1.4.1 Mobile Anwendung

Eine Anwendung für mobile Endgeräte wie Smartphones und Tablets, nachfolgend “App” genannt, könnte das Ziel verfolgen, Nutzern unterwegs, sowie abseits vom Desktop-PC optimierten Zugriff auf ein parlamentarisches Informationssystem zu ermöglichen. Dies könnte auch zur Vereinfachung der bisherigen Prozesse beitragen, da Nutzerinnen z.B. die Möglichkeit gegeben werden kann, auf Einladungen zu reagieren, oder Protokolle zu lesen.

1.4.2 Integration in ein Webportal

Portallösungen bieten den Betreibern die Möglichkeit, Inhalte auf einer einheitlichen Weboberfläche zu veröffentlichen, die aus verschiedensten Quellen und Plattformen bereitgestellt werden. Ein Beispiel für die Realisierung eines solchen Integrations-Ansatzes wäre eine Kommune, die für ihre allgemeine Website eine Portallösung einsetzt und hier auch Inhalte aus dem kommunalen Ratsinformationssystem einspeisen und darstellen möchte. Vorteil einer solchen Einbindung, also der kontextbezogenen Darstellung von parlamentarischen Informationen im Gegensatz zu einem monolithischen parlamentarischen Informationssystem könnte sein, dass Nutzer in einer gewohnten und akzeptierten Oberfläche jeweils die relevanten Informationen erhalten, ohne sich an die ungewohnte Umgebung eines parlamentarischen Informationssystems gewöhnen zu müssen.

1.4.3 Meta-Suche

Die Ermöglichung einer nutzerfreundlichen Suche, die damit verbundene Indexierung von verschiedensten Dokumenteninhalten und die Kategorisierung von Inhalten kann eine sowohl konzeptionell als auch technisch anspruchsvolle Aufgabe sein. Angelehnt an das seit den Anfängen des Webs etablierte Modell der externen Web-Suchmaschine sind spezielle Suchmaschinen für OParl-konforme parlamentarische Informationssysteme denkbar. Solche Plattformen treten gegenüber dem OParl-Server als Client auf und rufen bestimmte oder sämtliche Informationen, die das System bereithält, ab. Vorbild sind die Robots oder Spider von Web-Suchmaschinen. Die abgerufenen Informationen können dann indexiert und je nach Anforderungen für eine gezielte Suche weiterverarbeitet werden.

1.4.4 Forschungsprojekt “Themenanalyse”

In einem Forschungsprojekt sollen Pro- und Contra-Argumentationen bei Ratsdiskussionen zum Ausbau von Stromtrassen identifiziert werden. Dazu nutzen die Mitarbeitenden des Forschungsprojektes die OParl-Schnittstellen der parlamentarischen Informationssysteme aller Kommunen entlang der geplanten überregionalen Trassen. Über diese einheitlichen Schnittstellen können sie insbesondere die relevanten Wortprotokolle abrufen und zum Beispiel in einem Werkzeug zur qualitativen Datenanalyse lokal verarbeiten.

1.5.1 Zwingende, empfohlene und optionale Anforderungen

Diese Spezifikation nutzt müssen, können und sollten in einer eindeutig definierten Art und Weise. Diese ist angelehnt an die Definitionen der Begriffe MUST, SHOULD und MAY (bzw. MUST NOT, SHOULD NOT und MAY NOT) aus RFC2119.⁹

Die Bedeutung im Einzelnen:

müssen/muss bzw. zwingend:

Die Erfüllung einer so gekennzeichneten Anforderung ist zwingend erforderlich.

Die Entsprechung in RFC2119 lautet “MUST”, “REQUIRED” oder “SHALL”.

nicht dürfen/darf nicht:

Dieses Stichwort kennzeichnet ein absolutes Verbot.

Die Entsprechung in RFC2119 lautet “MUST NOT” oder “SHALL NOT”.

sollten/sollte bzw. empfohlen:

Mit dem Wort sollten bzw. sollte sind empfohlene Anforderungen gekennzeichnet, die von jeder Implementierung erfüllt werden sollten. Eine Nichterfüllung ist als Nachteil zu verstehen, beispielsweise weil die Nutzerfreundlichkeit dadurch Einbußen erleidet, und sollte daher sorgfältig abgewogen werden.

Die Entsprechung in RFC2119 lautet “SHOULD” oder “RECOMMENDED”.

sollten nicht/sollte nicht bzw. nicht empfohlen:

