1 Einlei­tung

Dieses Doku­ment enthält die Spezi­fi­ka­tion des OParl Schnitt­stel­len-Stan­dards für parla­men­ta­ri­sche Infor­ma­ti­ons­sys­teme1. Es dient damit als Grund­lage für die Imple­men­tie­rung von OParl-konfor­men Server- und Clien­t­an­wen­dun­gen.

1.1 Was ist OParl?

OParl ist die Grup­pie­rung, die Initia­tor und Heraus­ge­ber der vorlie­gen­den Spezi­fi­ka­tion ist. An OParl wirken Verbände, zivil­ge­sell­schaft­li­che Orga­ni­sa­tio­nen und Initia­ti­ven und Soft­wa­rean­bie­ter sowie inter­es­sierte Einzel­per­so­nen mit.

Die vorlie­gende Spezi­fi­ka­tion beschreibt den OParl-Stan­dard. Dieser defi­niert eine Webser­vice­schnitt­stelle, die den anony­men, lesen­den Zugriff auf öffent­li­che Inhalte aus parla­men­ta­ri­schen Infor­ma­ti­ons­sys­te­men ermög­licht. Wie der Name “Webser­vice” ausdrückt, setzt diese Schnitt­stelle auf dem World Wide Web auf. Sie ermög­licht, dass parla­men­ta­ri­sche Infor­ma­tio­nen maschi­nen­les­bar als offene Daten (Open Data) veröf­fent­licht werden.

Die vorlie­gende Version ist die erste verab­schie­dete Version der Spezi­fi­ka­tion des OParl-Stan­dards.

1.2 Ziel­set­zung von OParl

OParl rich­tet sich an verschie­dene Nutzer­grup­pen und Stake­hol­der:

  • Verwal­tun­gen und andere poli­ti­sche Gremien in Gebiets­kör­per­schaf­ten
  • Bürger, poli­ti­sche Parteien und Orga­ni­sa­tio­nen
  • Open-Data-Initia­ti­ven
  • Wissen­schaft­ler
  • Anbie­ter von Server- und Soft­wa­re­pro­duk­ten im Umfeld von parla­men­ta­ri­schen Infor­ma­ti­ons­sys­te­men und Öffent­lich­keits­be­tei­li­gung

Die Gründe, warum Betrei­ber von parla­men­ta­ri­schen Infor­ma­ti­ons­sys­te­men den Zugriff darauf über eine stan­dar­di­sierte Schnitt­stelle ermög­li­chen soll­ten oder möch­ten, können viel­fäl­tig und je nach Nutzer­gruppe unter­schied­lich sein.

Ein zentra­les Argu­ment für Verwal­tung und poli­ti­sche Gremien, sei es in Gebiets­kör­per­schaf­ten oder auf Landes- oder Bundes­ebene, ist die Verpflich­tung der Parla­mente gegen­über der Bevöl­ke­rung, diese über die Fort­schritte der parla­men­ta­ri­schen Arbeit zu infor­mie­ren und auf dem Laufen­den zu halten. Ein erster Schritt, der Bevöl­ke­rung Einbli­cke in die Arbeit und Zugriff auf Doku­mente zu gewäh­ren, ist vieler­orts in den letz­ten Jahren durch Einfüh­rung von Rats­in­for­ma­ti­ons­sys­te­men mit anony­mem, lesen­dem Zugriff über das World Wide Web gemacht worden.

Die damit einge­schla­gene Rich­tung konse­quent weiter zu gehen, bedeu­tet, die Daten der parla­men­ta­ri­schen Infor­ma­ti­ons­sys­teme soweit offen zu legen, wie die Inhalte es erlau­ben. Es bedeu­tet, die Daten und Inhalte so univer­sell weiter­ver­wend­bar und so barrie­re­arm wie möglich anzu­bie­ten, dass jegli­che weitere Verwen­dung durch Dritte tech­nisch möglich ist. Der seit eini­ger Zeit etablierte Begriff für dieses Prin­zip heißt “Open Data”.

Open-Data-Initia­ti­ven können unter Rück­griff auf Rats­in­for­ma­ti­ons­sys­teme (RIS) mit OParl-Schnitt­stelle einfa­cher Doku­mente und Daten aus unter­schied­li­chen Gebiets­kör­per­schaf­ten in Open-Data-Kata­lo­gen verzeich­nen und so einfa­cher auffind­bar machen für die Weiter­ver­wen­dung durch Dritte.

Bürge­rin­nen und Bürger, poli­ti­sche Parteien und zivil­ge­sell­schaft­li­che Orga­ni­sa­tio­nen können einfa­cher auf Inhalte parla­men­ta­ri­scher Infor­ma­ti­ons­sys­teme zugrei­fen und diese entspre­chend ihren Inter­es­sen aufbe­rei­ten. Dies können beispiels­weise Visua­li­sie­run­gen von enthal­te­nen Daten, die Anrei­che­rung von Infor­ma­ti­ons­an­ge­bo­ten für spezi­elle Nutzer­grup­pen oder die Schaf­fung von Benut­ze­ro­ber­flä­chen mit beson­de­ren Funk­tio­nen für verschie­dene Endge­räte sein.

Das Inter­esse an parla­men­ta­ri­schen Infor­ma­tio­nen und an Anwen­dun­gen, die diese nutz­bar und auswert­bar machen, ist offen­sicht­lich vorhan­den. Die Entwick­ler der alter­na­ti­ven Rats­in­for­ma­ti­ons­sys­teme wie Frank­furt Gestal­ten2, Offe­nes Köln oder der OpenRuhr:RIS-Instan­zen (die letz­ten beiden wurden zusam­men­ge­führt in Poli­tik Bei Uns3) wissen zu berich­ten, wie viel Inter­esse den Projek­ten gerade aus Orten entge­gen gebracht wird, in denen derar­tige Systeme noch nicht verfüg­bar sind.

Die Anwen­dungs­mög­lich­kei­ten für parla­men­ta­ri­sche Infor­ma­tio­nen, wenn sie über eine Schnitt­stelle schnell und einfach abge­ru­fen werden können, sind viel­fäl­tig. Beispiele sind:

  • Apps für den Abruf auf mobi­len Endge­rä­ten
  • Möglich­kei­ten zur Wieder­gabe für Nutze­rin­nen und Nutzer mit Beein­träch­ti­gung des Sehver­mö­gens
  • Alter­na­tive und erwei­terte Such­mög­lich­kei­ten in Inhal­ten
  • Auswer­tung und Analyse von Themen, Inhal­ten, Spra­che etc.
  • Benach­rich­ti­gungs­funk­tio­nen beim Erschei­nen bestimm­ter Inhalte

Die Stan­dar­di­sie­rung dieses Zugriffs über die Gren­zen einzel­ner Systeme hinweg erlaubt zudem, diese Entwick­lun­gen auch geogra­phisch und poli­tisch grenz­über­schrei­tend zu denken. Damit steigt nicht nur die poten­zi­elle Nutzer­schaft einzel­ner Entwick­lun­gen. Auch das Poten­zial für Koope­ra­tio­nen zwischen Anwen­dungs­ent­wick­lern wächst.

Für Wissen­schaft­ler, die z. B. an verglei­chen­den Unter­su­chun­gen zu Vorgän­gen in verschie­de­nen Gebiets­kör­per­schaf­ten inter­es­siert sind, erge­ben sich ebenso viel­fäl­tige Möglich­kei­ten über mehrere RIS-Instan­zen hinweg auf entspre­chende Infor­ma­tio­nen zuzu­grei­fen und diese so einfa­cher in ihre Analy­sen einzu­be­zie­hen.

Darüber hinaus sind auch Moti­va­tio­nen inner­halb von Orga­ni­sa­tio­nen und Körper­schaf­ten erkenn­bar. So sollen parla­men­ta­ri­sche Infor­ma­ti­ons­sys­teme vieler­orts in verschie­denste Prozesse und hete­ro­gene System­land­schaf­ten inte­griert werden. Durch eine einheit­li­che Schnitt­stelle bieten sich effi­zi­ente Möglich­kei­ten zur Inte­gra­tion der Daten in ande­ren Systeme, wie beispiels­weise Webpor­tale.

Anbie­ter von Soft­wa­re­pro­duk­ten, die RIS-Lösun­gen anbie­ten, können ihren Kunden mit der Imple­men­ta­tion der OParl-Schnitt­stelle eine entspre­chende einheit­li­che Schnitt­stelle anbie­ten.

Ausführ­li­chere Beschrei­bun­gen eini­ger mögli­cher Anwen­dungs­sze­na­rien finden sich im Kapi­tel Nutzungs­sze­na­rien.

1.3 Trans­pa­renz und Betei­li­gung durch Open Data

Öffent­li­che Stel­len verfü­gen über viel­fäl­tige Infor­ma­tio­nen und Daten. Seit eini­gen Jahren sind zivil­ge­sell­schaft­li­che Orga­ni­sa­tio­nen sowie Poli­tik und Verwal­tung unter dem Schlag­wort Open Data inter­na­tio­nal und auch in Deutsch­land um eine stär­kere Öffnung dieser Daten bemüht4. Bei dem Ansatz Open Data5 geht es darum, diese Daten so bereit­zu­stel­len, dass Dritte diese einfa­cher finden und weiter­ver­wen­den können.

Die zehn Open-Data-Prin­zi­pien der Sunlight-Foun­da­tion6 beschrei­ben die Offen­heit von Daten­sät­zen. Wesent­lich dabei sind vor allem die einfa­che recht­li­che und die tech­ni­sche Offen­heit. Bei erste­rer geht es darum, dass Daten­sätze unter Nutzungs­be­stim­mun­gen bereit­ge­stellt werden, die kurz und verständ­lich formu­liert sind und mindes­tens jegli­che weitere Verwen­dung inklu­sive der kommer­zi­el­len erlau­ben, unter der Voraus­set­zung, dass bei der Weiter­ver­wen­dung die Quelle benannt wird. Bei der tech­ni­schen Offen­heit steht die Bereit­stel­lung von Daten­sät­zen in möglichst maschi­nen­les­ba­ren Forma­ten im Vorder­grund. Dies bedeu­tet, stär­ker struk­tu­rierte Daten­sätze sind in der Bereit­stel­lung zu bevor­zu­gen. Liegen Daten inner­halb einer Orga­ni­sa­tion in einer Daten­bank vor, so bietet es sich an, diese über eine Program­mier­schnitt­stelle (API) für Außen­ste­hende bereit­zu­stel­len.

