1 Einlei­tung

Dieses Doku­ment enthält die Spezi­fika­tion des OParl Schnitt­s­tel­len-Stand­ards für parla­ment­ar­ische Inform­a­tionssysteme1. Es dient damit als Grundlage für die Imple­men­tier­ung von OParl-konfor­men Server- und Clientan­wendun­gen.

1.1 Was ist OParl?

OParl ist die Grup­pier­ung, die Initi­ator und Heraus­ge­ber der vorlie­genden Spezi­fika­tion ist. An OParl wirken Verbände, zivil­gesell­schaft­liche Organ­isa­tionen und Initi­at­iven und Soft­warean­bi­eter sowie interessierte Einzelp­er­sonen mit.

Die vorlie­gende Spezi­fika­tion beschreibt den OParl-Stand­ard. Dieser definiert eine Webser­viceschnitt­s­telle, die den anony­men, lesenden Zugriff auf öffent­liche Inhalte aus parla­ment­ar­ischen Inform­a­tionssyste­men ermög­licht. Wie der Name “Webser­vice” ausdrückt, setzt diese Schnitt­s­telle auf dem World Wide Web auf. Sie ermög­licht, dass parla­ment­ar­ische Inform­a­tionen maschinen­les­bar als offene Daten (Open Data) veröf­fent­licht werden.

Die vorlie­gende Version ist die erste verab­schiedete Version der Spezi­fika­tion des OParl-Stand­ards.

1.2 Ziel­set­zung von OParl

OParl richtet sich an verschiedene Nutzer­grup­pen und Stake­holder:

  • Verwal­tun­gen und andere polit­ische Gremien in Gebi­et­skörper­schaften
  • Bürger, polit­ische Parteien und Organ­isa­tionen
  • Open-Data-Initi­at­iven
  • Wissenschaftler
  • Anbi­eter von Server- und Soft­ware­produk­ten im Umfeld von parla­ment­ar­ischen Inform­a­tionssyste­men und Öffent­lich­keits­beteili­gung

Die Gründe, warum Betreiber von parla­ment­ar­ischen Inform­a­tionssyste­men den Zugriff darauf über eine stand­ard­is­ierte Schnitt­s­telle ermög­lichen soll­ten oder möchten, können vielfältig und je nach Nutzer­gruppe unter­schied­lich sein.

Ein zent­rales Argu­ment für Verwal­tung und polit­ische Gremien, sei es in Gebi­et­skörper­schaften oder auf Landes- oder Bundesebene, ist die Verp­f­lich­tung der Parla­mente gegenüber der Bevölker­ung, diese über die Forts­ch­ritte der parla­ment­ar­ischen Arbeit zu informieren und auf dem Laufenden zu halten. Ein erster Schritt, der Bevölker­ung Einblicke in die Arbeit und Zugriff auf Doku­mente zu gewähren, ist viel­erorts in den letzten Jahren durch Einführung von Ratsin­form­a­tionssyste­men mit anonymem, lesen­dem Zugriff über das World Wide Web gemacht worden.

Die damit eingesch­la­gene Rich­tung konsequent weiter zu gehen, bedeutet, die Daten der parla­ment­ar­ischen Inform­a­tionssysteme soweit offen zu legen, wie die Inhalte es erlauben. Es bedeutet, die Daten und Inhalte so universell weit­erver­wend­bar und so barri­erearm wie möglich anzu­bi­eten, dass jegliche weit­ere Verwendung 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-Initi­at­iven können unter Rück­griff auf Ratsin­form­a­tionssysteme (RIS) mit OParl-Schnitt­s­telle einfacher Doku­mente und Daten aus unter­schied­lichen Gebi­et­skörper­schaften in Open-Data-Kata­logen verzeichnen und so einfacher auffind­bar machen für die Weit­erver­wendung durch Dritte.

Bürger­innen und Bürger, polit­ische Parteien und zivil­gesell­schaft­liche Organ­isa­tionen können einfacher auf Inhalte parla­ment­ar­ischer Inform­a­tionssysteme zugre­ifen und diese ents­prechend ihren Interessen aufbereiten. Dies können beis­piels­weise Visu­al­is­ier­ungen von enthaltenen Daten, die Anreicher­ung von Inform­a­tion­sange­boten für spez­i­elle Nutzer­grup­pen oder die Schaf­fung von Benutzer­ober­flächen mit beson­deren Funk­tionen für verschiedene Endger­äte sein.

Das Interesse an parla­ment­ar­ischen Inform­a­tionen und an Anwendun­gen, die diese nutzbar und auswert­bar machen, ist offensicht­lich vorhanden. Die Entwick­ler der altern­at­iven Ratsin­form­a­tionssysteme wie Frank­furt Gestal­ten2, Offenes Köln oder der OpenRuhr:RIS-Instan­zen (die letzten beiden wurden zusam­menge­führt in Politik Bei Uns3) wissen zu berichten, wie viel Interesse den Projek­ten gerade aus Orten entge­gen gebracht wird, in denen derartige Systeme noch nicht verfüg­bar sind.

Die Anwendungs­mög­lich­keiten für parla­ment­ar­ische Inform­a­tionen, wenn sie über eine Schnitt­s­telle schnell und einfach abgerufen werden können, sind vielfältig. Beis­piele sind:

  • Apps für den Abruf auf mobi­len Endger­äten
  • Möglich­keiten zur Wieder­gabe für Nutzer­innen und Nutzer mit Beein­träch­ti­gung des Sehver­mö­gens
  • Altern­at­ive und erweit­erte Such­mög­lich­keiten in Inhal­ten
  • Auswer­tung und Analyse von Themen, Inhal­ten, Sprache etc.
  • Bena­chrich­ti­gungs­funk­tionen beim Erscheinen bestim­mter Inhalte

Die Stand­ard­is­ier­ung dieses Zugriffs über die Gren­zen einzel­ner Systeme hinweg erlaubt zudem, diese Entwicklun­gen auch geograph­isch und polit­isch gren­züber­s­chreit­end zu denken. Damit steigt nicht nur die poten­zi­elle Nutzer­schaft einzel­ner Entwicklun­gen. Auch das Poten­zial für Koop­er­a­tionen zwis­chen Anwendung­sentwick­lern wächst.

Für Wissenschaftler, die z. B. an vergleichenden Unter­suchun­gen zu Vorgän­gen in verschiedenen Gebi­et­skörper­schaften interessiert sind, ergeben sich ebenso vielfältige Möglich­keiten über mehr­ere RIS-Instan­zen hinweg auf ents­prechende Inform­a­tionen zuzu­gre­ifen und diese so einfacher in ihre Analysen einzubez­iehen.

Darüber hinaus sind auch Motiv­a­tionen inner­halb von Organ­isa­tionen und Körper­schaften erken­nbar. So sollen parla­ment­ar­ische Inform­a­tionssysteme viel­erorts in verschieden­ste Prozesse und hetero­gene System­land­schaften integ­riert werden. Durch eine einheit­liche Schnitt­s­telle bieten sich effiz­iente Möglich­keiten zur Integ­ra­tion der Daten in anderen Systeme, wie beis­piels­weise Webportale.

Anbi­eter von Soft­ware­produk­ten, die RIS-Lösun­gen anbi­eten, können ihren Kunden mit der Imple­ment­a­tion der OParl-Schnitt­s­telle eine ents­prechende einheit­liche Schnitt­s­telle anbi­eten.

Ausführ­lichere Beschreibun­gen eini­ger möglicher Anwendungsszenarien finden sich im Kapitel Nutzungsszenarien.

1.3 Trans­par­enz und Beteili­gung durch Open Data

Öffent­liche Stel­len verfü­gen über vielfältige Inform­a­tionen und Daten. Seit eini­gen Jahren sind zivil­gesell­schaft­liche Organ­isa­tionen sowie Politik und Verwal­tung unter dem Schlag­wort Open Data inter­na­tional und auch in Deutsch­land um eine stärkere Öffnung dieser Daten bemüht4. Bei dem Ansatz Open Data5 geht es darum, diese Daten so bereit­zus­tel­len, dass Dritte diese einfacher finden und weit­erver­wenden können.

Die zehn Open-Data-Prin­zipien der Sunlight-Found­a­tion6 beschreiben die Offen­heit von Datensätzen. Wesent­lich dabei sind vor allem die einfache recht­liche und die tech­nis­che Offen­heit. Bei ersterer geht es darum, dass Datensätze unter Nutzungs­bestim­mun­gen bereit­ges­tellt werden, die kurz und verständ­lich formu­liert sind und mindes­tens jegliche weit­ere Verwendung inklus­ive der kommerzi­el­len erlauben, unter der Voraus­set­zung, dass bei der Weit­erver­wendung die Quelle benannt wird. Bei der tech­nis­chen Offen­heit steht die Bereit­s­tel­lung von Datensätzen in möglichst maschinen­les­baren Formaten im Vorder­grund. Dies bedeutet, stärker struk­tur­ierte Datensätze sind in der Bereit­s­tel­lung zu bevorzu­gen. Liegen Daten inner­halb einer Organ­isa­tion in einer Daten­bank vor, so bietet es sich an, diese über eine Program­mi­er­schnitt­s­telle (API) für Außen­stehende bereit­zus­tel­len.

Die Erfül­lung dieser recht­lichen und tech­nis­chen Offen­heit erlaubt es im Falle von OParl Drit­ten – dies können Bürger­innen und Bürger, Unterneh­men, Forschung­sein­rich­tun­gen oder auch andere Verwal­tung­sein­heiten sein – die Verwal­tungs­daten wesent­lich unkom­pliz­ierter für eigene Vorhaben wie Anwendun­gen oder Visu­al­is­ier­ungen einzu­set­zen. Mit dem Ansatz offener Verwal­tungs­daten soll so erstens mehr Trans­par­enz über Prozesse und Entscheidun­gen in Politik und Verwal­tung erreicht werden. Zweitens können Dritte auf Grundlage dieser Daten leichter eigene Geschäfts­mod­elle verfein­ern oder neue entwick­eln. Drit­tens wird es auch öffent­lichen Stel­len selbst erleichtert bereits im öffent­lichen Sektor existi­er­ende Daten zu finden und weit­erzuver­wenden.

