1.4.1 Mobile Anwen­dung

Eine Anwen­dung für mobile Endge­räte wie Smart­pho­nes und Tablets, nach­fol­gend “App” genannt, könnte das Ziel verfol­gen, Nutzern unter­wegs, sowie abseits vom Desktop-PC opti­mier­ten Zugriff auf ein parla­men­ta­ri­sches Infor­ma­ti­ons­sys­tem zu ermög­li­chen. Dies könnte auch zur Verein­fa­chung der bishe­ri­gen Prozesse beitra­gen, da Nutze­rin­nen z.B. die Möglich­keit gege­ben werden kann, auf Einla­dun­gen zu reagie­ren, oder Proto­kolle zu lesen.

1.4.2 Inte­gra­tion in ein Webpor­tal

Portal­lö­sun­gen bieten den Betrei­bern die Möglich­keit, Inhalte auf einer einheit­li­chen Webo­ber­flä­che zu veröf­fent­li­chen, die aus verschie­dens­ten Quel­len und Platt­for­men bereit­ge­stellt werden. Ein Beispiel für die Reali­sie­rung eines solchen Inte­gra­ti­ons-Ansat­zes wäre eine Kommune, die für ihre allge­meine Website eine Portal­lö­sung einsetzt und hier auch Inhalte aus dem kommu­na­len Rats­in­for­ma­ti­ons­sys­tem einspei­sen und darstel­len möchte. Vorteil einer solchen Einbin­dung, also der kontext­be­zo­ge­nen Darstel­lung von parla­men­ta­ri­schen Infor­ma­tio­nen im Gegen­satz zu einem mono­li­thi­schen parla­men­ta­ri­schen Infor­ma­ti­ons­sys­tem könnte sein, dass Nutzer in einer gewohn­ten und akzep­tier­ten Ober­flä­che jeweils die rele­van­ten Infor­ma­tio­nen erhal­ten, ohne sich an die unge­wohnte Umge­bung eines parla­men­ta­ri­schen Infor­ma­ti­ons­sys­tems gewöh­nen zu müssen.

1.4.3 Meta-Suche

Die Ermög­li­chung einer nutzer­freund­li­chen Suche, die damit verbun­dene Inde­xie­rung von verschie­dens­ten Doku­men­ten­in­hal­ten und die Kate­go­ri­sie­rung von Inhal­ten kann eine sowohl konzep­tio­nell als auch tech­nisch anspruchs­volle Aufgabe sein. Ange­lehnt an das seit den Anfän­gen des Webs etablierte Modell der exter­nen Web-Such­ma­schine sind spezi­elle Such­ma­schi­nen für OParl-konforme parla­men­ta­ri­sche Infor­ma­ti­ons­sys­teme denk­bar. Solche Platt­for­men treten gegen­über dem OParl-Server als Client auf und rufen bestimmte oder sämt­li­che Infor­ma­tio­nen, die das System bereithält, ab. Vorbild sind die Robots oder Spider von Web-Such­ma­schi­nen. Die abge­ru­fe­nen Infor­ma­tio­nen können dann inde­xiert und je nach Anfor­de­run­gen für eine gezielte Suche weiter­ver­ar­bei­tet werden.

1.4.4 Forschungs­pro­jekt “Themen­ana­lyse”

In einem Forschungs­pro­jekt sollen Pro- und Contra-Argu­men­ta­tio­nen bei Rats­dis­kus­sio­nen zum Ausbau von Strom­tras­sen iden­ti­fi­ziert werden. Dazu nutzen die Mitar­bei­ten­den des Forschungs­pro­jek­tes die OParl-Schnitt­stel­len der parla­men­ta­ri­schen Infor­ma­ti­ons­sys­teme aller Kommu­nen entlang der geplan­ten über­re­gio­na­len Tras­sen. Über diese einheit­li­chen Schnitt­stel­len können sie insbe­son­dere die rele­van­ten Wort­pro­to­kolle abru­fen und zum Beispiel in einem Werk­zeug zur quali­ta­ti­ven Daten­ana­lyse lokal verar­bei­ten.

1.5.1 Zwin­gende, empfoh­lene und optio­nale Anfor­de­run­gen

Diese Spezi­fi­ka­tion nutzt müssen, können und soll­ten in einer eindeu­tig defi­nier­ten Art und Weise. Diese ist ange­lehnt an die Defi­ni­tio­nen der Begriffe MUST, SHOULD und MAY (bzw. MUST NOT, SHOULD NOT und MAY NOT) aus RFC2119.⁹

Die Bedeu­tung im Einzel­nen:

müssen/muss bzw. zwin­gend:

Die Erfül­lung einer so gekenn­zeich­ne­ten Anfor­de­rung ist zwin­gend erfor­der­lich.

Die Entspre­chung in RFC2119 lautet “MUST”, “REQUIRED” oder “SHALL”.

nicht dürfen/darf nicht:

Dieses Stich­wort kenn­zeich­net ein abso­lu­tes Verbot.

Die Entspre­chung in RFC2119 lautet “MUST NOT” oder “SHALL NOT”.

soll­ten/sollte bzw. empfoh­len:

Mit dem Wort soll­ten bzw. sollte sind empfoh­lene Anfor­de­run­gen gekenn­zeich­net, die von jeder Imple­men­tie­rung erfüllt werden soll­ten. Eine Nicht­er­fül­lung ist als Nach­teil zu verste­hen, beispiels­weise weil die Nutzer­freund­lich­keit dadurch Einbu­ßen erlei­det, und sollte daher sorg­fäl­tig abge­wo­gen werden.

Die Entspre­chung in RFC2119 lautet “SHOULD” oder “RECOMMENDED”.

soll­ten nicht/sollte nicht bzw. nicht empfoh­len:

Diese Formu­lie­rung wird verwen­det, wenn unter gewis­sen Umstän­den Gründe exis­tie­ren können, die ein bestimm­tes Verhal­ten akzep­ta­bel oder sogar nütz­lich erschei­nen lassen, jedoch die Auswir­kung des Verhal­tens vor einer entspre­chen­den Imple­men­tie­rung verstan­den und abge­wo­gen werden soll­ten.

Die Entspre­chung in RFC2119 lautet “SHOULD NOT” oder “NOT RECOMMENDED”.

dürfen/darf bzw. optio­nal:

Mit dem Wort dürfen bzw. darf oder optio­nal sind optio­nale Bestand­teile gekenn­zeich­net. Ein Anbie­ter könnte sich entschei­den, den entspre­chen­den Bestand­teil aufgrund beson­de­rer Kundenan­for­de­run­gen zu unter­stüt­zen, während andere diesen Bestand­teil igno­rie­ren könn­ten. Imple­men­tie­rer von Clients oder Servern dürfen in solchen Fällen nicht davon ausge­hen, dass der jewei­lige Kommu­ni­ka­ti­ons­part­ner den entspre­chen­den, optio­na­len Anteil unter­stützt.

Die Entspre­chung in RFC2119 lautet “MAY”.

1.5.2 Geschlech­ter­spe­zi­fi­sche Begriff­lich­kei­ten

Um bei Begrif­fen wie Nutzer, Anwen­der, Betrei­ber etc. die sonst übli­che Domi­nanz der männ­li­chen Vari­ante zu vermei­den, werden in diesem Doku­ment männ­li­che und weib­li­che Vari­an­ten gemischt. Gemeint sind in allen Fällen Perso­nen jegli­chen Geschlechts.

1.5.3 Code­bei­spiele

Die in diesem Doku­ment aufge­führ­ten Code­bei­spiele dienen der Veran­schau­li­chung der beschrie­be­nen Prin­zi­pien. Es handelt sich um frei erfun­dene Daten.

Code­bei­spiele erhe­ben insbe­son­dere bei JSON-Code nicht den Anspruch auf syntak­ti­sche Korrekt­heit und Voll­stän­dig­keit. Dement­spre­chend können in Code­bei­spie­len Auslas­sun­gen vorkom­men, die mit ... gekenn­zeich­net werden.

1.5.4 Name­space-Präfixe für Objekt- und Daten­ty­pen

Bei der Erwäh­nung von Objekt­ty­pen, die in dieser Spezi­fi­ka­tion beschrie­ben werden, wird in der Regel ein Präfix oparl: vor den Namen gesetzt, z. B. “oparl:Orga­ni­za­tion”. Damit soll verdeut­licht werden, dass der Objekt­typ inner­halb der OParl-Spezi­fi­ka­tion gemeint ist.

Das Präfix oparl: steht hier­bei für die folgende Name­space-URL:

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

Dadurch kann eine Typen­an­gabe wie oparl:Organization eindeu­tig in die folgende URL über­setzt werden:

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

1.8.1 Kern­team

Stefan Graup­ner, Erne­sto Ruge, Konstan­tin Schütze

1.8.2 OParl 1.0

Folgende Perso­nen haben an OParl 1.0 mitge­wirkt:

Jayan Aree­ka­dan, Jan Erhardt, Lucas Jacob, Jens Kless­mann (*), Andreas Kuck­artz (**), Babett Scha­litz, Tim Scheu­er­mann, Chris­tine Sieg­fried (*), Ralf Stern­berg, Marian Stein­bach (*), Bernd Thiem, Thomas Tursics, Jakob Voss, Mari­anne Wulff(*)

1.8.3 OParl 1.1

Folgende Perso­nen haben an OParl 1.1 mitge­wirkt:

grind­hold, Simeon Maxein, Sami Muss­bach, Ralf Stern­berg

(*): Initia­tor(in), (**): bis 4.7.2014

2.1.1 Aufbauen auf gängi­ger Praxis