Die Erfül­lung dieser recht­li­chen und tech­ni­schen Offen­heit erlaubt es im Falle von OParl Drit­ten – dies können Bürge­rin­nen und Bürger, Unter­neh­men, Forschungs­ein­rich­tun­gen oder auch andere Verwal­tungs­ein­hei­ten sein – die Verwal­tungs­da­ten wesent­lich unkom­pli­zier­ter für eigene Vorha­ben wie Anwen­dun­gen oder Visua­li­sie­run­gen einzu­set­zen. Mit dem Ansatz offe­ner Verwal­tungs­da­ten soll so erstens mehr Trans­pa­renz über Prozesse und Entschei­dun­gen in Poli­tik und Verwal­tung erreicht werden. Zwei­tens können Dritte auf Grund­lage dieser Daten leich­ter eigene Geschäfts­mo­delle verfei­nern oder neue entwi­ckeln. Drit­tens wird es auch öffent­li­chen Stel­len selbst erleich­tert bereits im öffent­li­chen Sektor exis­tie­rende Daten zu finden und weiter­zu­ver­wen­den.

Das Prin­zip offe­ner Daten bzw. offe­ner Verwal­tungs­da­ten über die Mini­mal­prin­zi­pien recht­li­cher und tech­ni­scher Offen­heit hinaus in die Tat umzu­set­zen, erfor­dert im Einzel­fall häufig eine Zusam­men­ar­beit von Daten­be­reit­stel­lern und poten­ti­el­len Daten­nut­zern. Die bloße Bereit­stel­lung einer OParl-konfor­men API wird weder die Einhal­tung der tech­ni­schen Prin­zi­pien, noch der weite­ren Open-Data-Prin­zi­pien voll­stän­dig garan­tie­ren. Viele Bestand­teile der OParl-Spezi­fi­ka­tion, die einen weit­ge­hend barrie­re­ar­men Zugang zu Infor­ma­tio­nen7 ermög­li­chen sollen, sind in der vorlie­gen­den Version noch optio­nal (Beispiel: Voll­texte von Doku­men­ten über die API abruf­bar machen). Andere Bestand­teile, die von Inter­esse wären, sind noch gar nicht von OParl abge­deckt (Beispiel: Abstim­mungs­er­geb­nisse). Grund dafür ist, dass sich OParl in einem frühen Stadium befin­det und primär am Status Quo der parla­men­ta­ri­schen Infor­ma­ti­ons­sys­teme ausge­rich­tet ist. Es liegt also auch weiter­hin an Verwal­tung und Poli­tik, durch einen verant­wor­tungs­vol­len Umgang mit den Syste­men die maxi­mal erreich­bare Trans­pa­renz zu bieten. Das fängt bei verfüg­ba­ren Doku­ment­for­ma­ten an (ein PDF mit digi­ta­lem Text weist weit weni­ger Barrie­ren auf, als ein gescann­ter Brief, der eben­falls als PDF gespei­chert wurde) und hört bei der verwen­de­ten Spra­che auf8.

1.4 Nutzungs­sze­na­rien

Für OParl sind verschie­dene Nutzungs­sze­na­rien denk­bar. Die Nach­fol­gende Auflis­tung soll einen klei­nen Über­blick geben, erhebt aber bei weitem keinen Anspruch auf Voll­stän­dig­keit:

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 Nomen­kla­tur

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.9

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.6 Daten­schutz

Gemäß der Grund­lage “öffent­li­che Daten nutzen, private Daten schüt­zen” hat Daten­schutz auch bei OParl eine hohe Prio­ri­tät. Hier­bei ist die deut­sche Daten­schutz-Gesetz­ge­bung zu beach­ten.

Um perso­nen­be­zo­gene Daten zu veröf­fent­li­chen, ist übli­cher­weise eine expli­zite Zustim­mung der betrof­fe­nen Person erfor­der­lich. Dies gilt für die beste­hende Webo­ber­flä­che des Rats­in­for­ma­ti­ons­sys­tems ebenso wie für die OParl- Schnitt­stelle. Beson­ders zu beach­ten sind hier­bei unter ande­rem E-Mail- Adres­sen, Anschrif­ten, Fotos und Anwe­sen­heits­lis­ten. Es wird empfoh­len, vor Veröf­fent­li­chung über die Schnitt­stelle den zustän­di­gen Daten­schutz­be­auf­trag­ten zu kontak­tie­ren.

1.7 OParl Gover­nance

Im Verlauf der Weiter­ent­wick­lung können wie bei jedem Stan­dar­di­sie­rungs­pro­zess Konflikte über die Ausrich­tung und die Imple­men­tie­rung entste­hen. Ist dies der Fall, so sollte als erstes der Issue Tracker auf Github für eine offene Diskus­sion und eine konstruk­tive Lösung verwen­det werden.

Sollte es auf Github wider Erwar­ten keine Lösung geben, wird die Entschei­dung an das OParl-Schlich­tungs­gre­mium weiter­ge­ge­ben. In diesem Gremium vertre­ten sind Entwick­ler, Anwen­der und Daten­be­reit­stel­ler, so dass eine ausge­wo­gene Weiter­ent­wick­lung im Inter­esse aller Akteure gewahrt bleibt.

Es ist natür­lich unab­hän­gig davon jeder­zeit erlaubt, einen Fork der OParl-Schnitt­stelle zu erstel­len und dort neue zunächst nicht mehr­heits­fä­hige Konzepte, Featu­res und Funk­tio­nen auszu­pro­bie­ren.

1.8 Auto­ren

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 Prin­zi­pien und Funk­tio­nen der Schnitt­stelle

2.1 Desi­gnprin­zi­pien

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­tem10 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”11, 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”12 genannt.

2.2 Zukunfts­si­cher­heit

Sollte in Zukunft eine zu OParl 1.0 inkom­pa­ti­ble Version 2.0 erschei­nen, kann ein Server beide Versio­nen gleich­zei­tig unter­stüt­zen, um mit OParl 1.0 Clients kompa­ti­bel zu blei­ben. Dazu muss der Server die OParl 2.0-Schnitt­stelle unter einer eige­nen URL paral­lel zur beste­hen­den OParl 1.0-Schnitt­stelle anbie­ten, siehe Kapi­tel System.

2.3 URLs

Aufbau einer URL
Aufbau einer URL

Den URLs (für Uniform Resource Loca­tors) kommt eine beson­dere Bedeu­tung zu und es werden deshalb eine Reihe von Anfor­de­run­gen an deren Aufbau und Eigen­schaf­ten gestellt. Die allge­meine Funk­ti­ons­weise von URLs ist in RFC 3986 beschrie­ben13.

Grund­sätz­lich müssen alle Zugriffe zustands­los erfol­gen können, also ohne Session­in­for­ma­tio­nen wie Cookies. Das bedeu­tet, dass alle Infor­ma­tio­nen, die zum Abru­fen eines Objekts nötig sind, in der URL vorhan­den sein müssen.

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-Lee14 sowie die Euro­päi­sche Kommis­sion15.

2.4 JSON-Ausgabe

Ein OParl-Server muss Objekte in Form von JSON ausge­ben. Die Abkür­zung JSON steht für “JavaS­cript Object Nota­tion”. Das JSON-Format ist in RFC 715916 beschrie­ben.

Sämt­li­che JSON-Ausgabe muss in UTF-8 ohne Byte Order Mark (BOM) gesche­hen. Dies entspricht RFC 7159 Section 8.117. Gemäß RFC 7159 Section 718 darf UTF-8 String-Esca­ping verwen­det werden. XML-/HTML-String-Esca­ping darf nicht verwen­det werden.

Eine Synta­x­über­sicht und weitere Imple­men­tie­rungs­hin­weise finden sich auf json.org.

Es ist gestat­tet, weitere zur JSON-Ausgabe seman­tisch iden­ti­sche Formate19 anzu­bie­ten. Da diese jedoch nicht Bestand­teil der Spezi­fi­ka­tion sind, soll­ten sich Clients nicht auf deren Vorhan­den­sein verlas­sen.

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 Objekt­lis­ten und Pagi­nie­rung

Oft wird für ein Attri­but kein Wert ausge­ge­ben, sondern ein ande­res Objekt oder eine Liste von Objek­ten. Dabei kann eine Refe­renz auf das Objekt bzw. die Objekt­liste ange­ge­ben werden, oder das Objekt bzw. die Objekt­list wird intern ausge­ge­ben. Beide Verfah­ren sollen im Folgen­den erklärt werden. Zu beach­ten ist, dass für jedes Liste­nat­tri­but fest­ge­legt ist, welches dieser Verfah­ren jeweils zu verwen­den ist. Diese Infor­ma­tion ist den Sche­ma­de­fi­ni­tio­nen zu entneh­men.

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.6 Cross-Origin Resource Sharing (CORS)

Wenn Webbrow­ser mittels Skript auf JSON-Ressour­cen zugrei­fen sollen unter­lie­gen diese Zugriffe übli­cher­weise einer Same-Origin-Policy (SOP). Das heißt, eine Anfrage ist nur an den Server zuläs­sig, der auch das initi­ie­rende Skript ausge­lie­fert hat. Anfra­gen an andere Server werden vom Brow­ser blockiert. Diese Einschrän­kung dient im Allge­mei­nen der Sicher­heit von Webbrow­sern.20

Um die Daten von OParl-Servern auch im Kontext von Weban­wen­dun­gen flexi­bel nutzen zu können, ist die Über­win­dung der SOP nötig. Hierzu dient Cross-Origin Resource Sharing (CORS)21. Mittels CORS kann ein Server mittei­len, dass bestimmte von ihm ausge­lie­ferte Ressour­cen auch inner­halb von Webappli­ka­tio­nen genutzt werden dürfen, die nicht vom selben Server ausge­lie­fert werden. Tech­nisch wird dies durch Ausgabe zusätz­li­cher HTTP-Header erreicht.

OParl-Server müssen für jegli­che Anfrage, die mit der Ausgabe von JSON-Daten beant­wor­tet wird (das sind alle Anfra­gen außer Datei­zu­griffe) den folgen­den HTTP-Antwort-Header senden:

Access-Control-Allow-Origin: *

Der HTTP-Antwort-Header Access-Control-Allow-Methods sollte darüber hinaus nicht gesetzt sein, oder muss die Methode GET bein­hal­ten.

Entwick­le­rin­nen von Weban­wen­dun­gen soll­ten sich darüber bewusst sein, dass durch die direkte Einbin­dung von Skrip­ten Drit­ter in ihre Anwen­dun­gen mögli­che Sicher­heits­ri­si­ken entste­hen. Für den Fall, dass ein OParl-Server, etwa in Folge einer Mani­pu­la­tion, Schad­code auslie­fert, könnte dieser unmit­tel­bar von Skrip­ten im Brow­ser ausge­führt werden.