Das Prin­zip offener Daten bzw. offener Verwal­tungs­daten über die Minim­al­prin­zipien recht­licher und tech­nis­cher Offen­heit hinaus in die Tat umzu­set­zen, erfordert im Einzel­fall häufig eine Zusammen­arbeit von Daten­bereit­s­tellern und poten­ti­el­len Daten­nutzern. Die bloße Bereit­s­tel­lung einer OParl-konfor­men API wird weder die Einhal­tung der tech­nis­chen Prin­zipien, noch der weit­eren Open-Data-Prin­zipien voll­ständig garantieren. Viele Best­andteile der OParl-Spezi­fika­tion, die einen weit­ge­hend barri­erear­men Zugang zu Inform­a­tionen7 ermög­lichen sollen, sind in der vorlie­genden Version noch optional (Beis­piel: Voll­texte von Doku­menten über die API abruf­bar machen). Andere Best­andteile,die von Interesse wären, sind noch gar nicht von OParl abgedeckt (Beis­piel: Abstim­mung­sergeb­n­isse). Grund dafür ist, dass sich OParl in einem frühen Stadium befin­det und primär am Status Quo der parla­ment­ar­ischen Inform­a­tionssysteme ausgerichtet ist. Es liegt also auch weit­er­hin an Verwal­tung und Politik, durch einen verant­wor­tungs­vol­len Umgang mit den Syste­men die maximal erreich­bare Trans­par­enz zu bieten. Das fängt bei verfüg­baren Doku­ment­formaten an (ein PDF mit digitalem Text weist weit weni­ger Barri­eren auf, als ein gescan­nter Brief, der eben­falls als PDF gespeich­ert wurde) und hört bei der verwen­deten Sprache auf8.

1.4 Nutzungsszenarien

Für OParl sind verschiedene Nutzungsszenarien denk­bar. Die Nach­fol­gende Auflis­tung soll einen kleinen Überblick geben, erhebt aber bei weitem keinen Anspruch auf Voll­ständigkeit:

1.4.1 Mobile Anwendung

Eine Anwendung für mobile Endger­äte wie Smart­phones und Tablets, nachfol­gend “App” genannt, könnte das Ziel verfol­gen, Nutzern unter­wegs, sowie abseits vom Desktop-PC opti­mier­ten Zugriff auf ein parla­ment­ar­isches Inform­a­tionssys­tem zu ermög­lichen. Dies könnte auch zur Vere­in­fachung der bish­eri­gen Prozesse beitra­gen, da Nutzer­innen z.B. die Möglich­keit gegeben werden kann, auf Einladun­gen zu reagieren, oder Protokolle zu lesen.

1.4.2 Integ­ra­tion in ein Webportal

Portallösun­gen bieten den Betreibern die Möglich­keit, Inhalte auf einer einheit­lichen Webober­fläche zu veröf­fent­lichen, die aus verschieden­sten Quel­len und Platt­for­men bereit­ges­tellt werden. Ein Beis­piel für die Real­is­ier­ung eines solchen Integ­ra­tions-Ansatzes wäre eine Kommune, die für ihre allge­meine Website eine Portallösung einsetzt und hier auch Inhalte aus dem kommun­alen Ratsin­form­a­tionssys­tem einspeisen und darstel­len möchte. Vorteil einer solchen Einbindung, also der kontext­bezo­genen Darstel­lung von parla­ment­ar­ischen Inform­a­tionen im Gegensatz zu einem mono­lith­is­chen parla­ment­ar­ischen Inform­a­tionssys­tem könnte sein, dass Nutzer in einer gewohnten und akzep­tier­ten Ober­fläche jeweils die relev­anten Inform­a­tionen erhal­ten, ohne sich an die unge­wohnte Umge­bung eines parla­ment­ar­ischen Inform­a­tionssys­tems gewöhnen zu müssen.

1.4.3 Meta-Suche

Die Ermög­lichung einer nutzer­fre­und­lichen Suche, die damit verbundene Index­ier­ung von verschieden­sten Doku­menten­in­hal­ten und die Kategor­is­ier­ung von Inhal­ten kann eine sowohl konzep­tion­ell als auch tech­nisch anspruchs­volle Aufgabe sein. Angelehnt an das seit den Anfän­gen des Webs etablierte Modell der externen Web-Such­maschine sind spez­i­elle Such­maschinen für OParl-konforme parla­ment­ar­ische Inform­a­tionssysteme denk­bar. Solche Platt­for­men treten gegenüber dem OParl-Server als Client auf und rufen bestim­mte oder sämt­liche Inform­a­tionen, die das System bereit­hält, ab. Vorbild sind die Robots oder Spider von Web-Such­maschinen. Die abgerufenen Inform­a­tionen können dann index­iert und je nach Anfor­der­ungen für eine gezielte Suche weit­erver­arbeitet werden.

1.4.4 Forschung­s­pro­jekt “Themen­ana­lyse”

In einem Forschung­s­pro­jekt sollen Pro- und Contra-Argu­ment­a­tionen bei Rats­diskus­sionen zum Ausbau von Stromtrassen iden­ti­fiz­iert werden. Dazu nutzen die Mitarbeitenden des Forschung­s­pro­jektes die OParl-Schnitt­s­tel­len der parla­ment­ar­ischen Inform­a­tionssysteme aller Kommunen entlang der geplanten über­re­gionalen Trassen. Über diese einheit­lichen Schnitt­s­tel­len können sie insbeson­dere die relev­anten Wort­pro­tokolle abrufen und zum Beis­piel in einem Werkzeug zur qual­it­at­iven Daten­ana­lyse lokal verarbeiten.

1.5 Nomen­k­latur

1.5.1 Zwin­gende, empfohlene und optionale Anfor­der­ungen

Dieses Spezi­fika­tion nutzt müssen, können und soll­ten in einer eindeutig definier­ten Art und Weise. Diese ist angelehnt an die Defini­tionen der Begriffe MUST, SHOULD und MAY (bzw. MUST NOT, SHOULD NOT und MAY NOT) aus RFC2119.9

Die Bedeu­tung im Einzelnen:

müssen/muss bzw. zwin­gend:

Die Erfül­lung einer so geken­nzeich­neten Anfor­der­ung ist zwin­gend erforder­lich.

Die Ents­prechung in RFC2119 lautet “MUST”, “REQUIRED” oder “SHALL”.

nicht dürfen/darf nicht:

Dieses Stich­wort kennzeich­net ein abso­lutes Verbot.

Die Ents­prechung in RFC2119 lautet “MUST NOT” oder “SHALL NOT”.

soll­ten/sollte bzw. empfohlen:

Mit dem Wort soll­ten bzw. sollte sind empfohlene Anfor­der­ungen geken­nzeich­net, die von jeder Imple­men­tier­ung erfüllt werden soll­ten. Eine Nichter­fül­lung ist als Nachteil zu verstehen, beis­piels­weise weil die Nutzer­fre­und­lich­keit dadurch Einbußen erleidet, und sollte daher sorgfältig abge­wo­gen werden.

Die Ents­prechung in RFC2119 lautet “SHOULD” oder “RECOMMENDED”.

soll­ten nicht/sollte nicht bzw. nicht empfohlen:

Diese Formu­lier­ung wird verwen­det, wenn unter gewis­sen Umständen Gründe existieren können, die ein bestim­mtes Verhal­ten akzept­a­bel oder sogar nütz­lich erscheinen lassen, jedoch die Auswirkung des Verhal­tens vor einer ents­prechenden Imple­men­tier­ung verstanden und abge­wo­gen werden soll­ten.

Die Ents­prechung in RFC2119 lautet “SHOULD NOT” oder “NOT RECOMMENDED”.

dürfen/darf bzw. optional:

Mit dem Wort dürfen bzw. darf oder optional sind optionale Best­andteile geken­nzeich­net. Ein Anbi­eter könnte sich entscheiden, den ents­prechenden Best­andteil aufgrund beson­derer Kundenan­for­der­ungen zu unter­stützen, während andere diesen Best­andteil ignor­i­eren könnten. Imple­men­tierer von Clients oder Servern dürfen in solchen Fällen nicht davon ausge­hen, dass der jewei­lige Kommunika­tion­spart­ner den ents­prechenden, optionalen Anteil unter­stützt.

Die Ents­prechung in RFC2119 lautet “MAY”.

1.5.2 Geschlechter­spezi­fis­che Begriff­lich­keiten

Um bei Begrif­fen wie Nutzer, Anwender, Betreiber etc. die sonst übliche Domin­anz der männ­lichen Vari­ante zu vermeiden, werden in diesem Doku­ment männ­liche und weib­liche Vari­anten gemis­cht. Gemeint sind in allen Fällen Personen jeglichen Geschlechts.

1.5.3 Code­beis­piele

Die in diesem Doku­ment aufge­führten Code­beis­piele dienen der Veran­schau­lichung der beschriebenen Prin­zipien. Es handelt sich um frei erfundene Daten.

Code­beis­piele erheben insbeson­dere bei JSON-Code nicht den Anspruch auf syntakt­ische Korrek­theit und Voll­ständigkeit. Dement­s­prechend können in Code­beis­pielen Auslas­sun­gen vorkom­men, die mit ... geken­nzeich­net werden.

1.5.4 Namespace-Präfixe für Objekt- und Daten­typen

Bei der Erwäh­nung von Objekt­typen, die in dieser Spezi­fika­tion beschrieben werden, wird in der Regel ein Präfix oparl: vor den Namen gesetzt, z. B. “oparl:Organ­iz­a­tion”. Damit soll verdeut­licht werden, dass der Objekttyp inner­halb der OParl-Spezi­fika­tion gemeint ist.

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

https://schema.oparl.org/1.0/

Dadurch kann eine Typen­angabe wie oparl:Organization eindeutig in die folgende URL über­setzt werden:

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

1.6 Datens­chutz

Gemäß der Grundlage “öffent­liche Daten nutzen, private Daten schützen” hat Datens­chutz auch bei OParl eine hohe Prior­ität. Hier­bei ist die deutsche Datens­chutz-Geset­zge­bung zu beachten.

Um person­en­bezo­gene Daten zu veröf­fent­lichen, ist üblich­er­weise eine expliz­ite Zustim­mung der betro­f­fenen Person erforder­lich. Dies gilt für die bestehende Webober­fläche des Ratsin­form­a­tionssys­tems ebenso wie für die OParl- Schnitt­s­telle. Eine beson­dere Beach­tung soll­ten hier­bei unter anderem E-Mail- Adressen, Anschriften, Fotos und Anwesen­heitslisten finden. Es wird empfohlen, vor Veröf­fent­lichung über die Schnitt­s­telle den zuständi­gen Datens­chutz­beau­ftragten zu kontak­tieren.

1.7 OParl Governance

Im Verlauf der Weit­er­entwicklung können wie bei jedem Stand­ard­is­ier­ung­s­prozess Konf­likte über die Ausrich­tung und die Imple­men­tier­ung entstehen. Ist dies der Fall, so sollte als erstes der Issue Tracker auf Github für eine offene Diskus­sion und eine konstrukt­ive Lösung verwen­det werden.