Diese Formulierung wird verwendet, wenn unter gewissen Umständen Gründe existieren können, die ein bestimmtes Verhalten akzeptabel oder sogar nützlich erscheinen lassen, jedoch die Auswirkung des Verhaltens vor einer entsprechenden Implementierung verstanden und abgewogen werden sollten.

Die Entsprechung in RFC2119 lautet “SHOULD NOT” oder “NOT RECOMMENDED”.

dürfen/darf bzw. optional:

Mit dem Wort dürfen bzw. darf oder optional sind optionale Bestandteile gekennzeichnet. Ein Anbieter könnte sich entscheiden, den entsprechenden Bestandteil aufgrund besonderer Kundenanforderungen zu unterstützen, während andere diesen Bestandteil ignorieren könnten. Implementierer von Clients oder Servern dürfen in solchen Fällen nicht davon ausgehen, dass der jeweilige Kommunikationspartner den entsprechenden, optionalen Anteil unterstützt.

Die Entsprechung in RFC2119 lautet “MAY”.

1.5.2 Geschlechterspezifische Begrifflichkeiten

Um bei Begriffen wie Nutzer, Anwender, Betreiber etc. die sonst übliche Dominanz der männlichen Variante zu vermeiden, werden in diesem Dokument männliche und weibliche Varianten gemischt. Gemeint sind in allen Fällen Personen jeglichen Geschlechts.

1.5.3 Codebeispiele

Die in diesem Dokument aufgeführten Codebeispiele dienen der Veranschaulichung der beschriebenen Prinzipien. Es handelt sich um frei erfundene Daten.

Codebeispiele erheben insbesondere bei JSON-Code nicht den Anspruch auf syntaktische Korrektheit und Vollständigkeit. Dementsprechend können in Codebeispielen Auslassungen vorkommen, die mit ... gekennzeichnet werden.

1.5.4 Namespace-Präfixe für Objekt- und Datentypen

Bei der Erwähnung von Objekttypen, die in dieser Spezifikation beschrieben werden, wird in der Regel ein Präfix oparl: vor den Namen gesetzt, z. B. “oparl:Organization”. Damit soll verdeutlicht werden, dass der Objekttyp innerhalb der OParl-Spezifikation gemeint ist.

Das Präfix oparl: steht hierbei für die folgende Namespace-URL:

https://schema.oparl.org/1.1/

Dadurch kann eine Typenangabe wie oparl:Organization eindeutig in die folgende URL übersetzt werden:

https://schema.oparl.org/1.1/Organization

1.8.1 Kernteam

Stefan Graupner, Ernesto Ruge, Konstantin Schütze

1.8.2 OParl 1.0

Folgende Personen haben an OParl 1.0 mitgewirkt:

Jayan Areekadan, Jan Erhardt, Lucas Jacob, Jens Klessmann (*), Andreas Kuckartz (**), Babett Schalitz, Tim Scheuermann, Christine Siegfried (*), Ralf Sternberg, Marian Steinbach (*), Bernd Thiem, Thomas Tursics, Jakob Voss, Marianne Wulff(*)

1.8.3 OParl 1.1

Folgende Personen haben an OParl 1.1 mitgewirkt:

grindhold, Simeon Maxein, Sami Mussbach, Ralf Sternberg

(*): Initiator(in), (**): bis 4.7.2014

2.1.1 Aufbauen auf gängiger Praxis

Grundlage für die Erarbeitung der OParl-Spezifikation in der vorliegenden Version ist eine Analyse von aktuell (2012 bis 2016) in Deutschland etablierten parlamentarischen Informationssystemen und ihrer Nutzung. Erklärtes Ziel für diese erste Version ist es, mit möglichst geringem Entwicklungsaufwand auf Seite der Softwareanbieter und ebenso geringem Migrationsaufwand auf Seite der Betreiber zu einer Bereitstellung von parlamentarischen Informationen über eine OParl-API zu gelangen. Hierbei war es von entscheidender Bedeutung, dass sich die Informationsmodelle der einschlägigen Softwareprodukte stark ähneln. Für die OParl-Spezifikation wurde sozusagen ein Datenmodell als “gemeinsamer Nenner” auf Basis der gängigen Praxis konstruiert.

2.1.2 Verbesserung gegenüber dem Status Quo wo möglich

Dort, wo es dem Ziel der einfachen Implementierbarkeit und der einfachen Migration nicht im Weg steht, erlauben sich die Autoren dieser Spezifikation, auch Funktionen aufzunehmen, die noch nicht als gängige Praxis im Bereich der Ratsinformationssysteme bezeichnet werden können oder welche nur von einzelnen Systemen unterstützt werden. Solche Funktionen sind dann so integriert, dass sie nicht als zwingende Anforderung gelten.