2.7 Datei­zu­griffe

Mit dem Begriff “Datei” sind im Sinne dieser Spezi­fi­ka­tion alle Ressour­cen gemeint, die von einem OParl-Server zur Verfü­gung gestellt werden und deren Meta­da­ten über die JSON-API als oparl:File abge­ru­fen werden können. Es handelt sich dabei beispiels­weise um Text­do­ku­mente im PDF-Format oder Abbil­dun­gen im JPEG- oder PNG-Format.

Jede Datei muss dabei mit einer HTTP-GET-Anfrage abruf­bar sein.

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. 22

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"

2.8 Gelöschte Objekte

In OParl dürfen Objekte nicht einfach gelöscht werden, sodass unter der betref­fen­den URL kein gülti­ges Objekt ausge­lie­fert wird. Statt­des­sen wird ein soge­nann­tes soft delete verwen­det.

Hinter­grund ist, dass OParl-Clients bei der Aktua­li­sie­rung ihres Daten­be­stan­des, z.B. mit den Filtern modified_since bzw. created_since, erfah­ren können müssen, welche Objekte gelöscht wurden.

Dies wird durch die folgen­den Regeln gewähr­leis­tet.

Wenn ein Objekt gelöscht wird,

  • muss das Objekt das zusätz­li­che Attri­but deleted mit dem Wert true bekom­men
  • muss das Attri­but modified auf den Zeit­punkt der Löschung setzen
  • müssen die Attri­bute id, type und created erhal­ten blei­ben
  • dürfen alle weite­ren Attri­bute entfernt werden

Als HTTP-Status­code muss weiter­hin 200 verwen­det werden.

Neu in OParl 1.1: Die Objekte Legis­la­ti­veTerm, Member­ship, Agen­daItem und Consul­ta­tion dürfen nicht mehr einfach gelöscht werden. Um Kompa­ti­bi­li­tät zu OParl 1.0 zu gewähr­leis­ten muss weiter­hin der Wert modified aller Objekte aktua­li­siert werden, in die dieses Objekt einge­bet­tet war.

2.9 Ausnah­me­be­hand­lung

Wenn ein Server eine Anfrage nicht bear­bei­ten kann, z.B. weil die URL ungül­tig ist oder das ange­fragte Objekt nicht exis­tiert, dann sollte er mit dem entspre­chen­den HTTP-Status­code antwor­ten.

Ein Server sollte in diesem Fall ein Objekt ausge­ben, das die folgen­den 3 Attri­bute enthält:

  • type: Enthält als Wert die URL https://schema.oparl.org/1.1/Error
  • message: Eine Fehler­mel­dung, die zur Anzeige für einen Nutzer gedacht ist. Die Fehler­mel­dung sollte deshalb in der Spra­che der durch die Schnitt­stelle ausge­lie­fer­ten Inhalte verfasst sein
  • debug: Zusätz­li­che Infor­ma­tio­nen über den Fehler

Wenn ein Server ein solches Objekt ausgibt, dann muss er dazu einen HTTP-Status­code senden, der einen Fehler anzeigt.

Ein Client darf nicht voraus­set­zen, dass er im Fall eines Fehlers verwert­bare Infor­ma­tio­nen wie das oben beschrie­bene Fehler­ob­jekt erhält.

2.10 OParl Endpunkt

Als OParl Endpunkt bzw. Einsprungs­punkt zur Schnitt­stelle wird ein OParl:System Objekt genutzt. Falls auf einem HTTP-Host mehrere OParl-Schnitt­stel­len oder mehrere OParl Versio­nen paral­lel instal­liert sind, müssen diese eindeu­tige und vonein­an­der unab­hän­gige OParl-Endpunkte anbie­ten. Es ist aller­dings möglich, eine Liste von OParl:System-Objek­ten auszu­ge­ben, die z.B. auf verschie­dene OParl-Versio­nen einer Schnitt­stelle verwei­sen.

3 Schema

Dieses Kapi­tel beschreibt das Schema von OParl. Das Schema defi­niert die Objekt­ty­pen und ihre Eigen­schaf­ten. Darüber hinaus ist im Schema auch fest­ge­legt, in welcher Bezie­hung verschie­dene Objekt­ty­pen zu einan­der stehen.

OParl Objekttypen: Ein Überblick. Die Zahl an den Verbindungslinien entspricht der Anzahl der Attribute, die eine oder mehrere Verknüpfungen herstellen.
OParl Objekt­ty­pen: Ein Über­blick. Die Zahl an den Verbin­dungs­li­nien entspricht der Anzahl der Attri­bute, die eine oder mehrere Verknüp­fun­gen herstel­len.

3.1 Die Objekte

OParl nutzt folgen­den Objekte:

  • oparl:System
  • oparl:Body
  • oparl:Legis­la­ti­veTerm
  • oparl:Orga­ni­za­tion
  • oparl:Person
  • oparl:Member­ship
  • oparl:Meeting
  • oparl:Agen­daItem
  • oparl:Paper
  • oparl:Consul­ta­tion
  • oparl:File
  • oparl:Loca­tion

Einige Objekte werden intern in ande­ren Objek­ten ausge­ge­ben:

  • oparl:Legis­la­ti­veTerm wird intern in oparl:Body ausge­ge­ben
  • oparl:Member­ship wird intern in oparl:Person ausge­ge­ben
  • oparl:Agen­daItem wird intern in oparl:Meeting ausge­ge­ben
  • oparl:Consul­ta­tion wird intern in Paper ausge­ge­ben
  • oparl:File wird intern in oparl:Meeting, oparl:Agen­daItem und oparl:Paper ausge­ge­ben
  • oparl:Loca­tion wird intern in oparl:Body, oparl:Orga­ni­za­tion, oparl:Meeting und oparl:Paper ausge­ge­ben

Grund­sätz­lich muss jedes Objekt unter seiner ID abruf­bar sein – auch dann, wenn das Objekt in ande­ren Objek­ten intern ausge­ge­ben wird. Bei der inter­nen Ausgabe wird beim inter­nen Objekt auf die Rück­re­fe­renz auf das Elter­n­ob­jekt verzich­tet.

Als Beispiel hier eine Ausgabe von oparl:Meeting, in welchem ein oparl:File enthal­ten ist:

{
    "id": "https://oparl.example.org/meeting/281",
    "type": "https://schema.oparl.org/1.1/Meeting",
    "name": "4. Sitzung des Finanzausschusses",
    "start": "2013-01-04T08:00:00+01:00",
    "end": "2013-01-04T12:00:00+01:00",
    "invitation": {
        "id": "https://oparl.example.org/files/57739",
        "name": "Einladung",
        "fileName": "einladung.pdf",
        "mimeType": "application/pdf",
        "date": "2012-01-08",
        "modified": "2012-01-08T14:05:27+01:00",
        "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 82930,
        "accessUrl": "https://oparl.example.org/files/57739.pdf",
        "downloadUrl": "https://oparl.example.org/files/download/57739.pdf"
    }
    [...]
}

Das enthal­tene oparl:File muss auch einzeln abge­ru­fen werden können. Dabei kommt dann das Eltern-Objekt als zusätz­li­ches Attri­but hinzu.:

{
    "id": "https://oparl.example.org/files/57739",
    "type": "https://schema.oparl.org/1.1/File",
    "name": "Einladung",
    "fileName": "einladung.pdf",
    "mimeType": "application/pdf",
    "date": "2012-01-08",
    "modified": "2012-01-08T14:05:27+01:00",
    "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "size": 82930,
    "accessUrl": "https://oparl.example.org/files/57739.pdf",
    "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
    "meeting": [
        "https://oparl.example.org/meeting/281"
    ]
}

Das zusätz­li­che Attri­but ist ein Array, da es auch möglich ist, dass Dateien von mehre­ren Haupt­ob­jek­ten aus genutzt werden. Das kann z.B. bei oparl:Location vorkom­men:

{
    "id": "https://oparl.example.org/locations/29856",
    "type": "https://schema.oparl.org/1.1/File",
    "description": "Honschaftsstraße 312, Köln",
    "geojson": {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                7.03291,
                50.98249
            ]
        }
    },
    "meeting": [
        "https://oparl.example.org/meeting/281",
        "https://oparl.example.org/meeting/766",
        "https://oparl.example.org/meeting/1002"
    ],
    "paper": [
        "https://oparl.example.org/paper/749",
        "https://oparl.example.org/paper/861",
        "https://oparl.example.org/paper/1077"
    ]
}

3.2 Über­grei­fende Aspekte

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 Eigen­schaf­ten mit Verwen­dung in mehre­ren Objekt­ty­pen

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:

Typ (kurz) Name­space-URL
oparl:AgendaItem https://schema.oparl.org/1.1/Agen­daItem
oparl:Body https://schema.oparl.org/1.1/Body
oparl:Consultation https://schema.oparl.org/1.1/Consul­ta­tion
oparl:File https://schema.oparl.org/1.1/File
oparl:LegislativeTerm https://schema.oparl.org/1.1/Legis­la­ti­veTerm
oparl:Location https://schema.oparl.org/1.1/Loca­tion
oparl:Meeting https://schema.oparl.org/1.1/Meeting
oparl:Membership https://schema.oparl.org/1.1/Member­ship
oparl:Organization https://schema.oparl.org/1.1/Orga­ni­za­tion
oparl:Paper https://schema.oparl.org/1.1/Paper
oparl:Person https://schema.oparl.org/1.1/Person
oparl:System https://schema.oparl.org/1.1/System

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. 23

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.

3.4 System

Ein oparl:System-Objekt reprä­sen­tiert eine OParl-Schnitt­stelle für eine bestimmte OParl-Version. Es ist außer­dem der Start­punkt für Clients beim Zugriff auf einen Server.

Möchte ein Server mehrere zuein­an­der inkom­pa­ti­ble OParl-Versio­nen unter­stüt­zen, dann muss der Server für jede Version eine eige­nen OParl-Schnitt­stelle mit einem eige­nen System-Objekt ausge­ben.