Grund­lage für die Erar­bei­tung der OParl-Spezi­fi­ka­tion in der vorlie­gen­den Version ist eine Analyse von aktu­ell (2012 bis 2016) in Deutsch­land etablier­ten parla­men­ta­ri­schen Infor­ma­ti­ons­sys­te­men und ihrer Nutzung. Erklär­tes Ziel für diese erste Version ist es, mit möglichst gerin­gem Entwick­lungs­auf­wand auf Seite der Soft­wa­rean­bie­ter und ebenso gerin­gem Migra­ti­ons­auf­wand auf Seite der Betrei­ber zu einer Bereit­stel­lung von parla­men­ta­ri­schen Infor­ma­tio­nen über eine OParl-API zu gelan­gen. Hier­bei war es von entschei­den­der Bedeu­tung, dass sich die Infor­ma­ti­ons­mo­delle der einschlä­gi­gen Soft­wa­re­pro­dukte stark ähneln. Für die OParl-Spezi­fi­ka­tion wurde sozu­sa­gen ein Daten­mo­dell als “gemein­sa­mer Nenner” auf Basis der gängi­gen Praxis konstru­iert.

2.1.2 Verbes­se­rung gegen­über dem Status Quo wo möglich

Dort, wo es dem Ziel der einfa­chen Imple­men­tier­bar­keit und der einfa­chen Migra­tion nicht im Weg steht, erlau­ben sich die Auto­ren dieser Spezi­fi­ka­tion, auch Funk­tio­nen aufzu­neh­men, die noch nicht als gängige Praxis im Bereich der Rats­in­for­ma­ti­ons­sys­teme bezeich­net werden können oder welche nur von einzel­nen Syste­men unter­stützt werden. Solche Funk­tio­nen sind dann so inte­griert, dass sie nicht als zwin­gende Anfor­de­rung gelten.

Ein Beispiel für eine derar­tige Funk­tion ist die Abbil­dung von Geoda­ten im Kontext von Druck­sa­chen (oparl:Paper), um beispiels­weise die Lage eines Bauvor­ha­bens, das in einer Beschluss­vor­lage behan­delt wird, zu beschrei­ben. Zwar ist den Auto­ren nur ein einzi­ges parla­men­ta­ri­sches Infor­ma­ti­ons­sys­tem¹⁰ in Deutsch­land bekannt, das Geoin­for­ma­tio­nen – und zwar in Form von Punkt­da­ten, also einer Kombi­na­tion aus Längen- und Brei­ten­grad­an­ga­ben – mit Doku­men­ten verknüpft. Der Vorteil dieser Funk­tion ist jedoch anhand zahl­rei­cher Anwen­dungs­sze­na­rien, wie z.B. dem Bauin­for­ma­ti­ons­sys­tem “Bürger baut Stadt”¹¹, beleg­bar. Somit ist in der vorlie­gen­den OParl-Spezi­fi­ka­tion die Möglich­keit beschrie­ben, Geoda­ten-Objekte einzu­bet­ten.

Die Angabe eines einzel­nen Punk­tes ist dabei der einfachste Fall. Die Spezi­fi­ka­tion erlaubt auch die Kodie­rung von mehre­ren Objek­ten, die Punkte, Linien oder Poly­gone reprä­sen­tie­ren können. Vgl. dazu oparl:Location.

Auch die Ausgabe einer Nur-Text-Version im Kontext der Datei (oparl:File), das den barrie­re­freien Zugriff auf Inhalte oder Inde­xie­rung für Voll­text­such­funk­tio­nen deut­lich verein­facht, ist eine Möglich­keit, die in der gängi­gen Praxis noch nicht zu finden ist. Ebenso die Möglich­keit, Bezie­hun­gen zwischen einzel­nen Dateien herzu­stel­len, um so z.B. von einer Datei zu ande­ren Dateien mit iden­ti­schem Inhalt, aber in ande­ren tech­ni­schen Forma­ten zu verwei­sen, etwa von einer ODT-Datei zu einer PDF-Version.

2.1.3 Selbst­be­schrei­bungs­fä­hig­keit

Ausga­ben des Servers soll­ten so beschaf­fen sein, dass sie für mensch­li­che Nutze­rin­nen weit­ge­hend selbst­er­klä­rend sein können. Dies betrifft beson­ders die Benen­nung von Objek­ten und Objek­tei­gen­schaf­ten.

Um den Kreis der Entwick­le­rin­nen und Entwick­ler, die mit einer OParl-API arbei­ten können, nicht unnö­tig einzu­schrän­ken, wird hier­bei grund­sätz­lich und soweit sinn­voll auf englisch­spra­chige Begriff­lich­kei­ten gesetzt.

2.1.4 Erweiter­bar­keit