Ein Beispiel für eine derartige Funktion ist die Abbildung von Geodaten im Kontext von Drucksachen (oparl:Paper), um beispielsweise die Lage eines Bauvorhabens, das in einer Beschlussvorlage behandelt wird, zu beschreiben. Zwar ist den Autoren nur ein einziges parlamentarisches Informationssystem¹⁰ in Deutschland bekannt, das Geoinformationen – und zwar in Form von Punktdaten, also einer Kombination aus Längen- und Breitengradangaben – mit Dokumenten verknüpft. Der Vorteil dieser Funktion ist jedoch anhand zahlreicher Anwendungsszenarien, wie z.B. dem Bauinformationssystem “Bürger baut Stadt”¹¹, belegbar. Somit ist in der vorliegenden OParl-Spezifikation die Möglichkeit beschrieben, Geodaten-Objekte einzubetten.

Die Angabe eines einzelnen Punktes ist dabei der einfachste Fall. Die Spezifikation erlaubt auch die Kodierung von mehreren Objekten, die Punkte, Linien oder Polygone repräsentieren können. Vgl. dazu oparl:Location.

Auch die Ausgabe einer Nur-Text-Version im Kontext der Datei (oparl:File), das den barrierefreien Zugriff auf Inhalte oder Indexierung für Volltextsuchfunktionen deutlich vereinfacht, ist eine Möglichkeit, die in der gängigen Praxis noch nicht zu finden ist. Ebenso die Möglichkeit, Beziehungen zwischen einzelnen Dateien herzustellen, um so z.B. von einer Datei zu anderen Dateien mit identischem Inhalt, aber in anderen technischen Formaten zu verweisen, etwa von einer ODT-Datei zu einer PDF-Version.

2.1.3 Selbstbeschreibungsfähigkeit

Ausgaben des Servers sollten so beschaffen sein, dass sie für menschliche Nutzerinnen weitgehend selbsterklärend sein können. Dies betrifft besonders die Benennung von Objekten und Objekteigenschaften.

Um den Kreis der Entwicklerinnen und Entwickler, die mit einer OParl-API arbeiten können, nicht unnötig einzuschränken, wird hierbei grundsätzlich und soweit sinnvoll auf englischsprachige Begrifflichkeiten gesetzt.

2.1.4 Erweiterbarkeit

Implementierer sollen in der Lage sein, über eine OParl-konforme Schnittstelle auch solche Informationen auszugeben, die nicht im Rahmen des OParl-Schemas abgebildet werden können. Dies bedeutet zum einen, dass ein System Objekttypen unterstützen und ausliefern darf, die nicht (oder noch nicht) im OParl-Schema beschrieben sind. Das bedeutet auch, dass Objekttypen so um eigene Eigenschaften erweitert werden können, die nicht im OParl Schema beschrieben sind.

Ein weiterer Aspekt betrifft die Abwärtskompatibilität, also die Kompatibilität von OParl-Clients mit zukünftigen Schnittstellen. So können beispielsweise zukünftige Erweiterungen des OParl-Schemas, etwa um neue Objekttypen, genauso durchgeführt werden, wie die Erweiterungen um herstellerspezifische Objekttypen. Ein Client muss diese Anteile nicht auswerten, sofern sie nicht für die Aufgabe des Clients relevant sind. Es bedeutet im Umkehrschluss allerdings auch, dass ein Client nicht fehlschlagen darf, falls derartige Erweiterungen vorhanden sind.

2.1.5 Browseability/Verlinkung

Klassische Webservice-Schnittstellen erfordern von den Entwicklern vollständige Kenntnis der angebotenen Einstiegspunkte und Zugriffsmethoden, gepaart mit sämtlichen unterstützten URL-Parametern, um den vollen Funktionsumfang der Schnittstelle ausschöpfen zu können.

Parlamentarische Informationen sind weitgehend in Form von Graphen aufgebaut. Das bedeutet, dass Objekte häufig mit einer Vielzahl anderer Objekte verknüpft sind. So ist eine Person beispielsweise Mitglied in mehreren Gremien, das Gremium hat mehrere Sitzungen abgehalten und zu diesen Sitzungen gibt es jeweils zahlreiche Drucksachen, die ihrerseits wieder zahlreiche Dokumente enthalten.

Eine OParl-Schnittstelle gibt jedem einzelnen Objekt eine eindeutige Adresse, eine URL. Somit kann die Schnittstelle den Verweis von einem Objekt, beispielsweise einem Gremium, auf ein anderes Objekt, etwa ein Mitglied des Gremiums, dadurch ausgeben, dass im Kontext des Gremiums die URL des Mitglieds ausgeben wird. Der Client kann somit ausgehend von einem bestimmten Objekt die zugehörigen Objekte im System finden, indem er einfach den angebotenen URLs folgt. Dieses Prinzip wird auch “Follow Your Nose”¹² genannt.