Name Typ Beschrei­bung
id url
type string
oparlVersion string ZWINGEND Die URL der OParl-Spezi­fi­ka­tion, die von diesem Server unter­stützt wird. Aktu­ell kommt hier nur ein Wert in Frage. Mit zukünf­ti­gen OParl-Versio­nen kommen weitere mögli­che URLs hinzu. Wert: https://schema.oparl.org/1.1/
otherOparlVersions array of url (System) Dient der Angabe von System-Objek­ten mit ande­ren OParl-Versio­nen.
license url Lizenz, unter der durch diese API abruf­ba­ren Daten stehen, sofern nicht am einzel­nen Objekt anders ange­ge­ben. Siehe license.
body url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Körper­schaf­ten, die auf dem System exis­tie­ren.
name string Nutzer­freund­li­cher Name für das System, mit dessen Hilfe Nutze­rin­nen und Nutzer das System erken­nen und von ande­ren unter­schei­den können.
contactEmail string E-Mail-Adresse für Anfra­gen zur OParl-API. Die Angabe einer E-Mail-Adresse dient sowohl NutzerIn­nen wie auch Entwick­le­rin­nen von Clients zur Kontakt­auf­nahme mit dem Betrei­ber.
contactName string Name der Ansprech­part­ne­rin bzw. des Ansprech­part­ners oder der Abtei­lung, die über die in contactEmail ange­ge­bene Adresse erreicht werden kann.
website url URL der Website des parla­men­ta­ri­schen Infor­ma­ti­ons­sys­tems
vendor url URL der Website des Soft­wa­rean­bie­ters, von dem die OParl-Server-Soft­ware stammt.
product url URL zu Infor­ma­tio­nen über die auf dem System genutzte OParl-Server-Soft­ware
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/",
    "type": "https://schema.oparl.org/1.1/System",
    "oparlVersion": "https://schema.oparl.org/1.1/",
    "body": "https://oparl.example.org/bodies",
    "name": "Beispiel-System",
    "contactEmail": "info@example.org",
    "contactName": "Allgemeiner OParl Kontakt",
    "website": "http://www.example.org/",
    "vendor": "http://example-software.com/",
    "product": "http://example-software.com/oparl-server/",
    "otherOparlVersions": [
        "https://oparl2.example.org/"
    ],
    "created": "2011-11-11T11:11:00+01:00",
    "modified": "2012-11-11T11:11:00+01:00"
}

3.5 Body

Der Objekt­typ oparl:Body dient dazu, eine Körper­schaft zu reprä­sen­tie­ren. Eine Körper­schaft ist in den meis­ten Fällen eine Gemeinde, eine Stadt oder ein Land­kreis. In der Regel sind auf einem OParl-Server Daten von genau einer Körper­schaft gespei­chert und es wird daher auch nur ein Body-Objekt ausge­ge­ben. Sind auf dem Server jedoch Daten von mehre­ren Körper­schaf­ten gespei­chert, muss für jede Körper­schaft ein eige­nes Body-Objekt ausge­ge­ben werden.

Name Typ Beschrei­bung
id url
type string
system url (System) System, zu dem dieses Objekt gehört.
shortName string Kurzer Name der Körper­schaft.
name string ZWINGEND Der offi­zi­elle lange Name der Körper­schaft.
website url Allge­meine Website der Körper­schaft.
license url Lizenz, unter der die Daten dieser Körper­schaft stehen, sofern nicht am einzel­nen Objekt anders ange­ge­ben. Siehe license.
licenseValidSince date-time Zeit­punkt, seit dem die unter license ange­ge­bene Lizenz gilt. Vorsicht bei Ände­run­gen der Lizenz die zu restrik­ti­veren Bedin­gun­gen führen!
oparlSince date-time Zeit­punkt, ab dem OParl für dieses Body bereit­ge­stellt wurde. Dies hilft, um die Daten­qua­li­tät einzu­schät­zen, denn erst ab der Einrich­tung für OParl kann sicher­ge­stellt werden, dass sämt­li­che Werte korrekt in der Origi­nal-Quelle vorlie­gen.
ags string Der acht­stel­lige Amtli­che Gemein­de­schlüs­sel24.
rgs string Der zwölf­stel­lige Regio­nal­schlüs­sel.
equivalent array of url Dient der Angabe zusätz­li­cher URLs, die dieselbe Körper­schaft reprä­sen­tie­ren. Hier können beispiels­weise der entspre­chende Eintrag der gemein­sa­men Norm­da­tei der Deut­schen Natio­nal­bi­blio­thek25, der DBPe­dia26 oder der Wiki­pe­dia27 ange­ge­ben werden. Body- oder System-Objekte mit ande­ren OParl-Versio­nen dürfen nicht Teil der Liste sein.
contactEmail string Dient der Angabe einer Kontakt-E-Mail-Adresse. Die Adresse soll die Kontakt­auf­nahme zu einer für die Körper­schaft und idea­ler­weise das parla­men­ta­ri­sche Infor­ma­ti­ons­sys­tem zustän­di­gen Stelle ermög­li­chen.
contactName string Name oder Bezeich­nung der mit contactEmail erreich­ba­ren Stelle.
organization url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Grup­pie­run­gen der Körper­schaft.
person url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Perso­nen der Körper­schaft.
meeting url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Sitzun­gen der Körper­schaft.
paper url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Druck­sa­chen der Körper­schaft.
legislativeTerm array of object (Legis­la­ti­veTerm) ZWINGEND Objekt­liste mit den Wahl­pe­ri­oden der Körper­schaft.
agendaItem url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Tages­ord­nungs­punk­ten der Körper­schaft. Neu in OParl 1.1.
consultation url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Bera­tun­gen der Körper­schaft. Neu in OParl 1.1.
file url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Dateien der Körper­schaft. Neu in OParl 1.1.
locationList url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Orts­an­ga­ben der Körper­schaft. Neu in OParl 1.1.
legislativeTermList url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Legis­la­tur­pe­ri­oden der Körper­schaft. Neu in OParl 1.1. Die externe Objekt­liste enthält die glei­chen Objekte wie legislativeTerm
membership url (exter­nalList) ZWINGEND Link zur Objekt­liste mit allen Mitglied­schaf­ten der Körper­schaft. Neu in OParl 1.1.
classification string Art der Körper­schaft.
location object (Loca­tion) Ort, an dem die Körper­schaft behei­ma­tet ist.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/body/0",
    "type": "https://schema.oparl.org/1.1/Body",
    "system": "https://oparl.example.org/",
    "contactEmail": "ris@beispielstadt.de",
    "contactName": "RIS-Betreuung",
    "ags": "05315000",
    "rgs": "053150000000",
    "equivalent": [
        "http://d-nb.info/gnd/2015732-0",
        "http://dbpedia.org/resource/Cologne"
    ],
    "shortName": "Köln",
    "name": "Stadt Köln, kreisfreie Stadt",
    "website": "http://www.beispielstadt.de/",
    "license": "http://creativecommons.org/licenses/by/4.0/",
    "licenseValidSince": "2014-01-01T00:00:00+02:00",
    "organization": "https://oparl.example.org/body/0/organizations/",
    "person": "https://oparl.example.org/body/0/persons/",
    "meeting": "https://oparl.example.org/body/0/meetings/",
    "paper": "https://oparl.example.org/body/0/papers/",
    "agendaItem": "https://oparl.example.org/body/0/agendaItems/",
    "consultation": "https://oparl.example.org/body/0/consultations/",
    "file": "https://oparl.example.org/body/0/files/",
    "locationList": "https://oparl.example.org/body/0/locations/",
    "membership": "https://oparl.example.org/body/0/memberships/",
    "legislativeTerm": [
        {
            "id": "https://oparl.example.org/term/21",
            "type": "https://schema.oparl.org/1.1/LegislativeTerm",
            "body": "https://oparl.example.org/body/0",
            "name": "21. Wahlperiode",
            "startDate": "2010-12-03",
            "endDate": "2013-12-03",
            "created": "2014-01-08T14:28:31+01:00",
            "modified": "2014-01-08T14:28:31+01:00"
        }
    ],
    "location": {
        "id": "https://oparl.example.org/location/0",
        "type": "https://schema.oparl.org/1.1/Location",
        "description": "Rathaus der Beispielstadt, Ratshausplatz 1, 12345 Beispielstadt",
        "created": "2014-01-08T14:28:31+01:00",
        "modified": "2014-01-08T14:28:31+01:00",
        "geojson": {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    50.1234,
                    10.4321
                ]
            },
            "properties": {
                "name": "Rathausplatz"
            }
        }
    },
    "classification": "Kreisfreie Stadt",
    "created": "2014-01-08T14:28:31+01:00",
    "modified": "2014-01-08T14:28:31+01:00"
}

3.6 Legis­la­ti­veTerm

Dieser Objekt­typ dient der Beschrei­bung einer Wahl­pe­ri­ode.

Name Typ Beschrei­bung
id url
type string
body url (Body) Rück­re­fe­renz auf die Körper­schaft, welche nur dann ausge­ge­ben werden muss, wenn das Legis­la­ti­veTerm-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
name string Nutzer­freund­li­che Bezeich­nung der Wahl­pe­ri­ode.
startDate date Der erste Tag der Wahl­pe­ri­ode.
endDate date Der letzte Tag der Wahl­pe­ri­ode.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.7 Orga­ni­za­tion

Dieser Objekt­typ dient dazu, Grup­pie­run­gen von Perso­nen abzu­bil­den, die in der parla­men­ta­ri­schen Arbeit eine Rolle spie­len. Dazu zählen in der Praxis insbe­son­dere Frak­tio­nen und Gremien.