Sollte es auf Github wider Erwarten keine Lösung geben, wird die Entscheidung an das OParl-Schlich­tungs­gremium weit­ergegeben. In diesem Gremium vertre­ten sind Entwick­ler, Anwender und Daten­bereit­s­teller, so dass eine ausge­wo­gene Weit­er­entwicklung im Interesse aller Akteure gewahrt bleibt.

Es ist natür­lich unab­hängig davon jederzeit erlaubt, einen Fork der OParl-Schnitt­s­telle zu erstel­len und dort neue zunächst nicht mehrheits­fähige Konzepte, Features und Funk­tionen auszuprobieren.

1.8 Autoren

Folgende Personen haben an OParl 1.0 mitgewirkt:

Jayan Areekadan, Jan Erhardt, Stefan Graupner, Lucas Jacob, Jens Kless­mann (*), Andreas Kuck­artz (**), Ernesto Ruge, Konstantin Schütze, Babett Schal­itz, Tim Scheuer­mann, Christine Siegfried (*), Ralf Stern­berg, Marian Stein­bach (*), Bernd Thiem, Thomas Tursics, Jakob Voss, Mari­anne Wulff(*)

(*): Initi­ator(in), (**): bis 4.7.2014

2 Prin­zipien und Funk­tionen der Schnitt­s­telle

2.1 Design­prin­zipien

2.1.1 Aufbauen auf gängiger Praxis

Grundlage für die Erarbei­tung der OParl-Spezi­fika­tion in der vorlie­genden Version ist eine Analyse von aktuell (2012 bis 2016) in Deutsch­land etablier­ten parla­ment­ar­ischen Inform­a­tionssyste­men und ihrer Nutzung. Erklärtes Ziel für diese erste Version ist es, mit möglichst geringem Entwicklung­saufwand auf Seite der Soft­warean­bi­eter und ebenso geringem Migra­tion­saufwand auf Seite der Betreiber zu einer Bereit­s­tel­lung von parla­ment­ar­ischen Inform­a­tionen über eine OParl-API zu gelan­gen. Hier­bei war es von entscheidender Bedeu­tung, dass sich die Inform­a­tionsmod­elle der einsch­lä­gigen Soft­ware­produkte stark ähneln. Für die OParl-Spezi­fika­tion wurde sozus­agen ein Daten­mod­ell als “gemein­samer Nenner” auf Basis der gängigen Praxis konstru­iert.

2.1.2 Verbesser­ung gegenüber dem Status Quo wo möglich

Dort, wo es dem Ziel der einfachen Imple­men­ti­erbar­keit und der einfachen Migra­tion nicht im Weg steht, erlauben sich die Autoren dieser Spezi­fika­tion, auch Funk­tionen aufzun­eh­men, die noch nicht als gängige Praxis im Bereich der Ratsin­form­a­tionssysteme bezeich­net werden können oder welche nur von einzelnen Syste­men unter­stützt werden. Solche Funk­tionen sind dann so integ­riert, dass sie nicht als zwin­gende Anfor­der­ung gelten.

Ein Beis­piel für eine derartige Funk­tion ist die Abbildung von Geod­aten im Kontext von Druck­sachen (oparl:Paper), um beis­piels­weise die Lage eines Bauvorhabens, das in einer Beschlussvor­lage behan­delt wird, zu beschreiben. Zwar ist den Autoren nur ein einziges parla­ment­ar­isches Inform­a­tionssys­tem10 in Deutsch­land bekannt, das Geoin­form­a­tionen – und zwar in Form von Punkt­daten, also einer Kombin­a­tion aus Längen- und Breit­en­gra­dangaben – mit Doku­menten verknüpft. Der Vorteil dieser Funk­tion ist jedoch anhand zahlreicher Anwendungsszenarien, wie z.B. dem Bauin­form­a­tionssys­tem “Bürger baut Stadt”11, beleg­bar. Somit ist in der vorlie­genden OParl-Spezi­fika­tion die Möglich­keit beschrieben, Geod­aten-Objekte einzubetten.

Die Angabe eines einzelnen Punktes ist dabei der einfach­ste Fall. Die Spezi­fika­tion erlaubt auch die Kodier­ung von mehr­eren Objek­ten, die Punkte, Linien oder Poly­gone repräsen­tieren können. Vgl. dazu oparl:Location.

Auch die Ausgabe einer Nur-Text-Version im Kontext der Datei (oparl:File), das den barri­ere­freien Zugriff auf Inhalte oder Index­ier­ung für Voll­textsuch­funk­tionen deut­lich verein­facht, ist eine Möglich­keit, die in der gängigen Praxis noch nicht zu finden ist. Ebenso die Möglich­keit, Beziehun­gen zwis­chen einzelnen Dateien herzus­tel­len, um so z.B. von einer Datei zu anderen Dateien mit identischem Inhalt, aber in anderen tech­nis­chen Formaten zu verweisen, etwa von einer ODT-Datei zu einer PDF-Version.

2.1.3 Selb­st­bes­chreibungs­fähigkeit

Ausgaben des Serv­ers soll­ten so beschaf­fen sein, dass sie für mensch­liche Nutzer­innen weit­ge­hend selb­ster­klärend sein können. Dies betrifft beson­ders die Benen­nung von Objek­ten und Objek­teigenschaften.

Um den Kreis der Entwick­ler­innen und Entwick­ler, die mit einer OParl-API arbeiten können, nicht unnötig einzus­chränken, wird hier­bei grundsätz­lich und soweit sinnvoll auf englischs­prac­hige Begriff­lich­keiten gesetzt.

2.1.4 Erwei­t­er­bar­keit

Imple­men­tierer sollen in der Lage sein, über eine OParl-konforme Schnitt­s­telle auch solche Inform­a­tionen auszugeben, die nicht im Rahmen des OParl-Schemas abge­bil­det werden können. Dies bedeutet zum einen, dass ein System Objekt­typen unter­stützen und ausliefern darf, die nicht (oder noch nicht) im OParl-Schema beschrieben sind. Das bedeutet auch, dass Objekt­typen so um eigene Eigenschaften erweit­ert werden können, die nicht im OParl Schema beschrieben sind.

Ein weit­erer Aspekt betrifft die Abwärtskom­pat­ib­il­ität, also die Kompat­ib­il­ität von OParl-Clients mit zukün­fti­gen Schnitt­s­tel­len. So können beis­piels­weise zukün­ftige Erweit­er­ungen des OParl-Schemas, etwa um neue Objekt­typen, genauso durchge­führt werden, wie die Erweit­er­ungen um hersteller­spezi­fis­che Objekt­typen. Ein Client muss diese Anteile nicht auswer­ten, sofern sie nicht für die Aufgabe des Clients relev­ant sind. Es bedeutet im Umkehr­schluss allerd­ings auch, dass ein Client nicht fehlsch­la­gen darf, falls derartige Erweit­er­ungen vorhanden sind.

2.1.5 Browseab­il­ity/Verlinkung

Klassis­che Webser­vice-Schnitt­s­tel­len erfordern von den Entwick­lern voll­ständige Kennt­nis der ange­botenen Einstiegspunkte und Zugriff­s­meth­oden, gepaart mit sämt­lichen unter­stützten URL-Para­met­ern, um den vollen Funk­tion­sum­fang der Schnitt­s­telle ausschöp­fen zu können.

Parla­ment­ar­ische Inform­a­tionen sind weit­ge­hend in Form von Graphen aufge­baut. Das bedeutet, dass Objekte häufig mit einer Vielzahl anderer Objekte verknüpft sind. So ist eine Person beis­piels­weise Mitglied in mehr­eren Gremien, das Gremium hat mehr­ere Sitzun­gen abge­hal­ten und zu diesen Sitzun­gen gibt es jeweils zahlreiche Druck­sachen, die ihrer­seits wieder zahlreiche Doku­mente enthal­ten.

Eine OParl-Schnitt­s­telle gibt jedem einzelnen Objekt eine eindeut­ige Adresse, eine URL. Somit kann die Schnitt­s­telle den Verweis von einem Objekt, beis­piels­weise einem Gremium, auf ein anderes Objekt, etwa ein Mitglied des Gremi­ums, dadurch ausgeben, dass im Kontext des Gremi­ums die URL des Mitglieds ausgeben wird. Der Client kann somit ausge­hend von einem bestim­mten Objekt die zuge­höri­gen Objekte im System finden, indem er einfach den ange­botenen URLs folgt. Dieses Prin­zip wird auch “Follow Your Nose”12 genannt.

2.2 Zukun­fts­sich­er­heit

Sollte in Zukunft eine zu OParl 1.0 inkom­pat­ible Version 2.0 erscheinen, kann ein Server beide Versionen gleichzeitig unter­stützen, um mit OParl 1.0 Clients kompat­i­bel zu bleiben. Dazu muss der Server die OParl 2.0-Schnitt­s­telle unter einer eigenen URL paral­lel zur bestehenden OParl 1.0-Schnitt­s­telle anbi­eten, siehe Kapitel System.

2.3 URLs

Aufbau einer URL
Aufbau einer URL

Den URLs (für Uniform Resource Locat­ors) kommt eine beson­dere Bedeu­tung zu und es werden deshalb eine Reihe von Anfor­der­ungen an deren Aufbau und Eigenschaften gestellt. Die allge­meine Funk­tion­s­weise von URLs ist in RFC 3986 beschrieben13.

Grundsätz­lich müssen alle Zugriffe zustand­slos erfol­gen können, also ohne Session­in­form­a­tionen wie Cook­ies. Das bedeutet, dass alle Inform­a­tionen, die zum Abrufen eines Objekts nötig sind, in der URL vorhanden sein müssen.

2.3.1 URL-Kanon­is­ier­ung

Um Objekte eindeutig iden­ti­fiz­ieren zu können ist es notwendig, dass ein Server für ein Objekt genau eine unver­än­der­liche URL benutzt. Diese Festle­gung auf genaue eine eindeut­ige URL wird Kanon­is­ier­ung genannt. Ein Server muss deshalb für jedes seiner Objekte eine kanon­is­che URL bestim­men können.

Es wird empfohlen keine IP-Adressen in URLs zu benutzen, sondern einen mit Bedacht gewähl­ten Host­na­men einzu­set­zen. Das ist vor allem im Hinblick auf die Langle­bigkeit der URLs wichtig.

Um die Kanon­is­ier­ung zu gewähr­leisten soll­ten OParl-Server so konfig­ur­iert werden, dass sie nur über eine bestim­mte Domain erreich­bar sind. OParl-Server soll­ten dage­gen möglichst nicht nur über eine IP-Addresse sowieso möglichst auch nicht über weit­ere, nicht kanon­is­che URLs erreich­bar sein.