2.3.1 URL-Kanonisierung

Um Objekte eindeutig identifizieren zu können ist es notwendig, dass ein Server für ein Objekt genau eine unveränderliche URL benutzt. Diese Festlegung auf genaue eine eindeutige URL wird Kanonisierung genannt. Ein Server muss deshalb für jedes seiner Objekte eine kanonische URL bestimmen können.

Es wird empfohlen keine IP-Adressen in URLs zu benutzen, sondern einen mit Bedacht gewählten Hostnamen einzusetzen. Das ist vor allem im Hinblick auf die Langlebigkeit der URLs wichtig.

Um die Kanonisierung zu gewährleisten sollten OParl-Server so konfiguriert werden, dass sie nur über eine bestimmte Domain erreichbar sind. OParl-Server sollten dagegen möglichst nicht nur über eine IP-Addresse sowieso möglichst auch nicht über weitere, nicht kanonische URLs erreichbar sein.

Wenn ein Server auch durch eine nicht-kanonische URL erreichbar ist, dann sollte eine entsprechende HTTP-Anfrage mit einer Weiterleitung auf die entsprechende kanonische URL und HTTP-Status-Code 301 beantwortet werden. Zur Überprüfung kann z.B. der Host-Header einer HTTP-Anfrage verwendet werden.

Beim Pfad-Bestandteil der URL müssen Server-Implementierer darüber hinaus beachten, dass zur kanonischen Schreibweise auch die Groß- und Kleinschreibung, die Anzahl von Schrägstrichen als Pfad-Trennzeichen und die Anzahl von führenden Nullen vor numerischen URL-Bestandteilen gehört.

Die Kanonisierung umfasst auch den Query-String-Bestandteil der URL. Wie auch beim Pfad gilt, dass für jeden Parameter und jeden Wert im Query-String genau eine kanonische Schreibweise gelten muss.

Darüber hinaus sollte der Server-Implementierer darauf achten, Query-String-Parameter immer nach demselben Prinzip zu sortieren. Als Beispiel: Die beiden URLs

https://oparl.example.org/members?body=1&committee=2
https://oparl.example.org/members?committee=2&body=1

unterscheiden sich lediglich in der Reihenfolge der Query-String-Parameter. Da sie jedoch nicht identisch sind, könnten Clients annehmen, dass beide URLs verschiedene Objekte repräsentieren.

Clients sollen die vom Server gelieferten URLs bei Anzeige, Speicherung und Weiterverarbeitung nicht verändern.

2.3.2 HTTP und HTTPS

Der Einsatz des verschlüsselten HTTPS wird empfohlen. Bei Verwendung von HTTPS wird allen URLs “https://” voran gestellt, ansonsten beginnen URLs mit “http://”.

Aus Gründen der URL-Kanonisierung ist es zwingend notwendig, dass ein Server-Betreiber sich entweder für HTTP oder für HTTPS entscheidet. Es jedoch möglich, eine Weiterleitung (HTTP Status-Code 301) einzurichten. Eine Weiterleitung von HTTPS auf HTTP wird nicht empfohlen.

2.3.3 Langlebigkeit

Weiterhin sollen URLs langlebig sein, sodass sie möglichst lange zur Abfrage des dazugehörigen Objekts verwendet werden können.

In URLs sollten deshalb nur Eigenschaften des Objekts aufgenommen werden, die nicht verändert werden. Ändert sich beispielsweise die Kennung einer Drucksache im Verlauf ihrer Existenz, dann scheidet sie für die Bildung der URL aus.

Des Weiteren sollen Eigenschaften der Implementierung nicht sichtbar sein. Ist ein OParl-Server beispielsweise in PHP geschrieben, sollte dies nicht dazu führen, dass im Pfad ein Bestandteil wie “oparl.php/” erscheint.

Weitere Empfehlungen für langlebige URLs liefern Tim Berners-Lee¹⁴ sowie die Europäische Kommission¹⁵.

2.4.1 In OParl verwendete Datentypen

In OParl werden alle in JSON definierten Dateitypen verwendet:

object:

Objects entsprechen der Definition des Objects in RFC 7159 Section 4

array:

Arrays entsprechen der Definition des Arrays in RFC 7159 Section 5

integer:

Integers entsprechen der Definition des Integer-Parts der Number aus RFC 7159 Section 6

