Glossary

The OParl objects and terms you meet when using oparl. For the option reference see the README and the cookbook in Usage.md.

The standard

OParl. An open standard for read-only access to council information systems (Ratsinformationssysteme, RIS) in Germany — the systems municipalities use to publish meetings, agendas, motions and decisions. Maintained by OKF Deutschland and Vitako; current version 1.1 (2018), backwards-compatible with 1.0 (2016). Spec: https://oparl.org/spezifikation/.

Ratsinformationssystem (RIS). The software behind a council’s public portal. Common products with OParl support: SD.NET RIM (Sternberg), Session/SessionNet (Somacos), more! rubin, ALLRIS (CC e-gov).

Endpoint registry. The public list of OParl servers at https://dev.oparl.org/api/endpoints. It caches each server’s System object from its last fetch (fetched), and it is rarely updated. Some entries are duplicates or aggregators (Politik bei Uns, München Transparent).

Curated endpoint list (endpoints, --source). Shipped with this tool: OParl servers the registry lacks, and a live check of every registry entry. oparl endpoints lists both (source: registry or curated). checked is the day of the last check, working its result, problem the reason it failed, and replacedBy the new URL of a server that moved. The maintainers refresh it with npm run check-endpoints, which checks a failing endpoint twice before recording it as down. When the registry cannot be reached, endpoints lists the curated entries alone and says so on stderr. --search matches title, URL and note, ignoring case and accents, and falls back to the umlaut spellings (koeln → Köln) only when nothing matches literally.

Object type URI (type). Every OParl object has type, e.g. https://schema.oparl.org/1.1/Meeting; the version in the path tells 1.0 from 1.1.

Object id (id). Every object’s own URL. Objects reference each other by these URLs — follow them with oparl get <id>.

The objects

System (system). The entry point of a server: oparlVersion, vendor, product, and body, the URL of the list of bodies.

Body (bodies) — Körperschaft. An organisation running council work on the server, usually one municipality or district (name, ags — the official municipality key). A Body links its object lists: organization, person, meeting, paper and, in 1.1, agendaItem, consultation, file, membership, locationList, legislativeTermList.

Organization (list organization) — Gremium. A council, committee, district council, parliamentary group (Fraktion) or administrative unit. classification names the kind.

Person (list person). A council member or other person with a role; see Membership. Personal data — see DATA_LICENSE.md.

Membership (list membership) — Mitgliedschaft. A person’s membership in an organization, with role, startDate, endDate and votingRight.

Meeting (list meeting) — Sitzung. A meeting of one or more organizations: name, start, end, location, cancelled, the agendaItem list and protocol files.

AgendaItem (list agenda-item) — Tagesordnungspunkt (TOP). One item of a meeting’s agenda: number, name, public, result, the consultation it belongs to.

Paper (list paper) — Drucksache / Vorlage. A document the council deals with — an administration proposal (Beschlussvorlage), a motion (Antrag), an inquiry (Anfrage): reference (the document number), name, date, paperType, mainFile, auxiliaryFile, and its consultations.

Consultation (list consultation) — Beratung. A paper being dealt with in a particular meeting and organization, with role (e.g. Entscheidung, Vorberatung) and authoritative.

File (list file) — Datei. A document attached to a paper or meeting: fileName, mimeType, accessUrl, downloadUrl. This CLI prints file metadata only; it does not download files.

Location (list location) — Ort. An address or room, often embedded in meetings.

LegislativeTerm (list legislative-term) — Wahlperiode. A council term with startDate and endDate. OParl 1.0 bodies embed these as an array instead of a list URL; list legislative-term then prints the embedded terms with pages: 0 and applies the date filters locally. A term without created/modified cannot be filtered on, so it is printed and the result’s note says so.

Lists and paging

Object list / page. A list is served in pages: data (the objects), pagination (optional counts) and links (first, self, last, and next on every page but the last). oparl list follows next; its result’s next is where it stopped. A page whose data holds anything but objects is rejected; a server that answers a list URL with a bare JSON array instead of a page (an SD.NET build in Essen) is read as a single page.

Filters. OParl defines created_since, created_until, modified_since, modified_until, limit and omit_internal for lists (--modified-since …). Servers are meant to support the date filters, but some ignore them or fail on them. SD.NET RIM servers answer a date window with no objects in it with HTTP 404 — the CLI then exits 4 “not found” although the list exists; repeat the call without the filter to tell the two apart. Each filter goes out once with the value you gave: it replaces the server’s own copy in a list URL or a next link, and it is set again on the target of a redirect, so every page is filtered alike.

Deleted objects (deleted: true). Servers may keep deleted objects in lists, marked deleted, so that syncing clients can remove them. A list only shows them with modified_since on some servers, and since oparl list keeps the last copy of a repeated id, a tombstone on a later page wins over the live copy on an earlier one.

Paging loop (looped). A server whose next link leads back to a page already fetched, or that keeps serving pages which add nothing — the same page, or an empty one, under ever-new ?page=n links. The walk gives up after three such pages in a row, lists each object once, sets looped: true, and keeps the server’s next so the list can be continued by hand. Why three: a page that repeats objects is also what an insertion into the list during the walk looks like.

Walk note (note). One sentence in a list/bodies result, also printed on stderr, saying why the walk stopped before the end of the list (a paging loop, or a next link the CLI refuses to follow) or which filter it could not apply.

This tool

Same-host rule. Links (next, list URLs) and redirects are only followed on the host they came from; an http: link on an https: server is upgraded. Anything else stops with “Refusing to follow …”. The same upgrade applies to what is printed: in a response fetched over https, http:// URLs on that host are shown as https://, so ids you pass back to list or get stay encrypted. A relative link ("body": "bodies") is resolved against the URL the answer actually came from — after a redirect, that is the redirect’s target, not the URL the request started at.

Server text in messages. Anything a server sends that ends up in an error message — an object’s type, an error message, a link, a content type — is first stripped of control characters, folded onto one line and cut to 200 characters. A hostile or man-in-the-middled endpoint could otherwise write terminal escape sequences (window title, colours, screen clearing) or fake an Error: line of the CLI’s own. In JSON output the same characters are escaped instead, so nothing is lost.

pages / next (list output). How many pages were fetched, and the link to continue — present whenever the last page fetched offered one, null at the end of the list and when the link leads back into a loop.