Imple­men­tie­rer sollen in der Lage sein, über eine OParl-konforme Schnitt­stelle auch solche Infor­ma­tio­nen auszu­ge­ben, die nicht im Rahmen des OParl-Sche­mas abge­bil­det werden können. Dies bedeu­tet zum einen, dass ein System Objekt­ty­pen unter­stüt­zen und auslie­fern darf, die nicht (oder noch nicht) im OParl-Schema beschrie­ben sind. Das bedeu­tet auch, dass Objekt­ty­pen so um eigene Eigen­schaf­ten erwei­tert werden können, die nicht im OParl Schema beschrie­ben sind.

Ein weite­rer Aspekt betrifft die Abwärts­kom­pa­ti­bi­li­tät, also die Kompa­ti­bi­li­tät von OParl-Clients mit zukünf­ti­gen Schnitt­stel­len. So können beispiels­weise zukünf­tige Erwei­te­run­gen des OParl-Sche­mas, etwa um neue Objekt­ty­pen, genauso durch­ge­führt werden, wie die Erwei­te­run­gen um herstel­ler­spe­zi­fi­sche Objekt­ty­pen. Ein Client muss diese Anteile nicht auswer­ten, sofern sie nicht für die Aufgabe des Clients rele­vant sind. Es bedeu­tet im Umkehrschluss aller­dings auch, dass ein Client nicht fehl­schla­gen darf, falls derar­tige Erwei­te­run­gen vorhan­den sind.

2.1.5 Brow­sea­bi­lity/Verlin­kung

Klas­si­sche Webser­vice-Schnitt­stel­len erfor­dern von den Entwick­lern voll­stän­dige Kennt­nis der ange­bo­te­nen Einstiegs­punkte und Zugriffs­me­tho­den, gepaart mit sämt­li­chen unter­stütz­ten URL-Para­me­tern, um den vollen Funk­ti­ons­um­fang der Schnitt­stelle ausschöp­fen zu können.

Parla­men­ta­ri­sche Infor­ma­tio­nen sind weit­ge­hend in Form von Graphen aufge­baut. Das bedeu­tet, dass Objekte häufig mit einer Viel­zahl ande­rer Objekte verknüpft sind. So ist eine Person beispiels­weise Mitglied in mehre­ren Gremien, das Gremium hat mehrere Sitzun­gen abge­hal­ten und zu diesen Sitzun­gen gibt es jeweils zahl­rei­che Druck­sa­chen, die ihrer­seits wieder zahl­rei­che Doku­mente enthal­ten.

Eine OParl-Schnitt­stelle gibt jedem einzel­nen Objekt eine eindeu­tige Adresse, eine URL. Somit kann die Schnitt­stelle den Verweis von einem Objekt, beispiels­weise einem Gremium, auf ein ande­res Objekt, etwa ein Mitglied des Gremi­ums, dadurch ausge­ben, dass im Kontext des Gremi­ums die URL des Mitglieds ausge­ben wird. Der Client kann somit ausge­hend von einem bestimm­ten Objekt die zuge­hö­ri­gen Objekte im System finden, indem er einfach den ange­bo­te­nen URLs folgt. Dieses Prin­zip wird auch “Follow Your Nose”¹² genannt.

2.3.1 URL-Kano­ni­sie­rung

Um Objekte eindeu­tig iden­ti­fi­zie­ren zu können ist es notwen­dig, dass ein Server für ein Objekt genau eine unver­än­der­li­che URL benutzt. Diese Fest­le­gung auf genaue eine eindeu­tige URL wird Kano­ni­sie­rung genannt. Ein Server muss deshalb für jedes seiner Objekte eine kano­ni­sche URL bestim­men können.

Es wird empfoh­len keine IP-Adres­sen in URLs zu benut­zen, sondern einen mit Bedacht gewähl­ten Host­na­men einzu­set­zen. Das ist vor allem im Hinblick auf die Lang­le­big­keit der URLs wich­tig.

Um die Kano­ni­sie­rung zu gewähr­leis­ten soll­ten OParl-Server so konfi­gu­riert werden, dass sie nur über eine bestimmte Domain erreich­bar sind. OParl-Server soll­ten dage­gen möglichst nicht nur über eine IP-Addresse sowieso möglichst auch nicht über weitere, nicht kano­ni­sche URLs erreich­bar sein.

Wenn ein Server auch durch eine nicht-kano­ni­sche URL erreich­bar ist, dann sollte eine entspre­chende HTTP-Anfrage mit einer Weiter­lei­tung auf die entspre­chende kano­ni­sche URL und HTTP-Status-Code 301 beant­wor­tet werden. Zur Über­prü­fung kann z.B. der Host-Header einer HTTP-Anfrage verwen­det werden.

Beim Pfad-Bestand­teil der URL müssen Server-Imple­men­tie­rer darüber hinaus beach­ten, dass zur kano­ni­schen Schreib­weise auch die Groß- und Klein­schrei­bung, die Anzahl von Schräg­stri­chen als Pfad-Trenn­zei­chen und die Anzahl von führen­den Nullen vor nume­ri­schen URL-Bestand­tei­len gehört.