boolean:

Booleans entsprechen der Definition von Boolean in RFC 7159 Section 3

string:

Strings entsprechen der Definition der Unicode-Strings aus RFC 7159 Section 7

In OParl werden verschiedene String-Typen verwendet. Wenn von diesen Typen gesprochen wird, so wird automatisch ein JSON-String vorausgesetzt:

url:

Eine URL ist ein String, der entsprechend des URL-Kapitels formatiert wurde.

url (Object):

Eine URL mit in Klammern angehängtem Objektname beschreibt eine URL auf eben diesen Objekttypus.

date:

Entspricht einem Datum ohne Uhrzeit und ohne Zeitzone, wie sie im folgenden Abschnitt beschrieben werden.

date-time:

Entspricht einem Datum und einer Uhrzeit mit Zeitzone, wie sie im folgenden Abschnitt beschrieben werden.

2.4.2 Datums- und Zeitangaben

Für Datums- und Zeitangaben wird eine Spezielisierung der in ISO 8601 beschriebenen Formate verwendet. Ein Datum (date) muss muss die Form yyyy-mm-dd besitzen und ein Zeitpunkt (date-time) muss in der Form yyyy-mm-ddThh:mm:ss±hh:mm angegeben werden.

Beispiel für ein Datum: 1969-07-21

Beispiel für einen Zeitpunkt: 1969-07-21T02:56:00+00:00

2.4.3 null-Werte und leere Listen

JSON erlaubt es grundsätzlich, Eigenschaften mit dem Wert null zu versehen. Eigenschaften sollten nicht mit dem Wert null ausgegeben werden, wenn zu einer Eigenschaft keine Daten vorliegen. Obligatorische Eigenschaften dürfen nicht den Wert null haben.

Im Fall von Arrays erlaubt JSON grundsätzlich die Ausgabe von [] für leere Arrays. Wie bei null wird auch hier empfohlen, auf die Ausgabe einer Eigenschaft mit dem Wert [] zu verzichten, wenn zu einer Eigenschaft keine Daten vorliegen. Bei obligatorischen Eigenschaften muss jedoch eine leere Liste ausgegeben werden.

Bei nicht obligatorischen Eigenschaften sollte gleichermaßen auf die Ausgabe eines leeren Strings "" verzichtet werden.

2.5.1 Referenzierung von Objekten via URL

Bei der Referenzierung einzelner Objekte wird eine URL angegeben, welche auf das entsprechende Objekt verweist. Der Typ ist hierbei ein string (url: Objekt-ID). Ein Beispiel hierfür ist subOrganizationOf in Organization:

{
  "id": "https://oparl.example.org/organization/1",
  "type": "https://schema.oparl.org/1.1/Organization",
  "subOrganizationOf": "https://oparl.example.org/organization/2"
  ...
}

Es kann auch eine Liste von Referenzen ausgegeben werden. Der Typ ist in diese Fall array of string (url: Objekt-ID).

Ein Beispiel hierfür ist meeting in Organization:

{
  "id": "https://oparl.example.org/organization/1",
  "type": "https://schema.oparl.org/1.1/Organization",
  "meeting": [
    "https://oparl.example.org/meeting/1",
    "https://oparl.example.org/meeting/2",
    "https://oparl.example.org/meeting/3",
  ]
  ...
}

2.5.2 Interne Ausgabe von Objekten

Objekte können auch intern ausgegeben werden. Dabei wird das gesamte Objekt als Wert eines Attributs angegeben. Ein Beispiel für ein internes Objekt ist location in oparl:Body:

{
  "id": "https://oparl.example.org/body/1",
  "type": "https://schema.oparl.org/1.1/Body",
  "location": {
    "id": "https://oparl.example.org/location/1",
    "type": "https://schema.oparl.org/1.1/Location",
    "description": "Ratshausvorplatz 1, 12345 Beispielstadt"
  },
  ...
}

Ebenso kann eine Liste von Objekten intern ausgegeben werden. Hier das Beispiel des Attributes membership in oparl:Person.

{
  "id": "https://oparl.example.org/person/1",
  "type": "https://schema.oparl.org/1.1/Person",
  "membership": [
    {
      "id": "https://oparl.example.org/memberships/385",
      "organization": "https://oparl.example.org/organizations/5",
      "role": "Vorsitzende",
      "votingRight": true,
      "startDate": "2013-12-03"
    },
    {
      "id": "https://oparl.example.org/memberships/693",
      "organization": "https://oparl.example.org/organizations/9",
      "role": "Sachkundige Bürgerin",
      "votingRight": false,
      "startDate": "2013-12-03",
      "endDate": "2014-07-28"
    }
  ],
  ...
}

