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 „The­men­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

Dieses 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.0/

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

https://schema.oparl.org/1.0/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. Eine beson­dere Beach­tung soll­ten hier­bei unter ande­rem E-Mail- Adres­sen, Anschrif­ten, Fotos und Anwe­sen­heits­lis­ten finden. 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

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

Jayan Aree­ka­dan, Jan Erhardt, Stefan Graup­ner, Lucas Jacob, Jens Kless­mann (*), Andreas Kuck­artz (**), Erne­sto Ruge, Konstan­tin Schütze, 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(*)

(*): 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ür­ger 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 „Fol­low 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 RFC462716 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 werden die in ISO 8601 beschrie­be­nen Formate verwen­det. Ein Datum (date) muss muss also 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.

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.

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.0/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.0/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.0/Body",
  "location": {
    "id": "https://oparl.example.org/location/1",
    "type": "https://schema.oparl.org/1.0/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.0/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"
    }
  ],
  ...
}

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.0/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.0/Organization",
        "name": "Organisation Nummer 1",
        ...
      },
      {
        "id": "https://oparl.example.org/organization/2",
        "type": "https://schema.oparl.org/1.0/Organization",
        "name": "Organisation Nummer 2",
        ...
      },
      {
        "id": "https://oparl.example.org/organization/3",
        "type": "https://schema.oparl.org/1.0/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

{
    "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"
    }
}

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.

Die Filter werden vom Client benutzt, indem die gewünsch­ten URL-Para­me­ter an die URL der ersten Listen­siete ange­hängt werden. Bei allen weite­ren Seiten hat der Server sicher­zu­stel­len, dass die verwen­de­ten Filter erhal­ten blei­ben. 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 mit dem URL-Para­me­ter limit die Länge einer Listen durch den Client begrenzt werden. Ein Client darf nicht erwar­ten, dass sich ein Server an seine limit-Anfrage hält.

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 „Con­di­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

Das Löschen der Objekte oparl:System, oparl:Body, oparl:Orga­ni­sa­tion, oparl:Person, oparl:Meeting, oparl:Paper, oparl:File und oparl:Loca­tion muss in OParl geson­dert vermerkt werden. Es darf insbe­son­dere nicht einfach gelöscht werden, so dass unter der betref­fen­den URL kein gülti­ges Objekt ausge­lie­fert wird.

Hinter­grund ist, dass alle OParl-Clients zeit­nah erfah­ren können müssen, wenn ein Objekt gelöscht wurde. 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: 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

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

Die Objekte Legis­la­ti­veTerm, Member­ship, Agen­daItem und Consul­ta­tion können dage­gen einfach gelöscht werden. Beim Löschen dieser Objekte muss aller­dings der Wert modified aller Objekte aktua­li­siert werden, in die dieses Objekt einge­bun­den war.