Die Kano­ni­sie­rung umfasst auch den Query-String-Bestand­teil der URL. Wie auch beim Pfad gilt, dass für jeden Para­me­ter und jeden Wert im Query-String genau eine kano­ni­sche Schreib­weise gelten muss.

Darüber hinaus sollte der Server-Imple­men­tie­rer darauf achten, Query-String-Para­me­ter immer nach demsel­ben Prin­zip zu sortie­ren. Als Beispiel: Die beiden URLs

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

unter­schei­den sich ledig­lich in der Reihen­folge der Query-String-Para­me­ter. Da sie jedoch nicht iden­tisch sind, könn­ten Clients anneh­men, dass beide URLs verschie­dene Objekte reprä­sen­tie­ren.

Clients sollen die vom Server gelie­fer­ten URLs bei Anzeige, Spei­che­rung und Weiter­ver­ar­bei­tung nicht verän­dern.

2.3.2 HTTP und HTTPS

Der Einsatz des verschlüs­sel­ten HTTPS wird empfoh­len. Bei Verwen­dung von HTTPS wird allen URLs “https://” voran gestellt, ansons­ten begin­nen URLs mit “http://”.

Aus Grün­den der URL-Kano­ni­sie­rung ist es zwin­gend notwen­dig, dass ein Server-Betrei­ber sich entwe­der für HTTP oder für HTTPS entschei­det. Es jedoch möglich, eine Weiter­lei­tung (HTTP Status-Code 301) einzu­rich­ten. Eine Weiter­lei­tung von HTTPS auf HTTP wird nicht empfoh­len.

2.3.3 Lang­le­big­keit

Weiter­hin sollen URLs lang­le­big sein, sodass sie möglichst lange zur Abfrage des dazu­ge­hö­ri­gen Objekts verwen­det werden können.

In URLs soll­ten deshalb nur Eigen­schaf­ten des Objekts aufge­nom­men werden, die nicht verän­dert werden. Ändert sich beispiels­weise die Kennung einer Druck­sa­che im Verlauf ihrer Exis­tenz, dann schei­det sie für die Bildung der URL aus.

Des Weite­ren sollen Eigen­schaf­ten der Imple­men­tie­rung nicht sicht­bar sein. Ist ein OParl-Server beispiels­weise in PHP geschrie­ben, sollte dies nicht dazu führen, dass im Pfad ein Bestand­teil wie “oparl.php/” erscheint.

Weitere Empfeh­lun­gen für lang­le­bige URLs liefern Tim Berners-Lee¹⁴ sowie die Euro­päi­sche Kommis­sion¹⁵.

2.4.1 In OParl verwen­dete Daten­ty­pen

In OParl werden alle in JSON defi­nier­ten Datei­ty­pen verwen­det:

object:

Objects entspre­chen der Defi­ni­tion des Objects in RFC 7159 Section 4

array:

Arrays entspre­chen der Defi­ni­tion des Arrays in RFC 7159 Section 5

inte­ger:

Inte­gers entspre­chen der Defi­ni­tion des Inte­ger-Parts der Number aus RFC 7159 Section 6

boolean:

Booleans entspre­chen der Defi­ni­tion von Boolean in RFC 7159 Section 3

string:

Strings entspre­chen der Defi­ni­tion der Unicode-Strings aus RFC 7159 Section 7

In OParl werden verschie­dene String-Typen verwen­det. Wenn von diesen Typen gespro­chen wird, so wird auto­ma­tisch ein JSON-String voraus­ge­setzt:

url:

Eine URL ist ein String, der entspre­chend des URL-Kapi­tels forma­tiert wurde.

url (Object):

Eine URL mit in Klam­mern ange­häng­tem Objekt­name beschreibt eine URL auf eben diesen Objekt­ty­pus.

date:

Entspricht einem Datum ohne Uhrzeit und ohne Zeit­zone, wie sie im folgen­den Abschnitt beschrie­ben werden.

date-time:

Entspricht einem Datum und einer Uhrzeit mit Zeit­zone, wie sie im folgen­den Abschnitt beschrie­ben werden.

2.4.2 Datums- und Zeit­an­ga­ben

Für Datums- und Zeit­an­ga­ben wird eine Spezie­li­sie­rung der in ISO 8601 beschrie­be­nen Formate verwen­det. Ein Datum (date) muss muss die Form yyyy-mm-dd besit­zen und ein Zeit­punkt (date-time) muss in der Form yyyy-mm-ddThh:mm:ss±hh:mm ange­ge­ben werden.

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

Beispiel für einen Zeit­punkt: 1969-07-21T02:56:00+00:00

2.4.3 null-Werte und leere Listen

JSON erlaubt es grund­sätz­lich, Eigen­schaf­ten mit dem Wert null zu verse­hen. Eigen­schaf­ten soll­ten nicht mit dem Wert null ausge­ge­ben werden, wenn zu einer Eigen­schaft keine Daten vorlie­gen. Obli­ga­to­ri­sche Eigen­schaf­ten dürfen nicht den Wert null haben.