Name Typ Beschrei­bung
id url
type string
body url (Body) Körper­schaft, zu der diese Grup­pie­rung gehört.
name string Offi­zi­elle (lange) Form des Namens der Grup­pie­rung.
membership array of url (Member­ship) Mitglied­schaf­ten dieser Grup­pie­rung.
meeting url (exter­nalList) URL auf eine externe Objekt­liste mit den Sitzun­gen dieser Grup­pie­rung. Invers zur Eigen­schaft organization der Klasse oparl:Meeting
consultation url (exter­nalList) URL auf eine externe Objekt­liste mit den Bera­tun­gen dieser Grup­pie­rung. Invers zur Eigen­schaft organization der Klasse oparl:Consultation
shortName string Der Name der Grup­pie­rung als Kurz­form.
post array of string Posi­tio­nen, die für diese Grup­pie­rung vorge­se­hen sind.
subOrganizationOf url (Orga­ni­za­tion) URL einer even­tu­el­len über­ge­ord­ne­ten Grup­pie­rung.
organizationType string Grobe Kate­go­ri­sie­rung der Grup­pie­rung. Mögli­che Werte sind “Gremium”, “Partei”, “Frak­tion”, “Verwal­tungs­be­reich”, “exter­nes Gremium”, “Insti­tu­tion” und “Sons­ti­ges”.
classification string Die Art der Grup­pie­rung. In Frage kommen z.B. “Parla­ment”, “Ausschuss”, “Beirat”, “Projekt­bei­rat”, “Kommis­sion”, “AG”, “Verwal­tungs­rat”, “Frak­tion” oder “Partei”. Die Angabe sollte möglichst präzise erfol­gen. Außer­dem soll­ten Abkür­zun­gen vermie­den werden. Für die höchste demo­kra­ti­sche Instanz in der Kommune sollte immer der Begriff “Parla­ment” verwen­det werden, nicht “Rat” oder “Haupt­aus­schuss”.
startDate date Grün­dungs­da­tum der Grup­pie­rung. Kann z. B. das Datum der konsti­tu­ie­ren­den Sitzung sein.
endDate date Datum des letz­ten Tages der Exis­tenz der Grup­pie­rung.
website url Allge­meine Website der Grup­pie­rung.
location object (Loca­tion) Ort, an dem die Orga­ni­sa­tion behei­ma­tet ist
externalBody url (Body) Exter­ner OParl Body, der dieser Orga­ni­sa­tion entspricht. Diese Eigen­schaft ist dafür gedacht auf even­tu­elle konkre­tere OParl-Schnitt­stel­len zu verwei­sen. Ein Beispiel hier­für wäre eine Stadt, die sowohl ein über­grei­fen­des parla­men­ta­ri­sches Infor­ma­ti­ons­sys­tem, als auch bezirkss­pe­zi­fi­sche Systeme hat.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/organization/34",
    "type": "https://schema.oparl.org/1.1/Organization",
    "body": "https://oparl.example.org/bodies/1",
    "name": "Ausschuss für Haushalt und Finanzen",
    "shortName": "Finanzausschuss",
    "startDate": "2012-07-17",
    "organizationType": "Gremium",
    "location": {
        "id": "https://oparl.example.org/location/0",
        "type": "https://schema.oparl.org/1.1/Location",
        "description": "Rathaus der Beispielstadt, Ratshausplatz 1, 12345 Beispielstadt",
        "created": "2012-01-06T12:01:00+01:00",
        "modified": "2012-01-08T14:05:27+01:00",
        "geojson": {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    50.1234,
                    10.4321
                ]
            },
            "properties": {
                "name": "Rathausplatz"
            }
        }
    },
    "post": [
        "Vorsitzender",
        "1. Stellvertreter",
        "Mitglied"
    ],
    "meeting": "https://oparl.example.org/organization/34/meetings",
    "membership": [
        "https://oparl.example.org/membership/27",
        "https://oparl.example.org/membership/48",
        "https://oparl.example.org/membership/57"
    ],
    "classification": "Ausschuss",
    "keyword": [
        "finanzen",
        "haushalt"
    ],
    "created": "2012-07-16T00:00:00+02:00",
    "modified": "2012-08-16T12:34:56+02:00"
}

3.8 Person

Jede natür­li­che Person, die in der parla­men­ta­ri­schen Arbeit tätig und insbe­son­dere Mitglied in einer Grup­pie­rung (oparl:Orga­ni­za­tion) ist, wird mit einem Objekt vom Typ oparl:Person abge­bil­det.

Name Typ Beschrei­bung
id url
type string
body url (Body) Körper­schaft, zu der die Person gehört.
name string Der voll­stän­dige Name der Person mit akade­mi­schem Grad und dem gebräuch­li­chen Vorna­men, wie er zur Anzeige durch den Client genutzt werden kann.
familyName string Fami­li­enname bzw. Nach­name.
givenName string Vorname bzw. Tauf­name.
formOfAddress string Anrede.
affix string Namens­zu­satz (z.B. jun. oder MdL.)
title array of string Akade­mi­sche Titel
gender string Geschlecht. Vorge­ge­bene Werte sind female und male, weitere werden durch die durch­ge­hend klein geschrie­bene engli­sche Bezeich­nung ange­ge­ben. Für den Fall, dass das Geschlecht der Person unbe­kannt ist, sollte die Eigen­schaft nicht ausge­ge­ben werden.
phone array of string Tele­fon­num­mern der Person.
email array of string E-Mail-Adres­sen der Person.
location url (Loca­tion) Refe­renz der Kontakt-Anschrift der Person.
locationObject object (Loca­tion) Kontakt-Anschrift der Person. Wenn diese Eigen­schaft ausge­ge­ben wird, dann muss auch die Eigen­schaft location ausge­ge­ben werden und auf das glei­che Loca­tion-Objekt verwei­sen. Dieses Feld sollte die eigent­li­che Ausga­be­form von location in OParl 1.0 werden. vgl. https://github.com/OParl/spec/issues/373. Neu in OParl 1.1
status array of string Status, d.h. Rollen in der Kommune.
membership array of object (Member­ship) Mitglied­schaf­ten der Person in Grup­pie­run­gen, z. B. Gremien und Frak­tio­nen. Es sollen sowohl aktu­elle als auch vergan­gene Mitglied­schaf­ten ange­ge­ben werden
life string Kurzer Infor­ma­ti­ons­text zur Person. Eine Länge von weni­ger als 300 Zeichen ist empfoh­len
lifeSource string Angabe der Quelle, aus der die Infor­ma­tio­nen für life stam­men. Bei Angabe von life ist diese Eigen­schaft empfoh­len
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/person/29",
    "type": "https://schema.oparl.org/1.1/Person",
    "body": "https://oparl.example.org/body/0",
    "name": "Prof. Dr. Max Mustermann",
    "familyName": "Mustermann",
    "givenName": "Max",
    "title": [
        "Prof.",
        "Dr."
    ],
    "formOfAddress": "Ratsfrau",
    "gender": "male",
    "email": [
        "max@mustermann.de"
    ],
    "phone": [
        "+493012345678"
    ],
    "status": [
        "Bezirksbürgermeister"
    ],
    "membership": [
        {
            "id": "https://oparl.example.org/memberships/385",
            "type": "https://schema.oparl.org/1.1/Membership",
            "organization": "https://oparl.example.org/organizations/5",
            "role": "Vorsitzende",
            "votingRight": true,
            "startDate": "2013-12-03",
            "created": "2011-11-11T11:11:00+01:00",
            "modified": "2012-08-16T14:05:27+02:00"
        },
        {
            "id": "https://oparl.example.org/memberships/693",
            "type": "https://schema.oparl.org/1.1/Membership",
            "organization": "https://oparl.example.org/organizations/9",
            "role": "Sachkundige Bürgerin",
            "votingRight": false,
            "startDate": "2013-12-03",
            "endDate": "2014-07-28",
            "created": "2011-11-11T11:11:00+01:00",
            "modified": "2012-08-16T14:05:27+02:00"
        }
    ],
    "created": "2011-11-11T11:11:00+01:00",
    "modified": "2012-08-16T14:05:27+02:00"
}

3.9 Member­ship

Über Objekte dieses Typs wird die Mitglied­schaft von Perso­nen in Grup­pie­run­gen darge­stellt. Diese Mitglied­schaf­ten können zeit­lich begrenzt sein. Zudem kann abge­bil­det werden, dass eine Person eine bestimmte Rolle bzw. Posi­tion inner­halb der Grup­pie­rung inne­hat, beispiels­weise den Vorsitz einer Frak­tion.

Name Typ Beschrei­bung
id url
type string
person url (Person) Rück­re­fe­renz auf Person, welches nur dann ausge­ge­ben werden muss, wenn das Member­ship-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
organization url (Orga­ni­za­tion) Die Grup­pie­rung, in der die Person Mitglied ist oder war.
role string Rolle der Person für die Grup­pie­rung. Kann genutzt werden, um verschie­dene Arten von Mitglied­schaf­ten zum Beispiel in Gremien zu unter­schei­den.
votingRight boolean Gibt an, ob die Person in der Grup­pie­rung stimm­be­rech­tig­tes Mitglied ist.
startDate date Datum, an dem die Mitglied­schaft beginnt.
endDate date Datum, an dem die Mitglied­schaft endet.
onBehalfOf url (Orga­ni­za­tion) Die Grup­pie­rung, für die die Person in der unter organization ange­ge­be­nen Orga­ni­sa­tion sitzt. Beispiel: Mitglied­schaft als Vertre­ter einer Rats­frak­tion, einer Grup­pie­rung oder einer exter­nen Orga­ni­sa­tion.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.10 Meeting

Eine Sitzung ist die Versamm­lung einer oder mehre­rer Grup­pie­run­gen (oparl:Orga­ni­za­tion) zu einem bestimm­ten Zeit­punkt an einem bestimm­ten Ort.

Die gela­de­nen Teil­neh­mer der Sitzung sind jeweils als Objekte vom Typ oparl:Person, die in entspre­chen­der Form refe­ren­ziert werden. Verschie­dene Dateien (Einla­dung, Ergeb­nis- und Wort­pro­to­koll, sons­tige Anla­gen) können refe­ren­ziert werden. Die Inhalte einer Sitzung werden durch Tages­ord­nungs­punkte (oparl:Agen­daItem) abge­bil­det.