Bei der internen Ausgabe von Objekten darf der Server keine gelöschten Objekte ausgeben.

2.5.3 Externe Objektlisten

Es können auch Referenzen zu sogenannten externen Objektlisten angegeben werden. Die externe Liste enthält dann die betreffenden Objekte in Form einer Listenausgabe. Ein Beispiel dafür ist organization in oparl:Body.

oparl:Body:

{
  "id": "https://oparl.example.org/body/1",
  "type": "https://schema.oparl.org/1.1/Body",
  "organization": "https://oparl.example.org/body/1/organization"
  ...
}

Die externe Objektliste:

{
    "data": [
      {
        "id": "https://oparl.example.org/organization/1",
        "type": "https://schema.oparl.org/1.1/Organization",
        "name": "Organisation Nummer 1",
        ...
      },
      {
        "id": "https://oparl.example.org/organization/2",
        "type": "https://schema.oparl.org/1.1/Organization",
        "name": "Organisation Nummer 2",
        ...
      },
      {
        "id": "https://oparl.example.org/organization/3",
        "type": "https://schema.oparl.org/1.1/Organization",
        "name": "Organisation Nummer 3",
        ...
      },
    ],
    ...
}

2.5.4 Paginierung

Für externe Objektlisten ist eine Aufteilung sogenannte Listenseiten vorgesehen, wobei jede Listenseite eine eigene URL erhält. Das dient dazu, die bei der jeweiligen Anfrage übertragenen Datenmengen und Antwortzeiten zu begrenzen.

Die Entscheidung, ob eine externe Objektliste mit Paginierung ausgegeben wird, liegt allein beim Server. Bei Listen mit mehr als 100 Einträgen wird dies empfohlen.

Ein Server muss für eine stabile Sortierung von Listeneinträgen sorgen. Das heißt, dass die Sortierung der Einträge einem konstanten Prinzip folgt und sich nicht von Abfrage zu Abfrage ändert. Das kann z.B. durch die Sortierung von Objekten nach einer eindeutigen und unveränderlichen ID erreicht werden.

Jede Listenseite muss die Attribute folgenden Attribute enthalten:

• data (Array der intern ausgegebenen Objekte)

• pagination (Object)

• links (Object)

Für pagination sind die folgenden Attribute festgelegt, die alle optional sind:

• totalElements: Gibt die Gesamtanzahl der Objekte in der Liste an. Diese Zahl kann sich unter Umständen bis zum Aufruf der nächsten Listenseiten ändern.

• elementsPerPage: Gibt die Anzahl der Objekte pro Listenseite an. Dieser Wert muss auf allen Listenseiten bis auf die letzte gleich sein.

• currentPage: Gibt die aktuelle Seitenzahl in der Liste an.

• totalPages: Gibt die Gesamtanzahl der Seiten in der Liste an.

Für links sind folgende Attribute festgelegt, die bis auf next alle optional sind:

• first: URL der ersten Listenseite

• prev: URL der vorherigen Listenseite

• self: Die kanonische URL dieser Listenseite

• next: URL der nächsten Listen. Für alle Seiten bis auf die letzte ist die Angabe dieser URL zwingend.

• last: URL der letzten Listenseite

• web: s. web. Neu in OParl 1.1

{
    "data": [
        {...},
        {...},
        ...
    ],
    "pagination": {
        "totalElements": 50000,
        "elementsPerPage": 100,
        "currentPage": 3,
        "totalPages":500
    },
    "links": {
        "first": "https://oparl.example.org/organization/",
        "prev": "https://oparl.example.org/organization/?page=2",
        "self": "https://oparl.example.org/organization/?page=3",
        "next": "https://oparl.example.org/organization/?page=4",
        "last": "https://oparl.example.org/organization/?page=500",
        "web": "https://web.example.org/organization/?page=500"
    }
}

2.5.5 Filter

Externe Objektlisten können mit den URL-Parametern created_since, created_until, modified_since und modified_until eingeschränkt werden. Diese Parameter beziehen sich auf die entsprechenden Attribute der jeweiligen Objekte, wobei reservierte Zeichen URL-Kodiert werden müssen. Ein Server muss diese Parameter bei allen externen Objektlisten unterstützen.

Neu in OParl 1.1: Wenn ein Client den Parameter omit_internal mit dem Wert true angibt, dann soll der Server auf die Ausgabe von internen Listen verzichten. Konkret bedeutet das, dass die folgenden Attribute nicht ausgegeben werden müssen:

• auxiliaryFile in AgendaItem
• auxiliaryFile in Meeting
• auxiliaryFile in Paper
• location in Paper
• membership in Person
• agendaItem in Meeting
• legislativeTerm in Body

Die Filter werden vom Client benutzt, indem die gewünschten URL-Parameter an die URL der ersten Listenseite angehängt werden. Bei allen weiteren Seiten, genauer gesagt bei den Werten von links, muss der Server sicherzustellen, dass die verwendeten Filter erhalten bleiben.

Neu in OParl 1.1: Ein Server muss für den im nächsten Abschnitt beschrieben Aktualisierungsmechanismus auch die den Filtern entsprechenden gelöschten Objekte ausgeben, wenn der Parameter modified_since gesetzt ist (s. OParl 1.1). Wenn modified_since nicht gesetzt ist, dann dürfen die gelöschten Objekte nicht ausgegeben werden. Dadurch kann sich ein Client effizient darüber informieren, welche der Objekte in seinem lokalen Bestand gelöscht wurden.

Lautet die URL für eine Liste von Drucksachen wie folgt:

https://oparl.example.org/papers/

kann der Client die folgende URL bilden, um die Ausgabe der Liste auf Drucksachen einzuschränken, die seit dem 1. Januar 2014 veröffentlicht wurden:

https://oparl.example.org/papers/?created_since=2014-01-01T00%3A00%3A00%2B01%3A00

Mehrere Parameter können auch gemeinsam verwendet werden. So kann man z.B. eine Einschränkung vom 1.1.2014 bis zum 31.1.2014 vornehmen:

https://oparl.example.org/papers/?created_since=2014-01-01T00%3A00%3A00%2B01%3A00&created_until=2014-01-31T23%3A59%3A59%2B01%3A00

Die genannten URL-Parameter erwarten grundsätzlich eine vollständige date-time-Angabe.

Des Weiteren kann ein Client die Anzahl der Objekte pro Listenseite durch den URL-Parameter limit begrenzen, der sich auf das gleichnamige Attribut bezieht. Ein Client darf nicht erwarten, dass sich ein Server an seine limit-Anfrage hält.

2.5.6 Der Aktualisierungsmechanismus

Dieser Abschnitt ist neu in OParl 1.1.

Der Hauptnutzen der Filter ist die Möglichkeit, einen lokalen Datenbestand inkrementell zu aktualisieren.

Ein Client könnte z.B. am 1.1.2014 um 2:00 Uhr deutscher Zeit die Liste aller Drucksachen herunterladen und in einer Datenbank speichern.

https://oparl.example.org/papers/

Um den Datenbestand am nächsten Tag zu aktualisieren, ruft der Client dieselbe URL auf, diesmal jedoch mit dem Parameter modified_since mit dem Wert 2014-01-01T02:00:00+01:00 und mit omit_internal.

https://oparl.example.org/papers/?modified_since=2014-01-01T02%3A00%3A00%2B01%3A00&omit_internal=true

Diese Liste ist in der Regel deutlich kürzer als die Liste aller Objekte, sodass die Aktualisierung bedeutend schneller ist als der erste Abruf. Der Client muss außerdem nur noch eine deutlich kleinere Menge an Objekten in die Datenbank einfügen, aktualisieren oder löschen, um den gleichen Datenstand wie der Server zu haben.

2.7.1 Empfehlungen für Dateizugriffe

• Ein Server sollte die Verwendung von Kompression gemäß dem HTTP-Standard unterstützen.

• Ein Server sollte “Conditional GET”, insbesondere If-Modified-Since und If-None-Match sowie “Chunked GET” unterstützen.

• Die Ausgabe der HTTP-Header Last-Modified, Content-Length und ETag ist empfohlen.

• Bei gelöschten Dateien sollte der HTTP-Statuscode 410 verwendet werden.

2.7.2 Allgemeiner Zugriff und expliziter Download

Mit der im oparl:File zwingend anzugebenden Eigenschaft accessUrl liefert der Server dem Client eine URL, die dem allgemeinen Zugriff auf die Datei dient. Beim Zugriff auf dieser URL darf der Server nicht den Content-Disposition-Header mit dem Parameter attachment senden. ²²

Es wird daher empfohlen, zusätzlich eine Eigenschaft downloadUrl anzubieten. Beim Zugriff auf die Download-URL muss der Server in der HTTP-Antwort einen Content-Disposition-Header senden, der als ersten Parameter den Typ attachment enthält und mit dem filename-Parameter den Namen der Datei angibt.

Beispiel:

Content-Disposition: attachment; filename="2014-08-22 Rat Wortprotokoll.pdf"