Im Fall von Arrays erlaubt JSON grund­sätz­lich die Ausgabe von [] für leere Arrays. Wie bei null wird auch hier empfoh­len, auf die Ausgabe einer Eigen­schaft mit dem Wert [] zu verzich­ten, wenn zu einer Eigen­schaft keine Daten vorlie­gen. Bei obli­ga­to­ri­schen Eigen­schaf­ten muss jedoch eine leere Liste ausge­ge­ben werden.

Bei nicht obli­ga­to­ri­schen Eigen­schaf­ten sollte glei­cher­ma­ßen auf die Ausgabe eines leeren Strings "" verzich­tet werden.

2.5.1 Refe­ren­zie­rung von Objek­ten via URL

Bei der Refe­ren­zie­rung einzel­ner Objekte wird eine URL ange­ge­ben, welche auf das entspre­chende Objekt verweist. Der Typ ist hier­bei ein string (url: Objekt-ID). Ein Beispiel hier­fü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 Refe­ren­zen ausge­ge­ben werden. Der Typ ist in diese Fall array of string (url: Objekt-ID).

Ein Beispiel hier­fü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 Objek­ten

Objekte können auch intern ausge­ge­ben werden. Dabei wird das gesamte Objekt als Wert eines Attri­buts ange­ge­ben. Ein Beispiel für ein inter­nes 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 Objek­ten intern ausge­ge­ben werden. Hier das Beispiel des Attri­bu­tes 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 inter­nen Ausgabe von Objek­ten darf der Server keine gelösch­ten Objekte ausge­ben.

2.5.3 Externe Objekt­lis­ten

Es können auch Refe­ren­zen zu soge­nann­ten exter­nen Objekt­lis­ten ange­ge­ben werden. Die externe Liste enthält dann die betref­fen­den Objekte in Form einer Listen­aus­gabe. 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 Objekt­liste:

{
    "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 Pagi­nie­rung

Für externe Objekt­lis­ten ist eine Auftei­lung soge­nannte Listen­sei­ten vorge­se­hen, wobei jede Listen­seite eine eigene URL erhält. Das dient dazu, die bei der jewei­li­gen Anfrage über­tra­ge­nen Daten­men­gen und Antwort­zei­ten zu begren­zen.

Die Entschei­dung, ob eine externe Objekt­liste mit Pagi­nie­rung ausge­ge­ben wird, liegt allein beim Server. Bei Listen mit mehr als 100 Einträ­gen wird dies empfoh­len.

Ein Server muss für eine stabile Sortie­rung von Listen­ein­trä­gen sorgen. Das heißt, dass die Sortie­rung der Einträge einem konstan­ten Prin­zip folgt und sich nicht von Abfrage zu Abfrage ändert. Das kann z.B. durch die Sortie­rung von Objek­ten nach einer eindeu­ti­gen und unver­än­der­li­chen ID erreicht werden.

Jede Listen­seite muss die Attri­bute folgen­den Attri­bute enthal­ten:

• data (Array der intern ausge­ge­be­nen Objekte)

• pagi­na­tion (Object)

• links (Object)

Für pagination sind die folgen­den Attri­bute fest­ge­legt, die alle optio­nal sind:

• totalElements: Gibt die Gesamtan­zahl der Objekte in der Liste an. Diese Zahl kann sich unter Umstän­den bis zum Aufruf der nächs­ten Listen­sei­ten ändern.

• elementsPerPage: Gibt die Anzahl der Objekte pro Listen­seite an. Dieser Wert muss auf allen Listen­sei­ten bis auf die letzte gleich sein.

• currentPage: Gibt die aktu­elle Seiten­zahl in der Liste an.

• totalPages: Gibt die Gesamtan­zahl der Seiten in der Liste an.

Für links sind folgende Attri­bute fest­ge­legt, die bis auf next alle optio­nal sind:

• first: URL der ersten Listen­seite

• prev: URL der vorhe­ri­gen Listen­seite

• self: Die kano­ni­sche URL dieser Listen­seite

• next: URL der nächs­ten Listen. Für alle Seiten bis auf die letzte ist die Angabe dieser URL zwin­gend.

• last: URL der letz­ten Listen­seite

• 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 Objekt­lis­ten können mit den URL-Para­me­tern created_since, created_until, modified_since und modified_until einge­schränkt werden. Diese Para­me­ter bezie­hen sich auf die entspre­chen­den Attri­bute der jewei­li­gen Objekte, wobei reser­vierte Zeichen URL-Kodiert werden müssen. Ein Server muss diese Para­me­ter bei allen exter­nen Objekt­lis­ten unter­stüt­zen.

Neu in OParl 1.1: Wenn ein Client den Para­me­ter omit_internal mit dem Wert true angibt, dann soll der Server auf die Ausgabe von inter­nen Listen verzich­ten. Konkret bedeu­tet das, dass die folgen­den Attri­bute nicht ausge­ge­ben 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ünsch­ten URL-Para­me­ter an die URL der ersten Listen­seite ange­hängt werden. Bei allen weite­ren Seiten, genauer gesagt bei den Werten von links, muss der Server sicher­zu­stel­len, dass die verwen­de­ten Filter erhal­ten blei­ben.

Neu in OParl 1.1: Ein Server muss für den im nächs­ten Abschnitt beschrie­ben Aktua­li­sie­rungs­me­cha­nis­mus auch die den Filtern entspre­chen­den gelösch­ten Objekte ausge­ben, wenn der Para­me­ter modified_since gesetzt ist (s. OParl 1.1). Wenn modified_since nicht gesetzt ist, dann dürfen die gelösch­ten Objekte nicht ausge­ge­ben werden. Dadurch kann sich ein Client effi­zi­ent darüber infor­mie­ren, welche der Objekte in seinem loka­len Bestand gelöscht wurden.

Lautet die URL für eine Liste von Druck­sa­chen wie folgt:

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

kann der Client die folgende URL bilden, um die Ausgabe der Liste auf Druck­sa­chen einzu­schrän­ken, die seit dem 1. Januar 2014 veröf­fent­licht wurden:

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

Mehrere Para­me­ter können auch gemein­sam verwen­det werden. So kann man z.B. eine Einschrän­kung vom 1.1.2014 bis zum 31.1.2014 vorneh­men:

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

Die genann­ten URL-Para­me­ter erwar­ten grund­sätz­lich eine voll­stän­dige date-time-Angabe.

Des Weite­ren kann ein Client die Anzahl der Objekte pro Listen­seite durch den URL-Para­me­ter limit begren­zen, der sich auf das gleich­na­mige Attri­but bezieht. Ein Client darf nicht erwar­ten, dass sich ein Server an seine limit-Anfrage hält.

2.5.6 Der Aktua­li­sie­rungs­me­cha­nis­mus

Dieser Abschnitt ist neu in OParl 1.1.

Der Haupt­nut­zen der Filter ist die Möglich­keit, einen loka­len Daten­be­stand inkre­men­tell zu aktua­li­sie­ren.

Ein Client könnte z.B. am 1.1.2014 um 2:00 Uhr deut­scher Zeit die Liste aller Druck­sa­chen herun­ter­la­den und in einer Daten­bank spei­chern.

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

Um den Daten­be­stand am nächs­ten Tag zu aktua­li­sie­ren, ruft der Client dieselbe URL auf, dies­mal jedoch mit dem Para­me­ter 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 deut­lich kürzer als die Liste aller Objekte, sodass die Aktua­li­sie­rung bedeu­tend schnel­ler ist als der erste Abruf. Der Client muss außer­dem nur noch eine deut­lich klei­nere Menge an Objek­ten in die Daten­bank einfü­gen, aktua­li­sie­ren oder löschen, um den glei­chen Daten­stand wie der Server zu haben.

2.7.1 Empfeh­lun­gen für Datei­zu­griffe

• Ein Server sollte die Verwen­dung von Kompres­sion gemäß dem HTTP-Stan­dard unter­stüt­zen.

• Ein Server sollte “Condi­tio­nal GET”, insbe­son­dere If-Modified-Since und If-None-Match sowie “Chun­ked GET” unter­stüt­zen.

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

• Bei gelösch­ten Dateien sollte der HTTP-Status­code 410 verwen­det werden.

2.7.2 Allge­mei­ner Zugriff und expli­zi­ter Down­load

Mit der im oparl:File zwin­gend anzu­ge­ben­den Eigen­schaft accessUrl liefert der Server dem Client eine URL, die dem allge­mei­nen Zugriff auf die Datei dient. Beim Zugriff auf dieser URL darf der Server nicht den Content-Disposition-Header mit dem Para­me­ter attachment senden. ²²

Es wird daher empfoh­len, zusätz­lich eine Eigen­schaft downloadUrl anzu­bie­ten. Beim Zugriff auf die Down­load-URL muss der Server in der HTTP-Antwort einen Content-Disposition-Header senden, der als ersten Para­me­ter den Typ attachment enthält und mit dem filename-Para­me­ter den Namen der Datei angibt.

Beispiel:

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

3.2.1 Voll­stän­dig­keit

Alle regu­lär öffent­lich abruf­ba­ren Infor­ma­tio­nen soll­ten auch in OParl ausge­ge­ben werden, solange dies nicht den Daten­schutz­be­stim­mun­gen wider­spricht. Daher sind sämt­li­che Felder im Schema als empfoh­len zu behan­deln, wenn nicht expli­zit etwas ande­res ange­ge­ben wurde.

3.2.2 Herstel­ler­spe­zi­fi­sche Erwei­te­run­gen

In OParl können zusätz­li­che, herstel­ler­spe­zi­fi­sche Eigen­schaf­ten hinzu­ge­fügt werden. Dazu wird diesen Eigen­schaf­ten ein Herstel­ler­pre­fix voran­ge­stellt. So könnte man z.B. oparl:Person um eine Faxnum­mer erwei­tern:

"BeispielHersteller:faxNumber": "012345678",

3.2.3 URL-Pfade in den Beispie­len

OParl-Clients wissen nichts vom Aufbau von Pfaden inner­halb von URLs, müssen dies nicht wissen, und es gibt deshalb in der OParl-Spezi­fi­ka­tion keine Fest­le­gun­gen dazu. Die in den Beispie­len verwen­de­ten URLs zeigen einen mögli­chen Weg zur Umset­zun­gen der Empfeh­lun­gen in URLs.

3.3.1 id

Die Eigen­schaft id enthält den eindeu­ti­gen Bezeich­ner des Objekts, nämlich seine URL. Dies ist ein zwin­gen­des Merk­mal für jedes Objekt.

3.3.2 type

Objekt­ty­pen­an­gabe des Objekts, zwin­gend für jedes Objekt. Der Wert ist eine Name­space-URL. Für die OParl-Objekt­ty­pen sind die folgen­den URLs defi­niert:

3.3.3 name und shortName

Beide Eigen­schaf­ten können bei vielen Objekt­ty­pen genutzt werden um den Namen des Objekts anzu­ge­ben. Übli­cher­weise ist name eine Pflich­tei­gen­schaft für den ausge­schrie­be­nen offi­zi­el­len Namen, während shortName optio­nal ange­ge­ben werden kann. Dies ist dann zu empfeh­len, wenn zu einem Namen eine kurze bzw. kompakte und eine längere, aber weni­ger nutzer­freund­li­che Vari­ante exis­tie­ren. So ist “Innen­mi­nis­te­rium” die Kurz­form des offi­zi­el­len “Bundes­mi­nis­te­rium des Inne­ren”.

3.3.4 license

Mit license wird ange­ge­ben, unter welcher Lizenz die Daten des jewei­li­gen Objekts stehen. ²³

Wird license im oparl:System-Objekt oder am oparl:Body-Objekt verwen­det, dann bedeu­tet das, dass alle Objekte dieses Systems bzw. der Körper­schaft unter der ange­ge­be­nen Lizenz veröf­fent­licht werden, sofern nicht das einzelne Objekt eine anders lautende Lizenz-URL angibt. Es wird empfoh­len, die Lizenz­in­for­ma­tion sofern möglich global am oparl:System Objekt mitzu­tei­len und auf redun­dante Infor­ma­tio­nen zu verzich­ten.

3.3.5 created

Datum und Uhrzeit der Erstel­lung des jewei­li­gen Objekts.

Diese Eigen­schaft muss in allen Objekt­ty­pen ange­ge­ben werden. Neu in OParl 1.1: Diese Eigen­schaft muss auch in Objek­ten ausge­ge­ben werden, die intern ausge­ge­ben werden.

3.3.6 modified

Diese Eigen­schaft kenn­zeich­net stets Datum und Uhrzeit der letz­ten Ände­rung des jewei­li­gen Objekts.

Diese Eigen­schaft muss – genau wie created – in allen Objekt­ty­pen ange­ge­ben werden. Neu in OParl 1.1: Diese Eigen­schaft muss auch in Objek­ten ausge­ge­ben werden, die intern ausge­ge­ben werden.

Es ist zwin­gend, dass bei jeder Ände­rung eines Objekts der Wert dieses Attri­buts auf die zu diesem Zeit­punkt aktu­elle Uhrzeit gesetzt wird, da ein Client in der Regel seinen Daten­be­stand nur auf Basis dieses Attri­buts verlust­frei aktua­li­sie­ren kann.

3.3.7 keyword

Die Eigen­schaft keyword dient der optio­na­len Kate­go­ri­sie­rung eines Objekts.

3.3.8 web

Gibt die URL einer Website an, die das Objekt im Brow­ser darstellt. Das ist z.B. die HTML-Ansicht eines parla­men­ta­ri­schen Infor­ma­ti­ons­sys­tems.

3.3.9 deleted

Falls das Objekt gelöscht wurde, muss dieses gemäß Kapi­tel 2.8 das Attri­but deleted: true bekom­men.

4.1.1 Weitere Ände­run­gen

• Name­space-URLs werden durch­gän­gig im Camel Case geschrie­ben
• Externe Objekt­lis­ten können ein web Attri­but ange­ben
• Jedes Objekt des Sche­mas hat seine eigene Datei bekom­men
• Defi­ni­tion eines Fehler­ob­jek­tes für die Ausnah­me­be­hand­lung
• sha1 veral­tet und sha512 als Ersatz hinzu­ge­fügt. (s. https://shat­te­red.io)
• Die Rück­re­fe­renz von Loca­tion auf Person wird zusätz­lich auch noch einge­bet­tet ausge­ben (s. https://github.com/OParl/spec/issues/373)