Name Typ Beschrei­bung
id url
type string
name string Name der Sitzung.
meetingState string Aktu­el­ler Status der Sitzung. Empfoh­len ist die Verwen­dung von terminiert (geplant), eingeladen (vor der Sitzung bis zur Frei­gabe des Proto­kolls) und durchgeführt (nach Frei­gabe des Proto­kolls).
cancelled boolean Wenn die Sitzung ausfällt, wird cancel­led auf true gesetzt.
start date-time Datum und Uhrzeit des Anfangs­zeit­punkts der Sitzung. Bei einer zukünf­ti­gen Sitzung ist dies der geplante Zeit­punkt, bei einer statt­ge­fun­de­nen kann es der tatsäch­li­che Start­zeit­punkt sein.
end date-time Endzeit­punkt der Sitzung als Datum/Uhrzeit. Bei einer zukünf­ti­gen Sitzung ist dies der geplante Zeit­punkt, bei einer statt­ge­fun­de­nen kann es der tatsäch­li­che Endzeit­punkt sein.
location object (Loca­tion) Sitzungs­ort.
organization array of url (Orga­ni­za­tion) Grup­pie­run­gen, denen die Sitzung zuge­ord­net ist. Im Regel­fall wird hier eine Grup­pie­rung verknüpft sein, es kann jedoch auch gemein­same Sitzun­gen mehre­rer Grup­pie­run­gen geben. Das erste Element sollte dann das feder­füh­rende Gremium sein.
participant array of url (Person) Perso­nen, die an der Sitzung teil­ge­nom­men haben (d.h. nicht nur die einge­la­de­nen Perso­nen, sondern die tatsäch­lich anwe­sen­den). Diese Eigen­schaft kann selbst­ver­ständ­lich erst nach dem Statt­fin­den der Sitzung vorkom­men.
invitation object (File) Einla­dungs­do­ku­ment zur Sitzung.
resultsProtocol object (File) Ergeb­nispro­to­koll zur Sitzung. Diese Eigen­schaft kann selbst­ver­ständ­lich erst nach­dem Statt­fin­den der Sitzung vorkom­men.
verbatimProtocol object (File) Wort­pro­to­koll zur Sitzung. Diese Eigen­schaft kann selbst­ver­ständ­lich erst nach dem Statt­fin­den der Sitzung vorkom­men.
auxiliaryFile array of object (File) Datei­an­hang zur Sitzung. Hier­mit sind Dateien gemeint, die übli­cher­weise mit der Einla­dung zu einer Sitzung verteilt werden, und die nicht bereits über einzelne Tages­ord­nungs­punkte refe­ren­ziert sind.
agendaItem array of object (Agen­daItem) Tages­ord­nungs­punkte der Sitzung. Die Reihen­folge ist rele­vant. Es kann Sitzun­gen ohne TOPs geben.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/meeting/281",
    "type": "https://schema.oparl.org/1.1/Meeting",
    "name": "4. Sitzung des Finanzausschusses",
    "start": "2013-01-04T08:00:00+01:00",
    "end": "2013-01-04T12:00:00+01:00",
    "location": {
        "id": "https://oparl.example.org/location/0",
        "type": "https://schema.oparl.org/1.1/Location",
        "description": "Rathaus der Beispielstadt, Ratshausplatz 1, 12345 Beispielstadt",
        "created": "2012-01-06T12:01:00+01:00",
        "modified": "2012-01-08T14:05:27+01:00",
        "geojson": {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    50.1234,
                    10.4321
                ]
            },
            "properties": {
                "name": "Rathausplatz"
            }
        }
    },
    "organization": [
        "https://oparl.example.org/organization/34"
    ],
    "invitation": {
        "id": "https://oparl.example.org/files/57739",
        "type": "https://schema.oparl.org/1.1/File",
        "name": "Einladung",
        "fileName": "einladung.pdf",
        "mimeType": "application/pdf",
        "date": "2012-01-08",
        "modified": "2012-01-08T14:05:27+01:00",
        "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 82930,
        "accessUrl": "https://oparl.example.org/files/57739.pdf",
        "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
        "created": "2012-01-06T12:01:00+01:00"
    },
    "resultsProtocol": {
        "id": "https://oparl.example.org/files/57739",
        "type": "https://schema.oparl.org/1.1/File",
        "name": "Protokoll",
        "fileName": "protokoll.pdf",
        "mimeType": "application/pdf",
        "date": "2012-01-08",
        "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 82930,
        "accessUrl": "https://oparl.example.org/files/57739.pdf",
        "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
        "modified": "2012-01-08T14:05:27+01:00",
        "created": "2012-01-06T12:01:00+01:00"
    },
    "verbatimProtocol": {
        "id": "https://oparl.example.org/files/57739",
        "type": "https://schema.oparl.org/1.1/File",
        "name": "Wortprotokoll",
        "fileName": "wortprotokoll.pdf",
        "mimeType": "application/pdf",
        "date": "2012-01-08",
        "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 82930,
        "accessUrl": "https://oparl.example.org/files/57739.pdf",
        "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
        "modified": "2012-01-08T14:05:27+01:00",
        "created": "2012-01-08T14:05:27+01:00"
    },
    "auxiliaryFile": [
        {
            "id": "https://oparl.example.org/files/57739",
            "type": "https://schema.oparl.org/1.1/File",
            "name": "Nachtrags-Tagesordnung",
            "fileName": "nachtrag-TO.pdf",
            "mimeType": "application/pdf",
            "date": "2012-01-08",
            "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
            "size": 82930,
            "accessUrl": "https://oparl.example.org/files/57739.pdf",
            "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
            "modified": "2012-01-08T14:05:27+01:00",
            "created": "2012-01-08T14:05:27+01:00"
        }
    ],
    "agendaItem": [
        {
            "id": "https://oparl.example.org/agendaitem/3271",
            "type": "https://schema.oparl.org/1.1/AgendaItem",
            "meeting": "https://oparl.example.org/meeting/281",
            "number": "10.1",
            "name": "Satzungsänderung für Ausschreibungen",
            "public": true,
            "consultation": "https://oparl.example.org/consultation/1034",
            "result": "Geändert beschlossen",
            "resolutionText": "Der Beschluss weicht wie folgt vom Antrag ab: ...",
            "created": "2012-01-06T12:01:00+01:00",
            "modified": "2012-01-08T14:05:27+01:00"
        }
    ],
    "created": "2012-01-06T12:01:00+01:00",
    "modified": "2012-01-08T14:05:27+01:00"
}

3.11 Agen­daItem

Tages­ord­nungs­punkte sind die Bestand­teile von Sitzun­gen (oparl:Meeting). Jeder Tages­ord­nungs­punkt widmet sich inhalt­lich einem bestimm­ten Thema, wozu in der Regel auch die Bera­tung bestimm­ter Druck­sa­chen gehört.

Die Bezie­hung zwischen einem Tages­ord­nungs­punkt und einer Druck­sa­che wird über ein Objekt vom Typ oparl:Consultation herge­stellt, das über die Eigen­schaft consultation refe­ren­ziert werden kann.

Name Typ Beschrei­bung
id url
type string
meeting url (Meeting) Rück­re­fe­renz auf das Meeting, welches nur dann ausge­ge­ben werden muss, wenn das agen­daItem-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
number string Glie­de­rungs-“Nummer” des Tages­ord­nungs­punk­tes. Eine belie­bige Zeichen­kette, wie z. B. “10.”, “10.1”, “C”, “c)” o. ä. Die Reihen­folge wird nicht dadurch, sondern durch die Reihen­folge der TOPs im agendaItem-Attri­but von oparl:Meeting fest­ge­legt, sollte aller­dings zu dieser iden­tisch sein.
order inte­ger ZWINGEND Neu in OParl 1.1: Die Posi­tion des Tages­ord­nungs­punkts in der Sitzung, wenn alle Tages­ord­nungs­punkte von 0 an durch­ge­hend nume­riert werden. Diese Nummer entspricht der Posi­tion in Meeting:agendaItem
name string Das Thema des Tages­ord­nungs­punk­tes.
public boolean Kenn­zeich­net, ob der Tages­ord­nungs­punkt zur Behand­lung in öffent­li­cher Sitzung vorge­se­hen ist/war. Es wird ein Wahr­heits­wert (true oder false) erwar­tet.
consultation url (Consul­ta­tion) Bera­tung, die diesem Tages­ord­nungs­punkt zuge­wie­sen ist.
result string Kate­go­ri­sche Infor­ma­tion darüber, welches Ergeb­nis die Bera­tung des Tages­ord­nungs­punk­tes erbracht hat, in der Bedeu­tung etwa “Unver­än­dert beschlos­sen” oder “Geän­dert beschlos­sen”.
resolutionText string Falls in diesem Tages­ord­nungs­punkt ein Beschluss gefasst wurde, kann hier ein Text ange­ge­ben werden. Das ist beson­ders dann in der Praxis rele­vant, wenn der gefasste Beschluss (z. B. durch Ände­rungs­an­trag) von der Beschluss­vor­lage abweicht.
resolutionFile object (File) Falls in diesem Tages­ord­nungs­punkt ein Beschluss gefasst wurde, kann hier eine Datei ange­ge­ben werden. Das ist beson­ders dann in der Praxis rele­vant, wenn der gefasste Beschluss (z. B. durch Ände­rungs­an­trag) von der Beschluss­vor­lage abweicht.
auxiliaryFile array of object (File) Weitere Datei­an­hänge zum Tages­ord­nungs­punkt.
start date-time Datum und Uhrzeit des Anfangs­zeit­punkts des Tages­ord­nungs­punk­tes. Bei zukünf­ti­gen Tages­ord­nungs­punk­ten ist dies der geplante Zeit­punkt, bei einem statt­ge­fun­de­nen kann es der tatsäch­li­che Start­zeit­punkt sein.
end date-time Endzeit­punkt des Tages­ord­nungs­punk­tes als Datum/Uhrzeit. Bei zukünf­ti­gen Tages­ord­nungs­punk­ten ist dies der geplante Zeit­punkt, bei einer statt­ge­fun­de­nen kann es der tatsäch­li­che Endzeit­punkt sein.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.12 Paper

Dieser Objekt­typ dient der Abbil­dung von Druck­sa­chen in der parla­men­ta­ri­schen Arbeit, wie zum Beispiel Anfra­gen, Anträ­gen und Beschluss­vor­la­gen. Druck­sa­chen werden in Form einer Bera­tung (oparl:Consul­ta­tion) im Rahmen eines Tages­ord­nungs­punkts (oparl:Agen­daItem) einer Sitzung (oparl:Meeting) behan­delt.

Druck­sa­chen spie­len in der schrift­li­chen wie münd­li­chen Kommu­ni­ka­tion eine beson­dere Rolle, da in vielen Texten auf bestimmte Druck­sa­chen Bezug genom­men wird. Hier­bei kommen in parla­men­ta­ri­schen Infor­ma­ti­ons­sys­te­men in der Regel unver­än­der­li­che Kennun­gen der Druck­sa­chen zum Einsatz.