3.2.1 Vollständigkeit

Alle regulär öffentlich abrufbaren Informationen sollten auch in OParl ausgegeben werden, solange dies nicht den Datenschutzbestimmungen widerspricht. Daher sind sämtliche Felder im Schema als empfohlen zu behandeln, wenn nicht explizit etwas anderes angegeben wurde.

3.2.2 Herstellerspezifische Erweiterungen

In OParl können zusätzliche, herstellerspezifische Eigenschaften hinzugefügt werden. Dazu wird diesen Eigenschaften ein Herstellerprefix vorangestellt. So könnte man z.B. oparl:Person um eine Faxnummer erweitern:

"BeispielHersteller:faxNumber": "012345678",

3.2.3 URL-Pfade in den Beispielen

OParl-Clients wissen nichts vom Aufbau von Pfaden innerhalb von URLs, müssen dies nicht wissen, und es gibt deshalb in der OParl-Spezifikation keine Festlegungen dazu. Die in den Beispielen verwendeten URLs zeigen einen möglichen Weg zur Umsetzungen der Empfehlungen in URLs.

3.3.1 id

Die Eigenschaft id enthält den eindeutigen Bezeichner des Objekts, nämlich seine URL. Dies ist ein zwingendes Merkmal für jedes Objekt.

3.3.2 type

Objekttypenangabe des Objekts, zwingend für jedes Objekt. Der Wert ist eine Namespace-URL. Für die OParl-Objekttypen sind die folgenden URLs definiert:

3.3.3 name und shortName

Beide Eigenschaften können bei vielen Objekttypen genutzt werden um den Namen des Objekts anzugeben. Üblicherweise ist name eine Pflichteigenschaft für den ausgeschriebenen offiziellen Namen, während shortName optional angegeben werden kann. Dies ist dann zu empfehlen, wenn zu einem Namen eine kurze bzw. kompakte und eine längere, aber weniger nutzerfreundliche Variante existieren. So ist “Innenministerium” die Kurzform des offiziellen “Bundesministerium des Inneren”.

3.3.4 license

Mit license wird angegeben, unter welcher Lizenz die Daten des jeweiligen Objekts stehen. ²³

Wird license im oparl:System-Objekt oder am oparl:Body-Objekt verwendet, dann bedeutet das, dass alle Objekte dieses Systems bzw. der Körperschaft unter der angegebenen Lizenz veröffentlicht werden, sofern nicht das einzelne Objekt eine anders lautende Lizenz-URL angibt. Es wird empfohlen, die Lizenzinformation sofern möglich global am oparl:System Objekt mitzuteilen und auf redundante Informationen zu verzichten.

3.3.5 created

Datum und Uhrzeit der Erstellung des jeweiligen Objekts.

Diese Eigenschaft muss in allen Objekttypen angegeben werden. Neu in OParl 1.1: Diese Eigenschaft muss auch in Objekten ausgegeben werden, die intern ausgegeben werden.

3.3.6 modified

Diese Eigenschaft kennzeichnet stets Datum und Uhrzeit der letzten Änderung des jeweiligen Objekts.

Diese Eigenschaft muss - genau wie created - in allen Objekttypen angegeben werden. Neu in OParl 1.1: Diese Eigenschaft muss auch in Objekten ausgegeben werden, die intern ausgegeben werden.

Es ist zwingend, dass bei jeder Änderung eines Objekts der Wert dieses Attributs auf die zu diesem Zeitpunkt aktuelle Uhrzeit gesetzt wird, da ein Client in der Regel seinen Datenbestand nur auf Basis dieses Attributs verlustfrei aktualisieren kann.

3.3.7 keyword

Die Eigenschaft keyword dient der optionalen Kategorisierung eines Objekts.

3.3.8 web

Gibt die URL einer Website an, die das Objekt im Browser darstellt. Das ist z.B. die HTML-Ansicht eines parlamentarischen Informationssystems.

3.3.9 deleted

Falls das Objekt gelöscht wurde, muss dieses gemäß Kapitel 2.8 das Attribut deleted: true bekommen.

4.1.1 Weitere Änderungen

• Namespace-URLs werden durchgängig im Camel Case geschrieben
• Externe Objektlisten können ein web Attribut angeben
• Jedes Objekt des Schemas hat seine eigene Datei bekommen
• Definition eines Fehlerobjektes für die Ausnahmebehandlung
• sha1 veraltet und sha512 als Ersatz hinzugefügt. (s. https://shattered.io)
• Die Rückreferenz von Location auf Person wird zusätzlich auch noch eingebettet ausgeben (s. https://github.com/OParl/spec/issues/373)