Dies garan­tiert, dass das gelöschte Objekt beim Upda­ten eines Client-Daten­be­stan­des aktua­li­siert wird, falls der Client nur seit dem letz­ten Update aktua­li­sierte Objekte abruft.

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 Client kann nicht voraus­set­zen, dass im Fall einer Ausnahme noch weitere verwert­bare Infor­ma­tio­nen wie ein Fehler­mel­dung gesen­det werden.

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.0/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.0/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.0/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.0/Agen­daItem
oparl:Body https://schema.oparl.org/1.0/Body
oparl:Consultation https://schema.oparl.org/1.0/Consul­ta­tion
oparl:File https://schema.oparl.org/1.0/File
oparl:LegislativeTerm https://schema.oparl.org/1.0/Legis­la­ti­veTerm
oparl:Location https://schema.oparl.org/1.0/Loca­tion
oparl:Meeting https://schema.oparl.org/1.0/Meeting
oparl:Membership https://schema.oparl.org/1.0/Member­ship
oparl:Organization https://schema.oparl.org/1.0/Orga­ni­za­tion
oparl:Paper https://schema.oparl.org/1.0/Paper
oparl:Person https://schema.oparl.org/1.0/Person
oparl:System https://schema.oparl.org/1.0/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 „Bun­des­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, die nicht in ande­ren Objek­ten 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, die nicht in ande­ren Objek­ten 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.0/
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 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
{
    "id": "https://oparl.example.org/", 
    "type": "https://schema.oparl.org/1.0/System", 
    "oparlVersion": "https://schema.oparl.org/1.0/", 
    "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 ZWINGEND Link zur Objekt­liste mit allen Grup­pie­run­gen der Körper­schaft.
person url ZWINGEND Link zur Objekt­liste mit allen Perso­nen der Körper­schaft.
meeting url ZWINGEND Link zur Objekt­liste mit allen Sitzun­gen der Körper­schaft.
paper url 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.
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

3.5.1 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.
keyword array of string
web url
{
    "id": "https://oparl.example.org/body/0", 
    "type": "https://schema.oparl.org/1.0/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-01", 
    "organization": "https://oparl.example.org/body/0/organizations/", 
    "person": "https://oparl.example.org/body/0/people/", 
    "meeting": "https://oparl.example.org/body/0/meetings/", 
    "paper": "https://oparl.example.org/body/0/papers/", 
    "legislativeTerm": [
        {
            "id": "https://oparl.example.org/term/21", 
            "type": "https://schema.oparl.org/1.0/LegislativeTerm", 
            "body": "https://oparl.example.org/body/0", 
            "name": "21. Wahlperiode", 
            "startDate": "2010-12-03", 
            "endDate": "2013-12-03"
        }
    ], 
    "location": {
        "id:": "https://oparl.example.org/location/0", 
        "type": "https://schema.oparl.org/1.0/Location", 
        "description": "Rathaus der Beispielstadt, Ratshausplatz 1, 12345 Beispielstadt", 
        "geometry": {
            "type": "Feature", 
            "geometry": {
                "type": "Point", 
                "coordinates": [
                    50.1234, 
                    10.4321
                ]
            }, 
            "properties": {
                "name": "Rathausplatz"
            }
        }
    }, 
    "classification": "Kreisfreie Stadt", 
    "created": "2014-01-08T14:28:31+0100", 
    "modified": "2014-01-08T14:28:31+0100"
}

3.6 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 (Meeting) URL auf eine externe Objekt­liste mit den Sitzun­gen dieser Grup­pie­rung. Invers zur Eigen­schaft organization der Klasse oparl:Meeting
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 „Gre­mium“, „Par­tei“, „Frak­tion“, „Ver­wal­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. „Par­la­ment“, „Aus­schuss“, „Bei­rat“, „Pro­jekt­bei­rat“, „Kom­mis­sion“, „AG“, „Ver­wal­tungs­rat“, „Frak­tion“ oder „Par­tei“. 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 „Par­la­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.
keyword array of string
created date-time
modified date-time
web url
deleted boolean
{
    "id": "https://oparl.example.org/organization/34", 
    "type": "https://schema.oparl.org/1.0/Organization", 
    "body": "https://oparl.example.org/bodies/1", 
    "name": "Ausschuss für Haushalt und Finanzen", 
    "shortName": "Finanzausschuss", 
    "startDate": "2012-07-17", 
    "organizationType": "Gremium", 
    "location": "https://oparl.example.org/location/4", 
    "post": [
        "Vorsitzender", 
        "1. Stellvertreter", 
        "Mitglied"
    ], 
    "meeting": [
        "https://oparl.example.org/meeting/27", 
        "https://oparl.example.org/meeting/36", 
        "https://oparl.example.org/meeting/45", 
        "https://oparl.example.org/meeting/53", 
        "https://oparl.example.org/meeting/63", 
        "https://oparl.example.org/meeting/72", 
        "https://oparl.example.org/meeting/81", 
        "https://oparl.example.org/meeting/92", 
        "https://oparl.example.org/meeting/101", 
        "https://oparl.example.org/meeting/111", 
        "https://oparl.example.org/meeting/120", 
        "https://oparl.example.org/meeting/133"
    ], 
    "membership": [
        "https://oparl.example.org/memberships/27", 
        "https://oparl.example.org/memberships/48", 
        "https://oparl.example.org/memberships/57"
    ], 
    "classification": "Ausschuss", 
    "keyword": [
        "finanzen", 
        "haushalt"
    ], 
    "created": "2012-07-16", 
    "modified": "2012-08-16"
}

3.7 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. Empfoh­lene Werte sind female, male und other. 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.
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
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.7.1 Member­ship

Über Objekte diesen 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.
keyword array of string
web url
{
    "id": "https://oparl.example.org/person/29", 
    "type": "https://schema.oparl.org/1.0/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.0/Membership", 
            "organization": "https://oparl.example.org/organizations/5", 
            "role": "Vorsitzende", 
            "votingRight": true, 
            "startDate": "2013-12-03"
        }, 
        {
            "id": "https://oparl.example.org/memberships/693", 
            "type": "https://schema.oparl.org/1.0/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"
}

3.8 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.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.8.1 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.
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.
keyword array of string
web url
{
    "id": "https://oparl.example.org/meeting/281", 
    "type": "https://schema.oparl.org/1.0/Meeting", 
    "name": "4. Sitzung des Finanzausschusses", 
    "start": "2013-01-04T08:00:00+01:00", 
    "end": "2013-01-04T12:00:00+01:00", 
    "location": "https://oparl.example.org/location/223", 
    "organization": [
        "https://oparl.example.org/organization/34"
    ], 
    "invitation": {
        "id": "https://oparl.example.org/files/57739", 
        "type": "https://schema.oparl.org/1.0/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"
    }, 
    "resultsProtocol": {
        "id": "https://oparl.example.org/files/57739", 
        "type": "https://schema.oparl.org/1.0/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"
    }, 
    "verbatimProtocol": {
        "id": "https://oparl.example.org/files/57739", 
        "type": "https://schema.oparl.org/1.0/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"
    }, 
    "auxiliaryFile": [
        {
            "id": "https://oparl.example.org/files/57739", 
            "type": "https://schema.oparl.org/1.0/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"
        }
    ], 
    "agendaItem": [
        {
            "id": "https://oparl.example.org/agendaitem/3271", 
            "type": "https://schema.oparl.org/1.0/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", 
            "resolution": "Der Beschluss weicht wie folgt vom Antrag ab: ...", 
            "modified": "2012-08-16T14:05:27+02:00"
        }
    ], 
    "created": "2012-01-06T12:01:00+01:00", 
    "modified": "2012-01-08T14:05:27+01:00"
}

3.9 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.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.9.1 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) Rück­re­fe­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) Tages­ord­nungs­punkt, unter dem die Druck­sa­che bera­ten wird.
meeting url (Meeting) Sitzung, in der die Druck­sa­che bera­ten wird.
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.
keyword array of string
web url
{
    "id": "https://oparl.example.org/paper/749", 
    "type": "https://schema.oparl.org/1.0/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.0/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.0/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.0/Location", 
            "description": "Honschaftsstraße 312, Köln", 
            "geometry": {
                "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.0/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"
        }
    ], 
    "underDirectionOf": [
        "https://oparl.example.org/organization/2000"
    ], 
    "created": "2013-01-08T12:05:27+01:00", 
    "modified": "2013-01-08T12:05:27+01:00"
}

3.10 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 sgezeigte 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: „eine­da­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 SHA1-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 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 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 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.
keyword array of string
created date-time
modified date-time
web url
deleted boolean
{
    "id": "https://oparl.example.org/files/57737", 
    "type": "https://schema.oparl.org/1.0/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.11 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 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.
organization array of url 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.
meeting array of url 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 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.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

  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 „par­la­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. RFC4627: https://tools.ietf.org/html/rfc4627

  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

Bitte wählen Sie ein Downloadformat aus

Wir stellen die Downloads der Spezifikation in verschiedenen Formaten zur Verfügung. Bitte wählen Sie unten das von Ihnen gewünschte aus.

Archive

Die Archive enthalten immer alle verfügbaren Ausgabeformate.