Name Typ Beschrei­bung
id url
type string
body url (Body) Körper­schaft, zu der die Druck­sa­che gehört.
name string Titel der Druck­sa­che.
reference string Kennung bzw. Akten­zei­chen der Druck­sa­che, mit der sie in der parla­men­ta­ri­schen Arbeit eindeu­tig refe­ren­ziert werden kann.
date date Datum, welches als Start­punkt für Fris­ten u.ä. verwen­det ist.
paperType string Art der Druck­sa­che, z. B. Beant­wor­tung einer Anfrage.
relatedPaper array of url (Paper) Inhalt­lich verwandte Druck­sa­chen.
superordinatedPaper array of url (Paper) Über­ge­ord­nete Druck­sa­chen.
subordinatedPaper array of url (Paper) Unter­ge­ord­nete Druck­sa­chen.
mainFile object (File) Die Haupt­da­tei zu dieser Druck­sa­che. Beispiel: Die Druck­sa­che reprä­sen­tiert eine Beschluss­vor­lage und die Haupt­da­tei enthält den Text der Beschluss­vor­lage. Sollte keine eindeu­tige Haupt­da­tei vorhan­den sein, wird diese Eigen­schaft nicht ausge­ge­ben.
auxiliaryFile array of object (File) Alle weite­ren Dateien zur Druck­sa­che ausge­nom­men der gege­be­nen­falls in mainFile ange­ge­be­nen.
location array of object (Loca­tion) Sofern die Druck­sa­che einen inhalt­li­chen Orts­be­zug hat, beschreibt diese Eigen­schaft den Ort in Text­form und/oder in Form von Geoda­ten.
originatorPerson array of url (Person) Urhe­ber der Druck­sa­che, falls der Urhe­ber eine Person ist. Es können auch mehrere Perso­nen ange­ge­ben werden.
underDirectionOf array of url (Orga­ni­za­tion) Feder­füh­rung. Amt oder Abtei­lung, für die Inhalte oder Beant­wor­tung der Druck­sa­che verant­wort­lich.
originatorOrganization array of url (Orga­ni­za­tion) Urhe­ber der Druck­sa­che, falls der Urhe­ber eine Grup­pie­rung ist. Es können auch mehrere Grup­pie­run­gen ange­ge­ben werden.
consultation array of object (Consul­ta­tion) Bera­tun­gen der Druck­sa­che.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/paper/749",
    "type": "https://schema.oparl.org/1.1/Paper",
    "body": "https://oparl.example.org/bodies/1",
    "name": "Antwort auf Anfrage 1200/2014",
    "reference": "1234/2014",
    "date": "2014-04-04",
    "paperType": "Beantwortung einer Anfrage",
    "relatedPaper": [
        "https://oparl.example.org/paper/699"
    ],
    "mainFile": {
        "id": "https://oparl.example.org/files/57737",
        "type": "https://schema.oparl.org/1.1/File",
        "name": "Anlage 1 zur Anfrage",
        "fileName": "anlage_1_zur_anfrage.pdf",
        "mimeType": "application/pdf",
        "date": "2013-01-04",
        "sha1Checksum": "d749751af44a32c818b9b1e1515251c67734f5d2",
        "size": 82930,
        "accessUrl": "https://oparl.example.org/files/57737.pdf",
        "downloadUrl": "https://oparl.example.org/files/download/57737.pdf",
        "license": "http://www.opendefinition.org/licenses/cc-by",
        "created": "2013-01-04T07:54:13+01:00",
        "modified": "2013-01-04T07:54:13+01:00"
    },
    "auxiliaryFile": [
        {
            "id": "https://oparl.example.org/files/57739",
            "type": "https://schema.oparl.org/1.1/File",
            "name": "Anlage 1 zur Anfrage",
            "fileName": "anlage.pdf",
            "mimeType": "application/pdf",
            "date": "2013-01-04",
            "sha1Checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
            "size": 82930,
            "accessUrl": "https://oparl.example.org/files/57739.pdf",
            "downloadUrl": "https://oparl.example.org/files/download/57739.pdf",
            "text": "Der Übersichtsplan zeigt alle Ebenen des ...",
            "masterFile": "https://oparl.example.org/files/57738",
            "license": "http://www.opendefinition.org/licenses/cc-by",
            "created": "2013-01-04T07:54:13+01:00",
            "modified": "2013-01-04T07:54:13+01:00"
        }
    ],
    "location": [
        {
            "id": "https://oparl.example.org/locations/29856",
            "type": "https://schema.oparl.org/1.1/Location",
            "description": "Honschaftsstraße 312, Köln",
            "created": "2012-01-08T14:05:27+01:00",
            "modified": "2012-01-08T14:05:27+01:00",
            "geojson": {
                "type": "Point",
                "coordinates": [
                    7.03291,
                    50.98249
                ]
            }
        }
    ],
    "originatorPerson": [
        "https://oparl.example.org/person/2000",
        "https://oparl.example.org/person/1000"
    ],
    "originatorOrganization": [
        "https://oparl.example.org/organization/2000",
        "https://oparl.example.org/organization/1000"
    ],
    "consultation": [
        {
            "id": "https://oparl.example.org/consultation/47594",
            "type": "https://schema.oparl.org/1.1/Consultation",
            "agendaItem": "https://oparl.example.org/agendaitem/15569",
            "meeting": "https://oparl.example.org/meeting/243",
            "organization": [
                "https://oparl.example.org/organization/96"
            ],
            "authoritative": false,
            "role": "Beschlussfassung",
            "created": "2012-01-08T14:05:27+01:00",
            "modified": "2012-01-08T14:05:27+01:00"
        }
    ],
    "underDirectionOf": [
        "https://oparl.example.org/organization/2000"
    ],
    "created": "2013-01-08T12:05:27+01:00",
    "modified": "2013-01-08T12:05:27+01:00"
}

3.13 Consul­ta­tion

Der Objekt­typ oparl:Consultation dient dazu, die Bera­tung einer Druck­sa­che (oparl:Paper) in einer Sitzung abzu­bil­den. Dabei ist es nicht entschei­dend, ob diese Bera­tung in der Vergan­gen­heit statt­ge­fun­den hat oder diese für die Zukunft geplant ist. Die Gesamt­heit aller Objekte des Typs oparl:Consultation zu einer bestimm­ten Druck­sa­che bildet das ab, was in der Praxis als “Bera­tungs­folge” der Druck­sa­che bezeich­net wird.

Name Typ Beschrei­bung
id url
type string
paper url (Paper) Refe­renz auf das Paper, welche nur dann ausge­ge­ben werden muss, wenn das Consul­ta­tion-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
agendaItem url (Agen­daItem) Refe­renz auf den Tages­ord­nungs­punkt, unter dem die Druck­sa­che bera­ten wird, welcher nur dann ausge­ge­ben werden muss, wenn das Consul­ta­tion-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
meeting url (Meeting) Refe­renz auf die Sitzung, in der die Druck­sa­che bera­ten wird oder wurde, welche nur dann ausge­ge­ben werden muss, wenn das Consul­ta­tion-Objekt einzeln abge­ru­fen wird, d.h. nicht Teil einer inter­nen Ausgabe ist.
organization array of url (Orga­ni­za­tion) Gremium, in dem die Druck­sa­che bera­ten wird. Hier kann auch eine mit Liste von Gremien ange­ge­ben werden (die verschie­de­nen oparl:Body und oparl:System ange­hö­ren können). Die Liste ist dann geord­net. Das erste Gremium der Liste ist feder­füh­rend.
authoritative boolean Drückt aus, ob bei dieser Bera­tung ein Beschluss zu der Druck­sa­che gefasst wird oder wurde (true) oder nicht (false).
role string Rolle oder Funk­tion der Bera­tung. Zum Beispiel Anhö­rung, Entschei­dung, Kennt­nis­nahme, Vorbe­ra­tung usw.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.14 File

Ein Objekt vom Typ oparl:File reprä­sen­tiert eine Datei, beispiels­weise eine PDF-Datei, ein RTF- oder ODF-Doku­ment, und hält Meta­da­ten zu der Datei sowie URLs zum Zugriff auf die Datei bereit.

Objekte vom Typ oparl:File können unter ande­rem mit Druck­sa­chen (oparl:Paper) oder Sitzun­gen (oparl:Meeting) in Bezie­hung stehen. Dies wird durch die Eigen­schaft paper bzw. meeting ange­zeigt. Mehrere Objekte vom Typ oparl:File können mit einan­der in direk­ter Bezie­hung stehen, z.B. wenn sie den selben Inhalt in unter­schied­li­chen tech­ni­schen Forma­ten wieder­ge­ben. Hier­für werden die Eigen­schaf­ten masterFile bzw. derivativeFile einge­setzt. Das gezeigte Beispiel-Objekt reprä­sen­tiert eine PDF-Datei (zu erken­nen an der Eigen­schaft mimeType) und zeigt außer­dem über die Eigen­schaft masterFile an, von welcher ande­ren Datei es abge­lei­tet wurde. Umge­kehrt kann über die Eigen­schaft derivativeFile ange­zeigt werden, welche Ablei­tun­gen einer Datei exis­tie­ren.

Name Typ Beschrei­bung
id url
type string
name string Ein zur Anzeige für Endnut­zer bestimm­ter Name für dieses Objekt. Leer­zei­chen dürfen enthal­ten sein, Datei-Endun­gen wie “.pdf” soll­ten nicht enthal­ten sein.
fileName string Dateiname, unter dem die Datei in einem Datei­sys­tem gespei­chert werden kann. Beispiel: “eineda­tei.pdf”. Da der Name den komplet­ten Unicode-Zeichen­um­fang nutzen kann, soll­ten Clients ggfs. selbst dafür sorgen, diesen beim Spei­chern in ein Datei­sys­tem den loka­len Erfor­der­nis­sen anzu­pas­sen.
mimeType string MIME-Type der Datei 28.
date date Datum, welches als Start­punkt für Fris­ten u.ä. verwen­det ist.
size inte­ger Größe der Datei in Bytes.
sha1Checksum string [Veral­tet] SHA1-Prüf­summe des Datei­in­halts in Hexa­de­zi­mal-Schreib­weise. Sollte nicht mehr verwen­det werden, da sha1 als unsi­cher gilt. Statt­des­sen sollte sha512checksum verwen­det werden.
sha512Checksum string SHA512-Prüf­summe des Datei­in­halts in Hexa­de­zi­mal-Schreib­weise.
text string Reine Text-Wieder­gabe des Datei­in­halts, sofern dieser in Text­form wieder­ge­ge­ben werden kann.
accessUrl url ZWINGEND URL zum allge­mei­nen Zugriff auf die Datei. Nähe­res unter Datei­zu­griffe.
downloadUrl url URL zum Down­load der Datei. Nähe­res unter Datei­zu­griffe.
externalServiceUrl url Externe URL, welche eine zusätz­li­che Zugriffs­mög­lich­keit bietet. Beispiel: YouTube-Video.
masterFile url (File) Datei, von der das aktu­elle Objekt abge­lei­tet wurde. Details dazu in der allge­mei­nen Beschrei­bung weiter oben.
derivativeFile array of url (File) Dateien, die von dem aktu­el­len Objekt abge­lei­tet wurden. Details dazu in der allge­mei­nen Beschrei­bung weiter oben.
fileLicense url Lizenz, unter der die Datei ange­bo­ten wird. Wenn diese Eigen­schaft nicht verwen­det wird, ist der Wert von license bezie­hungs­weise die Lizenz eines über­ge­ord­ne­ten Objek­tes maßgeb­lich. Siehe license
meeting array of url (Meeting) Rück­re­fe­ren­zen auf Meeting-Objekte. Wird nur dann ausge­ge­ben, wenn das File-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
agendaItem array of url (Agen­daItem) Rück­re­fe­ren­zen auf Agen­daItem-Objekte. Wird nur dann ausge­ge­ben, wenn das File-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
paper array of url (Paper) Rück­re­fe­ren­zen auf Paper-Objekte. Wird nur dann ausge­ge­ben, wenn das File-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/files/57737",
    "type": "https://schema.oparl.org/1.1/File",
    "name": "Anlage 1 zur Anfrage",
    "fileName": "anlage_1_zur_anfrage.pdf",
    "mimeType": "application/pdf",
    "date": "2013-01-04",
    "size": 82930,
    "sha1Checksum": "d749751af44a32c818b9b1e1515251c67734f5d2",
    "accessUrl": "https://oparl.example.org/files/57737.pdf",
    "downloadUrl": "https://oparl.example.org/files/download/57737.pdf",
    "derivativeFile": [
        "https://oparl.example.org/files/57739"
    ],
    "fileLicense": "http://www.opendefinition.org/licenses/cc-by",
    "created": "2013-01-04T07:54:13+01:00",
    "modified": "2013-01-04T07:54:13+01:00"
}