Wenn ein Server auch durch eine nicht-kanon­is­che URL erreich­bar ist, dann sollte eine ents­prechende HTTP-Anfrage mit einer Weit­er­lei­tung auf die ents­prechende kanon­is­che 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-Best­andteil der URL müssen Server-Imple­men­tierer darüber hinaus beachten, dass zur kanon­is­chen Schreib­weise auch die Groß- und Kleins­ch­reibung, die Anzahl von Schräg­strichen als Pfad-Tren­nzeichen und die Anzahl von führenden Nullen vor numerischen URL-Best­andteilen gehört.

Die Kanon­is­ier­ung umfasst auch den Query-String-Best­andteil der URL. Wie auch beim Pfad gilt, dass für jeden Para­meter und jeden Wert im Query-String genau eine kanon­is­che Schreib­weise gelten muss.

Darüber hinaus sollte der Server-Imple­men­tierer darauf achten, Query-String-Para­meter immer nach demsel­ben Prin­zip zu sortieren. Als Beis­piel: Die beiden URLs

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

unter­scheiden sich ledig­lich in der Reihen­folge der Query-String-Para­meter. Da sie jedoch nicht identisch sind, könnten Clients anneh­men, dass beide URLs verschiedene Objekte repräsen­tieren.

Clients sollen die vom Server geliefer­ten URLs bei Anzeige, Speicher­ung und Weit­erver­arbei­tung nicht verändern.

2.3.2 HTTP und HTTPS

Der Einsatz des verschlüs­sel­ten HTTPS wird empfohlen. Bei Verwendung von HTTPS wird allen URLs “https://” voran gestellt, anson­sten beginnen URLs mit “http://”.

Aus Gründen der URL-Kanon­is­ier­ung ist es zwin­gend notwendig, dass ein Server-Betreiber sich entweder für HTTP oder für HTTPS entscheidet. Es jedoch möglich, eine Weit­er­lei­tung (HTTP Status-Code 301) einzurichten. Eine Weit­er­lei­tung von HTTPS auf HTTP wird nicht empfohlen.

2.3.3 Langle­bigkeit

Weit­er­hin sollen URLs langle­big sein, sodass sie möglichst lange zur Abfrage des dazuge­höri­gen Objekts verwen­det werden können.

In URLs soll­ten deshalb nur Eigenschaften des Objekts aufgen­om­men werden, die nicht verändert werden. Ändert sich beis­piels­weise die Kennung einer Druck­sache im Verlauf ihrer Existenz, dann scheidet sie für die Bildung der URL aus.

Des weit­eren sollen Eigenschaften der Imple­men­tier­ung nicht sicht­bar sein. Ist ein OParl-Server beis­piels­weise in PHP geschrieben, sollte dies nicht dazu führen, dass im Pfad ein Best­andteil wie “oparl.php/” erscheint.

Weit­ere Empfehlun­gen für langle­bige URLs liefern Tim Bern­ers-Lee14 sowie die Europäis­che Kommis­sion15.

2.4 JSON-Ausgabe

Ein OParl-Server muss Objekte in Form von JSON ausgeben. Die Abkürzung JSON steht für “JavaScript Object Nota­tion”. Das JSON-Format ist in RFC462716 beschrieben.

Sämt­liche JSON-Ausgabe muss in UTF-8 ohne Byte Order Mark (BOM) geschehen. Dies ents­pricht RFC 7159 Section 8.117. Gemäß RFC 7159 Section 718 darf UTF-8 String-Escap­ing verwen­det werden. XML-/HTML-String-Escap­ing darf nicht verwen­det werden.

Eine Syntaxüber­sicht und weit­ere Imple­men­tier­ung­sh­in­weise finden sich auf json.org.

Es ist gest­at­tet, weit­ere zur JSON-Ausgabe semantisch identische Formate19 anzu­bi­eten. Da diese jedoch nicht Best­andteil der Spezi­fika­tion sind, soll­ten sich Clients nicht auf deren Vorhanden­sein verlassen.

2.4.1 In OParl verwen­dete Daten­typen

In OParl werden alle in JSON definier­ten Dateitypen verwen­det:

object:

Objects ents­prechen der Defin­i­tion des Objects in RFC 7159 Section 4

array:

Arrays ents­prechen der Defin­i­tion des Arrays in RFC 7159 Section 5

integer:

Integers ents­prechen der Defin­i­tion des Integer-Parts der Number aus RFC 7159 Section 6

boolean:

Booleans ents­prechen der Defin­i­tion von Boolean in RFC 7159 Section 3

string:

Strings ents­prechen der Defin­i­tion der Unicode-Strings aus RFC 7159 Section 7

In OParl werden verschiedene String-Typen verwen­det. Wenn von diesen Typen gesprochen wird, so wird auto­mat­isch ein JSON-String voraus­ge­setzt:

url:

Eine URL ist ein String, der ents­prechend des URL-Kapi­tels form­atiert wurde.

url (Object):

Eine URL mit in Klam­mern ange­hängtem Objekt­name beschreibt eine URL auf eben diesen Objektty­pus.

date:

Ents­pricht einem Datum ohne Uhrzeit und ohne Zeitzone, wie sie im folgenden Abschnitt beschrieben werden.

date-time:

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

2.4.2 Datums- und Zeit­angaben

Für Datums- und Zeit­angaben werden die in ISO 8601 beschriebenen Formate verwen­det. Ein Datum (date) muss muss also die Form yyyy-mm-dd besitzen und ein Zeit­punkt (date-time) muss in der Form yyyy-mm-ddThh:mm:ss+hh:mm angegeben werden.

Beis­piel für ein Datum: 1969-07-21

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

2.4.3 null-Werte und leere Listen

JSON erlaubt es grundsätz­lich, Eigenschaften mit dem Wert null zu verse­hen. Eigenschaften soll­ten nicht mit dem Wert null ausgegeben werden, wenn zu einer Eigenschaft keine Daten vorlie­gen. Oblig­at­or­ische Eigenschaften dürfen nicht den Wert null haben.

Im Fall von Arrays erlaubt JSON grundsätz­lich die Ausgabe von [] für leere Arrays. Wie bei null wird auch hier empfohlen, auf die Ausgabe einer Eigenschaft mit dem Wert [] zu verzichten, wenn zu einer Eigenschaft keine Daten vorlie­gen. Bei oblig­at­or­ischen Eigenschaften muss jedoch eine leere Liste ausgegeben werden.

2.5 Objekt­l­isten und Paginier­ung

Oft wird für ein Attribut kein Wert ausgegeben, sondern ein anderes Objekt oder eine Liste von Objek­ten. Dabei kann eine Refer­enz auf das Objekt bzw. die Objekt­l­iste angegeben werden, oder das Objekt bzw. die Objekt­l­ist wird intern ausgegeben. Beide Verfahren sollen im Folgenden erklärt werden.

2.5.1 Refer­en­zier­ung von Objek­ten via URL

Bei der Refer­en­zier­ung einzel­ner Objekte wird eine URL angegeben, welche auf das ents­prechende Objekt verweist. Der Typ ist hier­bei ein string (url: Objekt-ID). Ein Beis­piel 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 Refer­en­zen ausgegeben werden. Der Typ ist in diese Fall array of string (url: Objekt-ID).

Ein Beis­piel 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 ausgegeben werden. Dabei wird das gesamte Objekt als Wert eines Attributs angegeben. Ein Beis­piel für ein internes 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 ausgegeben werden. Hier das Beis­piel des Attrib­utes 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­l­isten

Es können auch Refer­en­zen zu sogenan­nten externen Objekt­l­isten angegeben werden. Die externe Liste enthält dann die betref­fenden Objekte in Form einer Listenaus­gabe. Ein Beis­piel 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­l­iste:

{
    "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 Paginier­ung

Für externe Objekt­l­isten ist eine Aufteilung sogenan­nte Listen­seiten vorgese­hen, wobei jede Listen­seite eine eigene URL erhält. Das dient dazu, die bei der jewei­li­gen Anfrage über­tra­genen Daten­men­gen und Antwortzeiten zu begren­zen.

Die Entscheidung, ob eine externe Objekt­l­iste mit Paginier­ung ausgegeben wird, liegt allein beim Server. Bei Listen mit mehr als 100 Einträ­gen wird dies empfohlen.

Ein Server muss für eine stabile Sortier­ung von Listenein­trä­gen sorgen. Das heißt, dass die Sortier­ung der Einträge einem konstanten Prin­zip folgt und sich nicht von Abfrage zu Abfrage ändert. Das kann z.B. durch die Sortier­ung von Objek­ten nach einer eindeut­i­gen und unver­än­der­lichen ID erreicht werden.

Jede Listen­seite muss die Attrib­ute folgenden Attrib­ute enthal­ten:

  • data (Array der intern ausgegebenen Objekte)

  • pagin­a­tion (Object)

  • links (Object)

Für pagination sind die folgenden Attrib­ute festgelegt, die alle optional sind:

  • totalElements: Gibt die Gesamtan­zahl der Objekte in der Liste an. Diese Zahl kann sich unter Umständen bis zum Aufruf der näch­sten Listen­seiten ändern.

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

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

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

Für links sind folgende Attrib­ute festgelegt, die bis auf next alle optional sind:

  • first: URL der ersten Listen­seite

  • prev: URL der vorheri­gen Listen­seite

  • self: Die kanon­is­che URL dieser Listen­seite

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

  • last: URL der letzten 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­l­isten können mit den URL-Para­met­ern created_since, created_until, modified_since und modified_until einges­chränkt werden. Diese Para­meter beziehen sich auf die ents­prechenden Attrib­ute der jewei­li­gen Objekte, wobei reser­vierte Zeichen URL-Kodiert werden müssen. Ein Server muss diese Para­meter bei allen externen Objekt­l­isten unter­stützen.

Die Filter werden vom Client benutzt, indem die gewün­schten URL-Para­meter an die URL der ersten Listen­si­ete ange­hängt werden. Bei allen weit­eren Seiten hat der Server sicherzus­tel­len, dass die verwen­deten Filter erhal­ten bleiben. Lautet die URL für eine Liste von Druck­sachen wie folgt:

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

kann der Client die folgende URL bilden, um die Ausgabe der Liste auf Druck­sachen einzus­chränken, 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

Mehr­ere Para­meter können auch gemein­sam verwen­det werden. So kann man z.B. eine Eins­ch­ränkung 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 genan­nten URL-Para­meter erwarten grundsätz­lich eine voll­ständige date-time-Angabe.

Des weit­eren kann mit dem URL-Para­meter limit die Länge einer Listen durch den Client begrenzt werden. Ein Client darf nicht erwarten, dass sich ein Server an seine limit-Anfrage hält.

2.6 Cross-Origin Resource Shar­ing (CORS)

Wenn Webbrowser mittels Skript auf JSON-Ressourcen zugre­ifen sollen unter­lie­gen diese Zugriffe üblich­er­weise einer Same-Origin-Policy (SOP). Das heißt, eine Anfrage ist nur an den Server zulässig, der auch das initii­er­ende Skript ausgeliefert hat. Anfra­gen an andere Server werden vom Browser block­iert. Diese Eins­ch­ränkung dient im Allge­meinen der Sich­er­heit von Webbrowsern.20

Um die Daten von OParl-Servern auch im Kontext von Weban­wendun­gen flex­i­bel nutzen zu können, ist die Über­windung der SOP nötig. Hierzu dient Cross-Origin Resource Shar­ing (CORS)21. Mittels CORS kann ein Server mitteilen, dass bestim­mte von ihm ausgelieferte Ressourcen auch inner­halb von Webap­p­lika­tionen genutzt werden dürfen, die nicht vom selben Server ausgeliefert werden. Tech­nisch wird dies durch Ausgabe zusätz­licher HTTP-Header erreicht.

OParl-Server müssen für jegliche Anfrage, die mit der Ausgabe von JSON-Daten beant­wor­tet wird (das sind alle Anfra­gen außer Dateizu­griffe) den folgenden 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 Meth­ode GET bein­hal­ten.

Entwick­ler­innen von Weban­wendun­gen soll­ten sich darüber bewusst sein, dass durch die direkte Einbindung von Skripten Drit­ter in ihre Anwendun­gen mögliche Sich­er­heit­s­risiken entstehen. Für den Fall, dass ein OParl-Server, etwa in Folge einer Manip­u­la­tion, Schad­code ausliefert, könnte dieser unmit­tel­bar von Skripten im Browser ausge­führt werden.

2.7 Dateizu­griffe

Mit dem Begriff “Datei” sind im Sinne dieser Spezi­fika­tion alle Ressourcen gemeint, die von einem OParl-Server zur Verfü­gung gestellt werden und deren Metad­aten über die JSON-API als oparl:File abgerufen werden können. Es handelt sich dabei beis­piels­weise um Textdok­u­mente im PDF-Format oder Abbildun­gen im JPEG- oder PNG-Format.

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

2.7.1 Empfehlun­gen für Dateizu­griffe

  • Ein Server sollte die Verwendung von Kompres­sion gemäß dem HTTP-Stand­ard unter­stützen.

  • Ein Server sollte “Condi­tional GET”, insbeson­dere If-Modified-Since und If-None-Match sowie “Chunked GET” unter­stützen.

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

  • Bei gelöschten Dateien sollte der HTTP-Statuscode 410 verwen­det werden.

2.7.2 Allge­meiner Zugriff und expliz­iter Down­load

Mit der im oparl:File zwin­gend anzugebenden Eigenschaft accessUrl liefert der Server dem Client eine URL, die dem allge­meinen Zugriff auf die Datei dient. Beim Zugriff auf dieser URL darf der Server nicht den Content-Disposition-Header mit dem Para­meter attachment senden. 22

Es wird daher empfohlen, zusätz­lich eine Eigenschaft downloadUrl anzu­bi­eten. Beim Zugriff auf die Down­load-URL muss der Server in der HTTP-Antwort einen Content-Disposition-Header senden, der als ersten Para­meter den Typ attachment enthält und mit dem filename-Para­meter den Namen der Datei angibt.

Beis­piel:

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:Organ­isa­tion, oparl:Person, oparl:Meet­ing, oparl:Paper, oparl:File und oparl:Loca­tion muss in OParl geson­dert vermerkt werden. Es darf insbeson­dere nicht einfach gelöscht werden, so dass unter der betref­fenden URL kein gültiges Objekt ausgeliefert wird.

Hinter­grund ist, dass alle OParl-Clients zeit­nah erfahren können müssen, wenn ein Objekt gelöscht wurde. Dies wird durch die folgenden Regeln gewähr­leistet.

Wenn ein Objekt gelöscht wird,

  • muss das Objekt das zusätz­liche Attribut deleted: true bekom­men
  • muss das Attribut modified auf den Zeit­punkt der Löschung setzen
  • müssen die Attrib­ute id, type und created erhal­ten bleiben

Als HTTP-Statuscode muss weit­er­hin 200 verwen­det werden.

Die Objekte Legis­lat­iveTerm, Member­ship, AgendaItem und Consulta­tion können dage­gen einfach gelöscht werden. Beim Löschen dieser Objekte muss allerd­ings der Wert modified aller Objekte aktu­al­is­iert werden, in die dieses Objekt einge­bunden war.

Dies garantiert, dass das gelöschte Objekt beim Updaten eines Client-Daten­be­st­andes aktu­al­is­iert wird, falls der Client nur seit dem letzten Update aktu­al­is­ierte Objekte abruft.

2.9 Ausnah­me­behand­lung

Wenn ein Server eine Anfrage nicht bearbeiten kann, z.B. weil die URL ungültig ist oder das ange­fragte Objekt nicht existiert, dann sollte er mit dem ents­prechenden HTTP-Statuscode antworten.

Ein Client kann nicht voraus­set­zen, dass im Fall einer Ausnahme noch weit­ere verwert­bare Inform­a­tionen wie ein Fehler­mel­dung gesen­det werden.

3 Schema

Dieses Kapitel beschreibt das Schema von OParl. Das Schema definiert die Objekt­typen und ihre Eigenschaften. Darüber hinaus ist im Schema auch festgelegt, in welcher Beziehung verschiedene Objekt­typen zu einander stehen.

OParl Objekttypen: Ein Überblick. Die Zahl an den Verbindungslinien entspricht der Anzahl der Attribute, die eine oder mehrere Verknüpfungen herstellen.
OParl Objekt­typen: Ein Überblick. Die Zahl an den Verbindungslinien ents­pricht der Anzahl der Attrib­ute, die eine oder mehr­ere Verknüp­fun­gen herstel­len.

3.1 Die Objekte

OParl nutzt folgenden Objekte:

  • oparl:System
  • oparl:Body
  • oparl:Legis­lat­iveTerm
  • oparl:Organ­iz­a­tion
  • oparl:Person
  • oparl:Member­ship
  • oparl:Meet­ing
  • oparl:AgendaItem
  • oparl:Paper
  • oparl:Consulta­tion
  • oparl:File
  • oparl:Loca­tion

Einige Objekte werden intern in anderen Objek­ten ausgegeben:

  • oparl:Legis­lat­iveTerm wird intern in oparl:Body ausgegeben
  • oparl:Member­ship wird intern in oparl:Person ausgegeben
  • oparl:AgendaItem wird intern in oparl:Meet­ing ausgegeben
  • oparl:Consulta­tion wird intern in Paper ausgegeben
  • oparl:File wird intern in oparl:Meet­ing, oparl:AgendaItem und oparl:Paper ausgegeben
  • oparl:Loca­tion wird intern in oparl:Body, oparl:Organ­iz­a­tion, oparl:Meet­ing und oparl:Paper ausgegeben

Grundsätz­lich muss jedes Objekt unter seiner ID abruf­bar sein – auch dann, wenn das Objekt in anderen Objek­ten intern ausgegeben wird. Bei der internen Ausgabe wird beim internen Objekt auf die Rück­refer­enz auf das Elter­n­ob­jekt verzichtet.

Als Beis­piel 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 enthaltene oparl:File muss auch einzeln abgerufen werden können. Dabei kommt dann das Eltern-Objekt als zusätz­liches Attribut 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­liche Attribut ist ein Array, da es auch möglich ist, dass Dateien von mehr­eren Haupto­b­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­gre­ifende Aspekte

3.2.1 Voll­ständigkeit

Alle regulär öffent­lich abruf­baren Inform­a­tionen soll­ten auch in OParl ausgegeben werden, solange dies nicht den Datens­chutzbestim­mun­gen wider­spricht. Daher sind sämt­liche Felder im Schema als empfohlen zu behan­deln, wenn nicht explizit etwas anderes angegeben wurde.

3.2.2 Hersteller­spezi­fis­che Erweit­er­ungen

In OParl können zusätz­liche, hersteller­spezi­fis­che Eigenschaften hinzuge­fügt werden. Dazu wird diesen Eigenschaften ein Hersteller­prefix voranges­tellt. So könnte man z.B. oparl:Person um eine Faxnum­mer erweit­ern:

"BeispielHersteller:faxNumber": "012345678",

3.2.3 URL-Pfade in den Beis­pielen

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­fika­tion keine Festle­gun­gen dazu. Die in den Beis­pielen verwen­deten URLs zeigen einen möglichen Weg zur Umset­zun­gen der Empfehlun­gen in URLs.

3.3 Eigenschaften mit Verwendung in mehr­eren Objekt­typen

3.3.1 id

Die Eigenschaft id enthält den eindeut­i­gen Bezeich­ner des Objekts, nämlich seine URL. Dies ist ein zwin­gendes Merkmal für jedes Objekt.

3.3.2 type

Objekt­typen­angabe des Objekts, zwin­gend für jedes Objekt. Der Wert ist eine Namespace-URL. Für die OParl-Objekt­typen sind die folgenden URLs definiert:

Typ (kurz) Namespace-URL
oparl:AgendaItem https://schema.oparl.org/1.0/AgendaItem
oparl:Body https://schema.oparl.org/1.0/Body
oparl:Consultation https://schema.oparl.org/1.0/Consulta­tion
oparl:File https://schema.oparl.org/1.0/File
oparl:LegislativeTerm https://schema.oparl.org/1.0/Legis­lat­iveTerm
oparl:Location https://schema.oparl.org/1.0/Loca­tion
oparl:Meeting https://schema.oparl.org/1.0/Meet­ing
oparl:Membership https://schema.oparl.org/1.0/Member­ship
oparl:Organization https://schema.oparl.org/1.0/Organ­iz­a­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 Eigenschaften können bei vielen Objekt­typen genutzt werden um den Namen des Objekts anzugeben. Üblich­er­weise ist name eine Pflichteigenschaft für den ausges­chriebenen offiz­i­el­len Namen, während shortName optional angegeben werden kann. Dies ist dann zu empfehlen, wenn zu einem Namen eine kurze bzw. kompakte und eine längere, aber weni­ger nutzer­fre­und­liche Vari­ante existieren. So ist “Innen­min­is­terium” die Kurz­form des offiz­i­el­len “Bundesmin­is­terium des Inneren”.

3.3.4 license

Mit license wird angegeben, 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 bedeutet das, dass alle Objekte dieses Systems bzw. der Körper­schaft unter der angegebenen Lizenz veröf­fent­licht werden, sofern nicht das einzelne Objekt eine anders lautende Lizenz-URL angibt. Es wird empfohlen, die Lizen­zin­form­a­tion sofern möglich global am oparl:System Objekt mitzuteilen und auf redund­ante Inform­a­tionen zu verzichten.

3.3.5 created

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

Diese Eigenschaft muss in allen Objekt­typen angegeben werden, die nicht in anderen Objek­ten intern ausgegeben werden.

3.3.6 modified

Diese Eigenschaft kennzeich­net stets Datum und Uhrzeit der letzten Änder­ung des jewei­li­gen Objekts.

Diese Eigenschaft muss – genau wie created – in allen Objekt­typen angegeben werden, die nicht in anderen Objek­ten intern ausgegeben werden.

Es ist zwin­gend, dass bei jeder Änder­ung eines Objekts der Wert dieses Attributs auf die zu diesem Zeit­punkt aktuelle Uhrzeit gesetzt wird, da ein Client in der Regel seinen Daten­be­st­and nur auf Basis dieses Attributs verlust­frei aktu­al­is­ieren kann.

3.3.7 keyword

Die Eigenschaft keyword dient der optionalen Kategor­is­ier­ung eines Objekts.

3.3.8 web

Gibt die URL einer Website an, die das Objekt im Browser darstellt. Das ist z.B. die HTML-Ansicht eines parla­ment­ar­ischen Inform­a­tionssys­tems.

3.3.9 deleted

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

3.4 System

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

Möchte ein Server mehr­ere zuein­ander inkom­pat­ible OParl-Versionen unter­stützen, dann muss der Server für jede Version eine eigenen OParl-Schnitt­s­telle mit einem eigenen System-Objekt ausgeben.

Name Typ Beschreibung
id url
type string
oparlVersion string ZWINGEND Die URL der OParl-Spezi­fika­tion, die von diesem Server unter­stützt wird. Aktuell kommt hier nur ein Wert in Frage. Mit zukün­fti­gen OParl-Versionen kommen weit­ere mögliche URLs hinzu. Wert: https://schema.oparl.org/1.0/
otherOparlVersions array of url (System) Dient der Angabe von System-Objek­ten mit anderen OParl-Versionen.
license url Lizenz, unter der durch diese API abruf­baren Daten stehen, sofern nicht am einzelnen Objekt anders angegeben. Siehe license.
body url ZWINGEND Link zur Objekt­l­iste mit allen Körper­schaften, die auf dem System existieren.
name string Nutzer­fre­und­licher Name für das System, mit dessen Hilfe Nutzer­innen und Nutzer das System erkennen und von anderen unter­scheiden können.
contactEmail string E-Mail-Adresse für Anfra­gen zur OParl-API. Die Angabe einer E-Mail-Adresse dient sowohl Nutzer­Innen wie auch Entwick­ler­innen von Clients zur Kontak­tauf­nahme mit dem Betreiber.
contactName string Name der Ansprech­part­nerin bzw. des Ansprech­part­ners oder der Abteilung, die über die in contactEmail angegebene Adresse erreicht werden kann.
website url URL der Website des parla­ment­ar­ischen Inform­a­tionssys­tems
vendor url URL der Website des Soft­warean­bi­eters, von dem die OParl-Server-Soft­ware stammt.
product url URL zu Inform­a­tionen über die auf dem System genutzte OParl-Server-Soft­ware
created date-time
modified date-time
web url
deleted boolean
Beis­piel
{
    "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 Objekttyp oparl:Body dient dazu, eine Körper­schaft zu repräsen­tieren. Eine Körper­schaft ist in den meisten Fällen eine Gemeinde, eine Stadt oder ein Landkreis.

In der Regel sind auf einem OParl-Server Daten von genau einer Körper­schaft gespeich­ert und es wird daher auch nur ein Body-Objekt ausgegeben. Sind auf dem Server jedoch Daten von mehr­eren Körper­schaften gespeich­ert, muss für jede Körper­schaft ein eigenes Body-Objekt ausgegeben werden.

Name Typ Beschreibung
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 offiz­i­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 einzelnen Objekt anders angegeben. Siehe license.
licenseValidSince date-time Zeit­punkt, seit dem die unter license angegebene Lizenz gilt. Vorsicht bei Änder­ungen der Lizenz die zu restrikt­iveren Bedin­gun­gen führen!
oparlSince date-time Zeit­punkt, ab dem OParl für dieses Body bereit­ges­tellt wurde. Dies hilft, um die Daten­qual­ität einzuschätzen, denn erst ab der Einrich­tung für OParl kann sich­erges­tellt werden, dass sämt­liche Werte korrekt in der Original-Quelle vorlie­gen.
ags string Der acht­s­tel­lige Amtliche Gemein­des­chlüs­sel24.
rgs string Der zwölf­s­tel­lige Region­alschlüs­sel.
equivalent array of url Dient der Angabe zusätz­licher URLs, die dies­elbe Körper­schaft repräsen­tieren. Hier können beis­piels­weise der ents­prechende Eintrag der gemein­samen Norm­d­atei der Deutschen Nation­al­bib­lio­thek25, der DBPe­dia26 oder der Wiki­pe­dia27 angegeben werden. Body- oder System-Objekte mit anderen OParl-Versionen dürfen nicht Teil der Liste sein.
contactEmail string Dient der Angabe einer Kontakt-E-Mail-Adresse. Die Adresse soll die Kontak­tauf­nahme zu einer für die Körper­schaft und ideal­er­weise das parla­ment­ar­ische Inform­a­tionssys­tem zuständi­gen Stelle ermög­lichen.
contactName string Name oder Bezeich­nung der mit contactEmail erreich­baren Stelle.
organization url ZWINGEND Link zur Objekt­l­iste mit allen Grup­pier­ungen der Körper­schaft.
person url ZWINGEND Link zur Objekt­l­iste mit allen Personen der Körper­schaft.
meeting url ZWINGEND Link zur Objekt­l­iste mit allen Sitzun­gen der Körper­schaft.
paper url ZWINGEND Link zur Objekt­l­iste mit allen Druck­sachen der Körper­schaft.
legislativeTerm array of object (Legis­lat­iveTerm) ZWINGEND Objekt­l­iste mit den Wahlperi­oden der Körper­schaft.
classification string Art der Körper­schaft.
location object (Loca­tion) Ort, an dem die Körper­schaft beheimatet ist.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.5.1 Legis­lat­iveTerm

Dieser Objekttyp dient der Beschreibung einer Wahlperi­ode.

Name Typ Beschreibung
id url
type string
body url (Body) Rück­refer­enz auf die Körper­schaft, welche nur dann ausgegeben werden muss, wenn das Legis­lat­iveTerm-Objekt einzeln abgerufen wird, d.h. nicht Teil einer internen Ausgabe ist.
name string Nutzer­fre­und­liche Bezeich­nung der Wahlperi­ode.
startDate date Der erste Tag der Wahlperi­ode.
endDate date Der letzte Tag der Wahlperi­ode.
keyword array of string
web url
Beis­piel
{
    "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 Organ­iz­a­tion

Dieser Objekttyp dient dazu, Grup­pier­ungen von Personen abzu­bilden, die in der parla­ment­ar­ischen Arbeit eine Rolle spielen. Dazu zählen in der Praxis insbeson­dere Frak­tionen und Gremien.

Name Typ Beschreibung
id url
type string
body url (Body) Körper­schaft, zu der diese Grup­pier­ung gehört.
name string Offiz­i­elle (lange) Form des Namens der Grup­pier­ung.
membership array of url (Member­ship) Mitglied­schaften dieser Grup­pier­ung.
meeting url (Meet­ing) URL auf eine externe Objekt­l­iste mit den Sitzun­gen dieser Grup­pier­ung. Invers zur Eigenschaft organization der Klasse oparl:Meeting
shortName string Der Name der Grup­pier­ung als Kurz­form.
post array of string Posi­tionen, die für diese Grup­pier­ung vorgese­hen sind.
subOrganizationOf url (Organ­iz­a­tion) URL einer even­tuel­len über­geord­neten Grup­pier­ung.
organizationType string Grobe Kategor­is­ier­ung der Grup­pier­ung. Mögliche Werte sind “Gremium”, “Partei”, “Frak­tion”, “Verwal­tungs­bereich”, “externes Gremium”, “Insti­tu­tion” und “Sonstiges”.
classification string Die Art der Grup­pier­ung. In Frage kommen z.B. “Parla­ment”, “Ausschuss”, “Beirat”, “Projekt­beirat”, “Kommis­sion”, “AG”, “Verwal­tung­s­rat”, “Frak­tion” oder “Partei”. Die Angabe sollte möglichst präzise erfol­gen. Außer­dem soll­ten Abkürzun­gen vermieden werden. Für die höch­ste demokrat­ische Instanz in der Kommune sollte immer der Begriff “Parla­ment” verwen­det werden, nicht “Rat” oder “Hauptausschuss”.
startDate date Gründungs­datum der Grup­pier­ung. Kann z. B. das Datum der konstitu­i­er­enden Sitzung sein.
endDate date Datum des letzten Tages der Existenz der Grup­pier­ung.
website url Allge­meine Website der Grup­pier­ung.
location object (Loca­tion) Ort, an dem die Organ­isa­tion beheimatet ist
externalBody url (Body) Externer OParl Body, der dieser Organ­isa­tion ents­pricht. Diese Eigenschaft ist dafür gedacht auf even­tuelle konkretere OParl-Schnitt­s­tel­len zu verweisen. Ein Beis­piel hier­für wäre eine Stadt, die sowohl ein über­gre­ifendes parla­ment­ar­isches Inform­a­tionssys­tem, als auch bezirksspezi­fis­che Systeme hat.
keyword array of string
created date-time
modified date-time
web url
deleted boolean
Beis­piel
{
    "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­liche Person, die in der parla­ment­ar­ischen Arbeit tätig und insbeson­dere Mitglied in einer Grup­pier­ung (oparl:Organ­iz­a­tion) ist, wird mit einem Objekt vom Typ oparl:Person abge­bil­det.

Name Typ Beschreibung
id url
type string
body url (Body) Körper­schaft, zu der die Person gehört.
name string Der voll­ständige Name der Person mit akademis­chem Grad und dem gebräuch­lichen Vorna­men, wie er zur Anzeige durch den Client genutzt werden kann.
familyName string Fami­li­en­name bzw. Nach­name.
givenName string Vorname bzw. Tauf­name.
formOfAddress string Anrede.
affix string Namenszus­atz (z.B. jun. oder MdL.)
title array of string Akademis­che Titel
gender string Geschlecht. Empfohlene Werte sind female, male und other. Für den Fall, dass das Geschlecht der Person unbekannt ist, sollte die Eigenschaft nicht ausgegeben werden.
phone array of string Tele­fon­num­mern der Person.
email array of string E-Mail-Adressen der Person.
location url (Loca­tion) Refer­enz der Kontakt-Anschrift der Person.
status array of string Status, d.h. Rollen in der Kommune.
membership array of object (Member­ship) Mitglied­schaften der Person in Grup­pier­ungen, z. B. Gremien und Frak­tionen. Es sollen sowohl aktuelle als auch vergan­gene Mitglied­schaften angegeben werden
life string Kurzer Inform­a­tion­s­text zur Person. Eine Länge von weni­ger als 300 Zeichen ist empfohlen
lifeSource string Angabe der Quelle, aus der die Inform­a­tionen für life stam­men. Bei Angabe von life ist diese Eigenschaft empfohlen
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 Personen in Grup­pier­ungen darges­tellt. Diese Mitglied­schaften können zeit­lich begrenzt sein. Zudem kann abge­bil­det werden, dass eine Person eine bestim­mte Rolle bzw. Posi­tion inner­halb der Grup­pier­ung inne hat, beis­piels­weise den Vorsitz einer Frak­tion.

Name Typ Beschreibung
id url
type string
person url (Person) Rück­refer­enz auf Person, welches nur dann ausgegeben werden muss, wenn das Member­ship-Objekt einzeln abgerufen wird, d.h. nicht Teil einer internen Ausgabe ist.
organization url (Organ­iz­a­tion) Die Grup­pier­ung, in der die Person Mitglied ist oder war.
role string Rolle der Person für die Grup­pier­ung. Kann genutzt werden, um verschiedene Arten von Mitglied­schaften zum Beis­piel in Gremien zu unter­scheiden.
votingRight boolean Gibt an, ob die Person in der Grup­pier­ung stimmberechtigtes Mitglied ist.
startDate date Datum, an dem die Mitglied­schaft beginnt.
endDate date Datum, an dem die Mitglied­schaft endet.
onBehalfOf url (Organ­iz­a­tion) Die Grup­pier­ung, für die die Person in der unter organization angegebenen Organ­isa­tion sitzt. Beis­piel: Mitglied­schaft als Vertreter einer Rats­frak­tion, einer Grup­pier­ung oder einer externen Organ­isa­tion.
keyword array of string
web url
Beis­piel
{
    "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 Meet­ing

Eine Sitzung ist die Versammlung einer oder mehr­erer Grup­pier­ungen (oparl:Organ­iz­a­tion) zu einem bestim­mten Zeit­punkt an einem bestim­mten Ort.

Die geladenen Teil­nehmer der Sitzung sind jeweils als Objekte vom Typ oparl:Person, die in ents­prechender Form refer­en­ziert werden. Verschiedene Dateien (Einladung, Ergeb­nis- und Wort­pro­tokoll, sonstige Anla­gen) können refer­en­ziert werden.

Die Inhalte einer Sitzung werden durch Tage­sord­nung­spunkte (oparl:AgendaItem) abge­bil­det.

Name Typ Beschreibung
id url
type string
name string Name der Sitzung.
meetingState string Aktueller Status der Sitzung. Empfohlen ist die Verwendung von terminiert (geplant), eingeladen (vor der Sitzung bis zur Freigabe des Protokolls) und durchgeführt (nach Freigabe des Protokolls).
cancelled boolean Wenn die Sitzung ausfällt, wird cancelled auf true gesetzt.
start date-time Datum und Uhrzeit des Anfang­szeit­punkts der Sitzung. Bei einer zukün­fti­gen Sitzung ist dies der geplante Zeit­punkt, bei einer stat­tge­fundenen kann es der tatsäch­liche Startzeit­punkt sein.
end date-time Endzeit­punkt der Sitzung als Datum/Uhrzeit. Bei einer zukün­fti­gen Sitzung ist dies der geplante Zeit­punkt, bei einer stat­tge­fundenen kann es der tatsäch­liche Endzeit­punkt sein.
location object (Loca­tion) Sitzung­sort.
organization array of url (Organ­iz­a­tion) Grup­pier­ungen, denen die Sitzung zugeord­net ist. Im Regel­fall wird hier eine Grup­pier­ung verknüpft sein, es kann jedoch auch gemein­same Sitzun­gen mehr­erer Grup­pier­ungen geben. Das erste Element sollte dann das feder­führende Gremium sein.
participant array of url (Person) Personen, die an der Sitzung teil­gen­om­men haben (d.h. nicht nur die einge­ladenen Personen, sondern die tatsäch­lich anwesenden). Diese Eigenschaft kann selb­stver­ständ­lich erst nach dem Stattfinden der Sitzung vorkom­men.
invitation object (File) Einladungs­dok­u­ment zur Sitzung.
resultsProtocol object (File) Ergeb­n­is­pro­tokoll zur Sitzung. Diese Eigenschaft kann selb­stver­ständ­lich erst nachdem Stattfinden der Sitzung vorkom­men.
verbatimProtocol object (File) Wort­pro­tokoll zur Sitzung. Diese Eigenschaft kann selb­stver­ständ­lich erst nach dem Stattfinden der Sitzung vorkom­men.
auxiliaryFile array of object (File) Dateian­hang zur Sitzung. Hier­mit sind Dateien gemeint, die üblich­er­weise mit der Einladung zu einer Sitzung verteilt werden, und die nicht bereits über einzelne Tage­sord­nung­spunkte refer­en­ziert sind.
agendaItem array of object (AgendaItem) Tage­sord­nung­spunkte der Sitzung. Die Reihen­folge ist relev­ant. Es kann Sitzun­gen ohne TOPs geben.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.8.1 AgendaItem

Tage­sord­nung­spunkte sind die Best­andteile von Sitzun­gen (oparl:Meeting). Jeder Tage­sord­nung­spunkt widmet sich inhalt­lich einem bestim­mten Thema, wozu in der Regel auch die Bera­tung bestim­mter Druck­sachen gehört.

Die Beziehung zwis­chen einem Tage­sord­nung­spunkt und einer Druck­sache wird über ein Objekt vom Typ oparl:Consultation herges­tellt, das über die Eigenschaft consultation refer­en­ziert werden kann.

Name Typ Beschreibung
id url
type string
meeting url (Meet­ing) Rück­refer­enz auf das Meet­ing, welches nur dann ausgegeben werden muss, wenn das agendaItem-Objekt einzeln abgerufen wird, d.h. nicht Teil einer internen Ausgabe ist.
number string Glie­der­ungs-"Nummer" des Tage­sord­nung­spunktes. Eine beliebige 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-Attribut von oparl:Meeting festgelegt, sollte allerd­ings zu dieser identisch sein.
name string Das Thema des Tage­sord­nung­spunktes.
public boolean Kennzeich­net, ob der Tage­sord­nung­spunkt zur Behand­lung in öffent­licher Sitzung vorgese­hen ist/war. Es wird ein Wahrheit­swert (true oder false) erwar­tet.
consultation url (Consulta­tion) Bera­tung, die diesem Tage­sord­nung­spunkt zugew­iesen ist.
result string Kategor­ische Inform­a­tion darüber, welches Ergeb­nis die Bera­tung des Tage­sord­nung­spunktes erbracht hat, in der Bedeu­tung etwa “Unver­ändert beschlossen” oder “Geändert beschlossen”.
resolutionText string Falls in diesem Tage­sord­nung­spunkt ein Beschluss gefasst wurde, kann hier ein Text angegeben werden. Das ist beson­ders dann in der Praxis relev­ant, wenn der gefasste Beschluss (z. B. durch Änder­ungsan­trag) von der Beschlussvor­lage abweicht.
resolutionFile object (File) Falls in diesem Tage­sord­nung­spunkt ein Beschluss gefasst wurde, kann hier eine Datei angegeben werden. Das ist beson­ders dann in der Praxis relev­ant, wenn der gefasste Beschluss (z. B. durch Änder­ungsan­trag) von der Beschlussvor­lage abweicht.
auxiliaryFile array of object (File) Weit­ere Dateian­hänge zum Tage­sord­nung­spunkt.
start date-time Datum und Uhrzeit des Anfang­szeit­punkts des Tage­sord­nung­spunktes. Bei zukün­fti­gen Tage­sord­nung­spunk­ten ist dies der geplante Zeit­punkt, bei einem stat­tge­fundenen kann es der tatsäch­liche Startzeit­punkt sein.
end date-time Endzeit­punkt des Tage­sord­nung­spunktes als Datum/Uhrzeit. Bei zukün­fti­gen Tage­sord­nung­spunk­ten ist dies der geplante Zeit­punkt, bei einer stat­tge­fundenen kann es der tatsäch­liche Endzeit­punkt sein.
keyword array of string
web url
Beis­piel
{
    "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 Objekttyp dient der Abbildung von Druck­sachen in der parla­ment­ar­ischen Arbeit, wie zum Beis­piel Anfra­gen, Anträ­gen und Beschlussvor­la­gen.

Druck­sachen werden in Form einer Bera­tung (oparl:Consulta­tion) im Rahmen eines Tage­sord­nung­spunkts (oparl:AgendaItem) einer Sitzung (oparl:Meet­ing) behan­delt.

Druck­sachen spielen in der schrift­lichen wie münd­lichen Kommunika­tion eine beson­dere Rolle, da in vielen Texten auf bestim­mte Druck­sachen Bezug genom­men wird. Hier­bei kommen in parla­ment­ar­ischen Inform­a­tionssyste­men in der Regel unver­än­der­liche Kennun­gen der Druck­sachen zum Einsatz.

Name Typ Beschreibung
id url
type string
body url (Body) Körper­schaft, zu der die Druck­sache gehört.
name string Titel der Druck­sache.
reference string Kennung bzw. Akten­zeichen der Druck­sache, mit der sie in der parla­ment­ar­ischen Arbeit eindeutig refer­en­ziert werden kann.
date date Datum, welches als Start­punkt für Fristen u.ä. verwen­det ist.
paperType string Art der Druck­sache, z. B. Beant­wor­tung einer Anfrage.
relatedPaper array of url (Paper) Inhalt­lich verwandte Druck­sachen.
superordinatedPaper array of url (Paper) Über­geord­nete Druck­sachen.
subordinatedPaper array of url (Paper) Unter­geord­nete Druck­sachen.
mainFile object (File) Die Hauptdatei zu dieser Druck­sache. Beis­piel: Die Druck­sache repräsen­tiert eine Beschlussvor­lage und die Hauptdatei enthält den Text der Beschlussvor­lage. Sollte keine eindeut­ige Hauptdatei vorhanden sein, wird diese Eigenschaft nicht ausgegeben.
auxiliaryFile array of object (File) Alle weit­eren Dateien zur Druck­sache ausgen­om­men der gegeben­en­falls in mainFile angegebenen.
location array of object (Loca­tion) Sofern die Druck­sache einen inhalt­lichen Orts­bezug hat, beschreibt diese Eigenschaft den Ort in Text­form und/oder in Form von Geod­aten.
originatorPerson array of url (Person) Urheber der Druck­sache, falls der Urheber eine Person ist. Es können auch mehr­ere Personen angegeben werden.
underDirectionOf array of url (Organ­iz­a­tion) Feder­führung. Amt oder Abteilung, für die Inhalte oder Beant­wor­tung der Druck­sache verant­wort­lich.
originatorOrganization array of url (Organ­iz­a­tion) Urheber der Druck­sache, falls der Urheber eine Grup­pier­ung ist. Es können auch mehr­ere Grup­pier­ungen angegeben werden.
consultation array of object (Consulta­tion) Bera­tun­gen der Druck­sache.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

3.9.1 Consulta­tion

Der Objekttyp oparl:Consultation dient dazu, die Bera­tung einer Druck­sache (oparl:Paper) in einer Sitzung abzu­bilden. Dabei ist es nicht entscheidend, ob diese Bera­tung in der Vergan­gen­heit stat­tge­fun­den hat oder diese für die Zukunft geplant ist.

Die Gesam­theit aller Objekte des Typs oparl:Consultation zu einer bestim­mten Druck­sache bildet das ab, was in der Praxis als “Bera­tungs­folge” der Druck­sache bezeich­net wird.

Name Typ Beschreibung
id url
type string
paper url (Paper) Rück­refer­enz auf das Paper, welche nur dann ausgegeben werden muss, wenn das Consulta­tion-Objekt einzeln abgerufen wird, d.h. nicht Teil einer internen Ausgabe ist.
agendaItem url (AgendaItem) Tage­sord­nung­spunkt, unter dem die Druck­sache beraten wird.
meeting url (Meet­ing) Sitzung, in der die Druck­sache beraten wird.
organization array of url (Organ­iz­a­tion) Gremium, in dem die Druck­sache beraten wird. Hier kann auch eine mit Liste von Gremien angegeben werden (die verschiedenen oparl:Body und oparl:System ange­hören können). Die Liste ist dann geord­net. Das erste Gremium der Liste ist feder­führend.
authoritative boolean Drückt aus, ob bei dieser Bera­tung ein Beschluss zu der Druck­sache gefasst wird oder wurde (true) oder nicht (false).
role string Rolle oder Funk­tion der Bera­tung. Zum Beis­piel Anhörung, Entscheidung, Kennt­nis­nahme, Vorber­a­tung usw.
keyword array of string
web url
Beis­piel
{
    "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, beis­piels­weise eine PDF-Datei, ein RTF- oder ODF-Doku­ment, und hält Metad­aten zu der Datei sowie URLs zum Zugriff auf die Datei bereit.

Objekte vom Typ oparl:File können unter anderem mit Druck­sachen (oparl:Paper) oder Sitzun­gen (oparl:Meeting) in Beziehung stehen. Dies wird durch die Eigenschaft paper bzw. meeting angezeigt.

Mehr­ere Objekte vom Typ oparl:File können mit einander in direk­ter Beziehung stehen, z.B. wenn sie den selben Inhalt in unter­schied­lichen tech­nis­chen Formaten wiedergeben. Hier­für werden die Eigenschaften masterFile bzw. derivativeFile einge­setzt. Das sgezeigte Beis­piel-Objekt repräsen­tiert eine PDF-Datei (zu erkennen an der Eigenschaft mimeType) und zeigt außer­dem über die Eigenschaft masterFile an, von welcher anderen Datei es abgeleitet wurde. Umgekehrt kann über die Eigenschaft derivativeFile angezeigt werden, welche Ablei­tun­gen einer Datei existieren.

Name Typ Beschreibung
id url
type string
name string Ein zur Anzeige für Endnutzer bestim­mter Name für dieses Objekt. Leerzeichen dürfen enthal­ten sein, Datei-Endun­gen wie “.pdf” soll­ten nicht enthal­ten sein.
fileName string Datein­ame, unter dem die Datei in einem Dateisys­tem gespeich­ert werden kann. Beis­piel: “eined­atei.pdf”. Da der Name den kompletten Unicode-Zeichenum­fang nutzen kann, soll­ten Clients ggfs. selbst dafür sorgen, diesen beim Speich­ern in ein Dateisys­tem den lokalen Erfordern­is­sen anzu­passen.
mimeType string MIME-Type der Datei 28.
date date Datum, welches als Start­punkt für Fristen u.ä. verwen­det ist.
size integer Größe der Datei in Bytes.
sha1Checksum string SHA1-Prüf­summe des Datei­in­halts in Hexadez­i­mal-Schreib­weise.
text string Reine Text-Wieder­gabe des Datei­in­halts, sofern dieser in Text­form wiedergegeben werden kann.
accessUrl url ZWINGEND URL zum allge­meinen Zugriff auf die Datei. Näheres unter Dateizu­griffe.
downloadUrl url URL zum Down­load der Datei. Näheres unter Dateizu­griffe.
externalServiceUrl url Externe URL, welche eine zusätz­liche Zugriff­s­mög­lich­keit bietet. Beis­piel: YouTube-Video.
masterFile url (File) Datei, von der das aktuelle Objekt abgeleitet wurde. Details dazu in der allge­meinen Beschreibung weiter oben.
derivativeFile array of url (File) Dateien, die von dem aktuel­len Objekt abgeleitet wurden. Details dazu in der allge­meinen Beschreibung weiter oben.
fileLicense url Lizenz, unter der die Datei ange­boten wird. Wenn diese Eigenschaft nicht verwen­det wird, ist der Wert von license beziehung­s­weise die Lizenz eines über­geord­neten Objektes maßgeb­lich. Siehe license
meeting array of url Rück­refer­en­zen auf Meet­ing-Objekte. Wird nur dann ausgegeben, wenn das File-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
agendaItem array of url Rück­refer­en­zen auf AgendaItem-Objekte. Wird nur dann ausgegeben, wenn das File-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
paper array of url Rück­refer­en­zen auf Paper-Objekte. Wird nur dann ausgegeben, wenn das File-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
keyword array of string
created date-time
modified date-time
web url
deleted boolean
Beis­piel
{
    "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 Objekttyp dient dazu, einen Orts­bezug formal abzu­bilden. Ortsangaben können sowohl aus Textin­form­a­tionen bestehen (beis­piels­weise dem Namen einer Straße/eines Platzes oder eine genaue Adresse) als auch aus Geod­aten. Ortsangaben sind auch nicht auf einzelne Posi­tionen beschränkt, sondern können eine Vielzahl von Posi­tionen, Flächen, Strecken etc. abdecken.

Name Typ Beschreibung
id url
type string
description string Textuelle Beschreibung eines Orts, z. B. in Form einer Adresse.
geojson object Geod­aten-Repräsent­a­tion des Orts. Der Wert dieser Eigenschaft muss der Spezi­fika­tion von GeoJSON ents­prechen, d.h. es muss ein voll­ständiges Feature-Objekt ausgegeben werden.
streetAddress string Straße und Haus­num­mer der Anschrift.
room string Raumangabe der Anschrift
postalCode string Postleitzahl der Anschrift.
subLocality string Unter­geord­nete Ortsangabe der Anschrift, z.B. Stadtbezirk, Ortsteil oder Dorf.
locality string Ortsangabe der Anschrift.
bodies array of url Rück­refer­en­zen auf Body-Objekte. Wird nur dann ausgegeben, wenn das Loca­tion-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
organization array of url Rück­refer­en­zen auf Organ­iz­a­tion-Objekte. Wird nur dann ausgegeben, wenn das Loca­tion-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
meeting array of url Rück­refer­en­zen auf Meet­ing-Objekte. Wird nur dann ausgegeben, wenn das Loca­tion-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
papers array of url Rück­refer­en­zen auf Paper-Objekte. Wird nur dann ausgegeben, wenn das Loca­tion-Objekt nicht als einge­b­ettetes Objekt aufgerufen wird.
keyword array of string
created date-time
modified date-time
web url
deleted boolean

  1. In Deutsch­land hat sich auf kommun­aler Ebene der Begriff “Ratsin­form­a­tionssys­tem” etabliert. OParl ist jedoch nicht auf Gemeinder­äte beschränkt und verwen­det daher den Begriff “parla­ment­ar­isches Inform­a­tionssys­tem”.

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

  3. Politik Bei Uns: https://politik-bei-uns.de

  4. Eine welt­weite Über­sicht zu Open-Data-Projek­ten bietet z. B. der Open-Data-Show­room http://opendata-show­room.org/de/

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

  6. Ten Prin­ciples for Open­ing Up Open Govern­ment Inform­a­tion, https://sunlight­found­a­tion.com/policy/docu­ments/ten-open-data-prin­ciples

  7. Barri­ere­freie Inform­a­tion­s­tech­nik-Veror­d­nung 2.0 http://www.gesetze-im-inter­net.de/bitv_2_0/

  8. Weit­ere gener­elle Inform­a­tionen zur Bereit­s­tel­lung offener Verwal­tungs­daten bieten bspw.

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

  10. Das Ratsin­form­a­tionssys­tem BoRis, eine Eigen­entwicklung der Stadt Bonn http://www2.bonn.de/bo_ris/ris_sql/agm_index.asp

  11. bürgerbaut­stadt, http://www.buer­gerbaut­stadt.de

  12. http://patterns.datain­cub­ator.org/book/follow-your-nose.html

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

  14. Bern­ers-Lee, Tim: Cool URIs don’t change. http://www.w3.org/Provider/Style/URI.html

  15. Study on persist­ent URIs, with iden­ti­fic­a­tion of best prac­tices and recom­mend­a­tions 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­sist­ent%20URIs.pdf

  16. RFC4627: https://tools.ietf.org/html/rfc4627

  17. RFC 7159 Section 8.1

  18. RFC 7159 Section 7

  19. Zu semantisch identischen Formaten zählen u.a.: YAML, MessagePack, etc.

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

  21. Cross Origin Resource Shar­ing – W3C Recom­mend­a­tion 16. Januar 2014: http://www.w3.org/TR/cors/

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

  23. Verzeich­n­isse für Lizenz-URLs sind unter anderem unter http://licenses.opendefin­i­tion.org/ und https://github.com/fraunhofer­fokus/ogd-metadata/blob/master/lizen­zen/deutsch­land.json zu finden. Allge­meine Inform­a­tionen zur Lizen­sier­ung von Open Data finden sich auch im Open Data Hand­book der Open Know­ledge Found­a­tion unter http://openda­ta­hand­book.org/de/how-to-open-up-data/apply-an-open-license.html.

  24. Amtliche Gemein­des­chlüs­sel können im Gemeindeverzeich­nis (GV-ISys) des Stat­istischen Bundes­amtes eingese­hen werden

  25. Gemein­same Norm­d­atei 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.