3.15 Loca­tion

Dieser Objekt­typ dient dazu, einen Orts­be­zug formal abzu­bil­den. Orts­an­ga­ben können sowohl aus Text­in­for­ma­tio­nen beste­hen (beispiels­weise dem Namen einer Straße/eines Plat­zes oder eine genaue Adresse) als auch aus Geoda­ten. Orts­an­ga­ben sind auch nicht auf einzelne Posi­tio­nen beschränkt, sondern können eine Viel­zahl von Posi­tio­nen, Flächen, Stre­cken etc. abde­cken.

Name Typ Beschrei­bung
id url
type string
description string Textu­elle Beschrei­bung eines Orts, z. B. in Form einer Adresse.
geojson object Geoda­ten-Reprä­sen­ta­tion des Orts. Der Wert dieser Eigen­schaft muss der Spezi­fi­ka­tion von GeoJSON entspre­chen, d.h. es muss ein voll­stän­di­ges Feature-Objekt ausge­ge­ben werden.
streetAddress string Straße und Haus­num­mer der Anschrift.
room string Raum­an­gabe der Anschrift
postalCode string Post­leit­zahl der Anschrift.
subLocality string Unter­ge­ord­nete Orts­an­gabe der Anschrift, z.B. Stadt­be­zirk, Orts­teil oder Dorf.
locality string Orts­an­gabe der Anschrift.
bodies array of url (Body) Rück­re­fe­ren­zen auf Body-Objekte. Wird nur dann ausge­ge­ben, wenn das Loca­tion-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
organizations array of url (Orga­ni­za­tion) Rück­re­fe­ren­zen auf Orga­ni­za­tion-Objekte. Wird nur dann ausge­ge­ben, wenn das Loca­tion-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
persons array of url (Person) Rück­re­fe­ren­zen auf Person-Objekte. Wird nur dann ausge­ge­ben, wenn das Loca­tion-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
meetings array of url (Meeting) Rück­re­fe­ren­zen auf Meeting-Objekte. Wird nur dann ausge­ge­ben, wenn das Loca­tion-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
papers array of url (Paper) Rück­re­fe­ren­zen auf Paper-Objekte. Wird nur dann ausge­ge­ben, wenn das Loca­tion-Objekt nicht als einge­bet­te­tes Objekt aufge­ru­fen wird.
license string
keyword array of string
created date-time
modified date-time
web url
deleted boolean

Beispiel

{
    "id": "https://oparl.example.org/location/0",
    "type": "https://schema.oparl.org/1.1/Location",
    "description": "Rathaus der Beispielstadt, Ratshausplatz 1, 12345 Beispielstadt",
    "created": "2014-01-08T14:28:31+01:00",
    "modified": "2014-01-08T14:28:31+01:00",
    "geojson": {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                50.1234,
                10.4321
            ]
        },
        "properties": {
            "name": "Rathausplatz"
        }
    }
}

4 Ände­run­gen und Migra­tion

Dieses Kapi­tel beschreibt die Ände­run­gen zwischen den einzel­nen OParl-Versio­nen und die zur Migra­tion notwen­di­gen Schritte.

4.1 OParl 1.1

In OParl 1.1 setzen wir die seit der Veröf­fent­li­chung von OParl 1.0 gewon­nen Erfah­run­gen um. OParl 1.1 ist dabei im Sinne von semver kompa­ti­bel zu OParl 1.0. Das bedeu­tet, dass ein für OParl 1.0 entwi­ckel­ter Client auch die Ausgabe von OParl 1.1 versteht. Dadurch wird der Migra­ti­ons­auf­wand von OParl 1.0 zu OParl 1.1 gering gehal­ten.

OParl 1.0 wurde in der Annahme geschrie­ben, dass für sechs Objekt­ty­pen (Legis­la­ti­veTerm, Member­ship, Agen­daItem, Consul­ta­tion, File, Loca­tion) keine verläss­li­chen Werte für created und modified exis­tie­ren. Aus diesem Grund hatten wir uns für das Design mit einge­bet­te­ten Objek­ten entschie­den. Da sich nun jedoch heraus­ge­stellt hat, dass created und modified bei allen Objek­ten exis­tie­ren, können auch für alle Objekte Listen ange­bo­ten werden. Das bringt bei große Verein­fa­chun­gen für Clients bei der Synchro­ni­sa­tion.

Konkret sind created und modified in OParl 1.1 für alle Objekte zwin­gend und es gibt sechs neue externe Objekt­lis­ten in Body: Agen­daItem, Consul­ta­tion, File, Legis­la­ti­veTerm, Loca­tion und Member­ship. Das Attri­but für die Loca­tion-Liste in Body heißt dabei locationList, um eine Kolli­sion mit dem bereits exis­tie­ren­den location zu vermei­den. Das glei­che gilt auch für legislativeTermList.

Es entsteht dabei Redun­danz zwischen den bereits exis­tie­ren­den Objekt­lis­ten mit einge­bet­te­ten Objek­ten (Body, Paper, Meeting, Person, Orga­ni­za­tion) und den neuen exter­nen Listen, die die bisher einge­bet­te­ten Objekte extern ausge­ben. Diese Redun­danz lässt sich auf Grund der Semver-Regeln in Version 1.1 nicht vermei­den und kann erst in einer Version 2 besei­tigt werden. Um diese Redun­danz zumin­dest bei der Aktua­li­sie­rung eines loka­len Daten­be­stands vermei­den zu können wurde die URL-Para­me­ter omit_internal einge­führt.

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)

  1. In Deutsch­land hat sich auf kommu­na­ler Ebene der Begriff “Rats­in­for­ma­ti­ons­sys­tem” etabliert. OParl ist jedoch nicht auf Gemein­deräte beschränkt und verwen­det daher den Begriff “parla­men­ta­ri­sches Infor­ma­ti­ons­sys­tem”.

  2. Frank­furt Gestal­ten: http://www.frank­furt-gestal­ten.de/

  3. Poli­tik Bei Uns: https://poli­tik-bei-uns.de

  4. Eine welt­weite Über­sicht zu Open-Data-Projek­ten bietet z. B. der Open-Data-Showroom http://open­data-showroom.org/de/

  5. vgl. https://de.wiki­pe­dia.org/wiki/Open_data

  6. Ten Prin­cip­les for Opening Up Open Gover­n­ment Infor­ma­tion, https://sunlight­foun­da­tion.com/policy/docu­ments/ten-open-data-prin­cip­les

  7. Barrie­re­freie Infor­ma­ti­ons­tech­nik-Verord­nung 2.0 http://www.gesetze-im-inter­net.de/bitv_2_0/

  8. Weitere gene­relle Infor­ma­tio­nen zur Bereit­stel­lung offe­ner Verwal­tungs­da­ten bieten bspw.

  9. RFC2119 http://tools.ietf.org/html/rfc2119

  10. Das Rats­in­for­ma­ti­ons­sys­tem BoRis, eine Eigen­ent­wick­lung der Stadt Bonn http://www2.bonn.de/bo_ris/ris_sql/agm_index.asp

  11. bürger­baut­stadt, http://www.buer­ger­baut­stadt.de

  12. http://patterns.datain­cu­ba­tor.org/book/follow-your-nose.html

  13. RFC 3986: http://tools.ietf.org/html/rfc3986

  14. Berners-Lee, Tim: Cool URIs don’t change. http://www.w3.org/Provi­der/Style/URI.html

  15. Study on persis­tent URIs, with iden­ti­fi­ca­tion of best prac­ti­ces and recom­men­da­ti­ons on the topic for the MSs and the EC. (PDF) https://joinup.ec.europa.eu/sites/default/files/D7.1.3%20-%20Study%20on%20per­sis­tent%20URIs.pdf

  16. RFC 7159: https://tools.ietf.org/html/rfc7159

  17. RFC 7159 Section 8.1

  18. RFC 7159 Section 7

  19. Zu seman­tisch iden­ti­schen Forma­ten zählen u.a.: YAML, Messa­gePack, etc.

  20. vgl. Wiki­pe­dia: Same-Origin-Policy https://de.wiki­pe­dia.org/wiki/Same-Origin-Policy

  21. Cross Origin Resource Sharing – W3C Recom­men­da­tion 16. Januar 2014: http://www.w3.org/TR/cors/

  22. vgl. RFC2138http://www.ietf.org/rfc/rfc2183

  23. Verzeich­nisse für Lizenz-URLs sind unter ande­rem unter http://licen­ses.open­de­fi­ni­tion.org/ und https://github.com/fraun­ho­fer­fo­kus/ogd-meta­data/blob/master/lizen­zen/deutsch­land.json zu finden. Allge­meine Infor­ma­tio­nen zur Lizen­sie­rung von Open Data finden sich auch im Open Data Hand­book der Open Know­ledge Foun­da­tion unter http://open­da­ta­hand­book.org/de/how-to-open-up-data/apply-an-open-license.html.

  24. Amtli­che Gemein­de­schlüs­sel können im Gemein­de­ver­zeich­nis (GV-ISys) des Statis­ti­schen Bundes­am­tes einge­se­hen werden

  25. Gemein­same Norm­da­tei http://www.dnb.de/gnd

  26. DBPe­dia http://www.dbpe­dia.org/

  27. Wiki­pe­dia http://de.wiki­pe­dia.org/

  28. vgl. RFC2046: http://tools.ietf.org/html/rfc2046