OParl Workshop 01.04.15 - Besprochene Änderungen

OParl Workshop 01.04.15 - Besprochene Änderungen 1 OParl besser crawlbar machen In der Spezifikation fehlen aktuell die üblichen Abfragemöglichkeiten, es gibt zum Beispiel keine Such- und Sortiermöglichkeit. Wir könnten versuchen diese Funktionen zu integrieren, das würde allerdings einiges an Zeit kosten und den Implementierungsaufwand erhöhen. Diese Funktionen sollen erst in einer zukünftigen Version von OParl integriert werden. Stattdessen wollen wir uns in Version 1.0 darauf konzentrieren, dass es unkompliziert möglich ist, die benötigten Daten aus einem RIS in eine eigene Datenbank zu laden. Die gewünschten Abfragen können dann in der eigenen Datenbank gemacht werden. Mit der OParl API soll es auch wie gehabt möglich sein den Datenbestand zu updaten. Aktuell gibt es aber noch keine komfortable Möglichkeit alle Objekte aus einem OParl-System zu laden (crawlen), daher sollen folgende drei Änderungen vorgenommen werden: 1.1 Vollständige Listenausgabe für alle Objekttypen Vom Body Objekt aus soll es Links zu externen Listen für jeden Objekttyp geben: "id": "http://oparl.example.org/bodies/0", "type": "http://oparl.org/schema/1.0/body", "organization": "http://oparl.example.org/bodies/0/organizations/", "person": "http://oparl.example.org/bodies/0/persons/", "meeting": "http://oparl.example.org/bodies/0/meetings/", "agendaitem": "http://oparl.example.org/bodies/0/papers/", "paper": "http://oparl.example.org/bodies/0/papers/", "file": "http://oparl.example.org/bodies/0/files/", "consultation": "http://oparl.example.org/bodies/0/consultation/", "location": "http://oparl.example.org/bodies/0/location/", "membership": "http://oparl.example.org/bodies/0/membership/", "legislativeterm": "http://oparl.example.org/bodies/0/legislativeterm/", In den Listen sollen die Objekte immer in vollständiger Form ausgegeben werden (also nicht nur die IDs), der Parameter listformat=complete entfällt somit. Es ist empfohlen Paginierung zu verwenden. Beispiel für die vollständige Paper-Liste: "items": [ "id": "http://oparl.example.org/bodies/0/papers/1", "type": "http://oparl.org/schema/1.0/paper", "name": "Antwort auf Anfrage 1/2014", "mainfile": "http://oparl.example.org/files/7", "publisheddate": "2014-01-04T16:42:02+02:00", "id": "http://oparl.example.org/bodies/0/papers/2", "type": "http://oparl.org/schema/1.0/paper", "name": "Radwege ausbauen", "mainfile": "http://oparl.example.org/files/12", "publisheddate": "2014-01-05T13:05:00+02:00", 1

} "id": "http://oparl.example.org/bodies/0/papers/3", "type": "http://oparl.org/schema/1.0/paper", "name": "Neue Parkbänke für den Stadtpark", "mainfile": "http://oparl.example.org/files/14", "publisheddate": "2014-01-05T14:31:12+02:00", ], "nextpage": "http://oparl.example.org/bodies/0/papers/?skip_id=99" 1.2 Standardgemäß interne Listenausgabe verwenden Aktuell darf der Server jede Liste in eine externe Liste auslagern. Beispiel: die participants aus einem Meeting-Objekt als externe Liste: "items": [ "id": "http://oparl.example.org/meetings/281", "type": "http://oparl.org/schema/1.0/meeting", "name": "1. Sitzung des Finanzausschusses", "participant": "http://oparl.example.org/meetings/281/participants/", Falls externe Listen verwendet werden, muss ein Client pro Objekt zusätzliche HTTP- Anfragen machen um die externen Listen abzufragen, was bei vielen Objekten im System zu sehr vielen HTTP-Anfragen führen würden. Stattdessen soll immer die interne Listenausgabe verwendet werden: "items": [ "id": "http://oparl.example.org/meetings/281", "type": "http://oparl.org/schema/1.0/meeting", "name": "1. Sitzung des Finanzausschusses", "participant": [ "http://oparl.example.org/person/10", "http://oparl.example.org/person/22", "http://oparl.example.org/person/12", "http://oparl.example.org/person/99", "http://oparl.example.org/person/73", "http://oparl.example.org/person/83", "http://oparl.example.org/person/78", "http://oparl.example.org/person/94", "http://oparl.example.org/person/98", "http://oparl.example.org/person/34", "http://oparl.example.org/person/52", "http://oparl.example.org/person/57" ], 2

Ein Client kann jetzt die Liste der Meetings crawlen ohne zusätzliche HTTP-Anfragen pro Objekt machen zu müssen. Durch URLs in der participant-liste kann gespeichert werden, welche Personen-IDs mit dieser Sitzung verknüpft sind (Fremdschlüssel). Ein Client sollte aus Performancegründen diese URLs nicht einzeln abfragen. Stattdessen sollte der Client gleich die vollständige Liste mit allen Personen-Objekten abfragen, um viele Objekte mit einem Request zu erhalten. Für manche Clients, zum Beispiel Tablet-Apps, könnte es jedoch ungünstig sein, zuerst die vollständige Liste mit allen Personen-Objekten laden zu müssen, bevor sie die Teilnehmer für eine Sitzung anzeigen können. Hier eignen sich externe Listen besser. Eine Lösungsmöglichkeit wäre, wenn sich die externe Listenausgabe mit einem Parameter, zum Beispiel?listformat=external, aktivieren ließe. Anmerkung: Nach dem Workshop ist dabei allerdings noch ein Problem aufgefallen. Möchte ein Client die Mitglieder eines Organization-Objekts abfragen, ebenfalls ohne vorher die vollständige Liste mit allen Personen-Objekten laden zu müssen, helfen externe Listen allein noch nicht. Das Problem ist, dass die Organization-Objekte nicht direkt, sondern über Membership-Objekte mit den Personen-Objekten verknüpft sind. Man könnte dann zwar eine externe Liste mit Membership-Objekten abfragen, müsste von dort aber die Personen-Objekte einzeln abfragen. Über dieses Problem soll weiter nachgedacht werden. 1.3 Feeds durch Filter ersetzen Feeds sind schwer zu implementieren, vor allem mit stabiler Paginierung. Feeds sollen wie folgt ersetzt werden: Jedes Objekt soll die Eigenschaften created und modifed haben. Es soll möglich sein, mit einem Filter in den Listen nur Objekte anzeigen zu lassen, die nach einem wählbaren Zeitpunkt erstellt oder geändert wurden. Die Abfrage dazu könnte so aussehen: http://oparl.example.org/bodies/0/papers/?modified_after=2015-04-20:15:27+02:00 Das ermöglicht es den Datenbestand zu updaten. Außerdem wird es dadurch ermöglicht, Objekte aus einem bestimmten Zeitraum abzufragen, falls man ältere Objekte nicht benötigt. 2 Serveranforderungen lockern HTTP-Kompression (gzip) und Caching für Dateianhänge soll nicht mehr zwingend, sondern nur empfohlen sein, da beides nicht unbedingt notwendig, aber schwer zu realisieren ist. Gzip wird in der Regel vom Webserver oder einem Reverse Proxy übernommen. Wir wollen aber vermeiden, dass für OParl die Serverkonfigurationen der Kommunen angepasst werden müssen. Dateianhänge werden wahrscheinlich nicht vom Webserver, sondern von der RIS-Software ausgeliefert, damit die Zugriffsberechtigung geprüft werden kann. Caching muss vermutlich erst in die RIS-Software implementiert werden, was eine unnötig hohe Anforderung wäre. Aktuell ist die Unterstützung für HTTP-HEAD Anfragen zwingend, obwohl es nicht für die verbreiteten Cachingverfahren (If-Modified-Since oder ETag) benötigt wird. Daher soll diese Anforderung entfernt werden. 3 UTF-8 (ohne Byte Order Marker) als Encoding festlegen Aktuell ist für OParl noch kein Encoding festgelegt und es ist gibt für Clients keine zuverlässige Methode das verwendete Encoding automatisch zu erkennen. UTF-8 (ohne Byte Order 3

Marker) ist mit großem Abstand das verbreitetste Encoding im Internet und soll daher zwingend das Encoding für die OParl Ausgabe sein. 4 Texte überarbeiten die Spezifikation ist aktuell sehr lang und unübersichtlich. Die Texte sollen überarbeitet werden, sodass zuerst die Geschichte und Ziele von OParl behandelt werden und dann möglichst kurz und präzise die technischen Anforderungen für OParl-Server und Clients beschrieben werden. Erklärungen zu Webtechniken und Hinweise zur Implementierung sollen in den Anhang verschoben werden. Im Kapitel RESTful sollte erwähnt werden, dass nicht alle Eigenschaften von REST in OParl umgesetzt wurden. Im Kapitel Herstellerspezifische Erweiterungen sollte der Hinweis auf JSON-LD entfernt werden, da bei JSON-LD die Präfixe eine andere Bedeutung haben. 5 Schema übersichtlicher machen Die Schemas der OParl-Objekte sollen übersichtlicher werden und in Tabellenform angegeben werden. Es soll ein ER-Diagramm mit dem kompletten Datenmodell erstellt werden. Eigenschaften die bei jedem Objekttyp vorkommen (id, type, created, modified, keyword) sollen einmal am Anfang definiert werden und nicht für jeden Objekttyp erneut definiert werden. Die Beispiele sollen vervollständigt und überarbeitet werden. 6 Content Negotiation entfernen, neue Eigenschaft mit der URL zur Webansicht Aktuell wird Content Negotiation empfohlen, man soll beim Aufruf einer OParl-URL im Browser auf die RIS-Webansicht für das aufgerufene Objekt weitergeleitet werden. Das würde aber das Debugging über den Browser unnötig schwer machen und OParl-Clients müssen mit einem zusätzlichem Header kommunizieren, dass sie ein OParl-Client und kein Browser sind. Stattdessen soll es eine neue Eigenschaft geben, die die URL zur RIS-Webansicht des Objektes enthält. Diese Eigenschaft soll jedes OParl-Objekt haben können, soll aber nicht zwingend sein. 7 Spezielle Datentypen (xsd:string, xsd:datetime... ) ersetzen Manche Eigenschaften haben spezielle Datentypen, die in anderen Spezifikationen definiert wurden. Zum Beispiel die Eigenschaft email von Person hat nicht den Datentyp string sondern den Datentyp foaf:mbox. Das macht die Spezifikation schwerer verständlich. Daher sollen die speziellen Datentypen wieder durch die üblichen JSON-Datentypen ersetzt werden. Für Zeitangaben soll der weit verbreitete ISO 8601 Standard verwendet werden, auf dem auch xsd:datetime basiert. Falls bei einer Zeitangabe die Zeitzone nicht explizit angegeben wurde, soll die angegebene Zeit in der deutschen Zeitzone liegen. Für eine zukünftigen OParl Version soll nochmal geprüft werden, welche bestehenden Standards in OParl integriert werden sollten. 4

8 SKOS-Objekte entfernen Aktuell scheint es in den RIS-Systemen noch keine ratsübergreifende Klassifizierungen für Drucksachen, Ämter und Gremien zu geben. Daher können aktuell noch keine SKOS-Objekte genutzt werden und sollen aus OParl 1.0 entfernt werden. Wir wollen mit OParl 1.0 erst mal Erfahrungen sammeln und dann überlegen wie sich die Daten am Besten ratsübergreifend klassifizieren lassen. 9 EMPFHOLEN und OPTIONAL Angaben im Datenmodell überarbeiten, Kardinalitäten entfernen Es soll grundsätzlich empfohlen sein, alle vorhandenen öffentlichen Daten aus der Datenbank auszugeben, sofern keine Datenschutzbestimmungen dagegen sprechen. Damit entfällt die ständige Angabe von EMPFOHLEN bei den Eigenschaften. Aktuell sind manche wichtige Eigenschaften mit OPTIONAL deklariert, weil sie nicht für jedes Objekt angegeben werden können. Beispiel: enddate bei Organization, die Eigenschaft kann natürlich nur angegeben werden, wenn die Gruppierung nicht mehr existiert, trotzdem ist die Eigenschaft wichtig, daher ist die Deklaration mit OPTIONAL irreführend. OPTIONAL sollen nur zusätzliche Eigenschaften sein, die man ohne großen Informationsverlust weglassen kann, zum Beispiel wenn der Implementierungsaufwand zu hoch ist. Ein Beispiel dafür ist sha1checksum bei File. Die Angabe der Kardinalitäten hat keinen Mehrwert. Falls mindestens ein Wert vorhanden sein muss, ergibt sich das aus der Deklaration ZWINGEND. Falls auch mehr als ein Wert vorhanden sein kann, ergibt sich das aus dem Datentyp Array. Daher soll die Angabe der Kardinalitäten entfernt werden. 10 Nur ein Datentyp pro Eigenschaft Manche Eigenschaften haben mehr als einen Datentyp. Zum Beispiel resolution von AgendaItem kann einen Text aber auch eine URL zu einem File-Objekt enthalten. Solche Eigenschaften sollten in mehrere Eigenschaften unterteilt werden, damit es nur noch einen Datentyp pro Eigenschaft gibt. In diesem Fall sollte also resolution durch die Eigenschaften resolutiontext und resolutionfile ersetzt werden. 11 Neues Kapitel zum Thema Datenschutz In diesem Kapitel sollen Empfehlungen an Server-Betreiber und API-Nutzer gegeben werden. Es soll überlegt werden, welche Empfehlungen sinnvoll sind. Folgende Empfehlungen könnten sinnvoll sein: Als Server-Betreiber sollte man keine Kontaktinformationen der Ratsmitglieder und keine Anwesenheitslisten über die OParl-Schnittstelle ausgeben, es sei denn es liegt eine explizite Erlaubnis vor. Die Erlaubnis könnte über eine Einstellungsmöglichkeit im RIS-System gegeben werden. Als API-Nutzer sollte man Emailadressen aus OParl-Daten nur so in Webanwendungen ausgeben, dass sie nicht von Spambots erkannt werden können. 12 Änderung am Datenmodell 12.1 System Da es in ferner Zukunft eine inkompatible OParl Version 2.0 geben könnte, sollte es die Möglichkeit geben, dass ein Server beide Versionen parallel unter verschiedenen URLs 5

anbietet. Unklar ist jedoch wie die URLs an den Client kommuniziert werden können. Eine Möglichkeit ist, dass in diesem Fall mehr als ein System Objekt ausgegeben werden kann. Ein System Objekt für OParl Version 1 und ein System Objekt für OParl Version 2, die dann auf jeweils unterschiedliche Body URLs verweisen (zum Beispiel http://oparl.example.org/v1/bodies/1 und http://oparl.example.org/v2/bodies/1). 12.2 Body Neue Eigenschaft: ags (Amtlicher Gemeindeschlüssel), zusätzlich zum Regionalschlüssel. Der Regionalschlüssel wird erst in Zukunft den Amtlichen Gemeindeschlüssel ablösen. contactmail und contactname sollen zwingend sein. Neue Eigenschaften um die Anschrift der Körperschaft zu speichern. Die Angabe soll zwingend sein. Neue Eigenschaft: location, um Geokoordinaten zusätzlich zur Anschrift der Körperschaft speichern zu können. Neue Eigenschaft um die Reihenfolge der Organizations nach Priorität festzulegen. 12.3 Organization post soll die Reihenfolge der Rollen nach Priorität festlegen (Beispiel: [ Vorsitzender Vorsitzende, 1. Stellvertreter 1. Stellvertreterin,... ]) Neue Eigenschaften um die Anschrift des Gremiums zu speichern. Neue Eigenschaft: location, um Geokoordinaten zusätzlich zur Anschrift des Gremiums speichern zu können. Neue Eigenschaft: external_body, falls dieses Organization-Objekt zu einer fremden Körperschaft gehört, kann hier die URL der Körperschaft angegeben werden. 12.4 Personen Neue Eigenschaft: Adressierungstitel (besondere Form der Anrede, zum Beispiel Bürgermeister oder Bischof). Neue Eigenschaft den Ortsteil (bzw. Stadtbezirk, Dorf... ) in dem die Person wohnt. Für diese Eigenschaft muss noch ein passender Name gefunden werden. Bei gender den Vorschlag none entfernen. Da man die Eigenschaft auch weglassen darf, ist nicht klar was gemeint ist. Bei phone den tel: Präfix entfernen. Dieses Präfix erweckt den Eindruck, als seien die angegebenen Telefonnummern maschinenlesbar, das sind sie in der Praxis aber oft nicht. 12.5 Meeting Neue Eigenschaft: meetingroom, gibt den genauen Treffpunkt der Sitzung an, zum Beispiel eine Raumnummer. scribe soll ein Array werden, denn es können auch mehrere Personen Schriftführer sein. participant soll nur die tatsächlich anwesenden Personen enthalten. Aktuell sollen in participant vor dem Sitzungstermin die eingeladenen Personen und nach dem Sitzungstermin nur noch die tatsächlich anwesenden Personen enthalten sein. Die Anwesenheitsliste kann aber auch einige Tage nach dem Termin oder gar nicht veröffentlicht werden, daher weiß man nicht zuverlässig, was gerade in participant gespeichert ist. Eingeladen sind sowieso immer alle Mitglieder des Gremiums und eingeladene externe Personen werden nach unserer Einschätzung nicht erfasst. Daher soll participant nur noch die tatsächlich anwesenden Personen enthalten und eine Liste der eingeladenen Personen entfällt. 6

12.6 AgendaItem Neue Eigenschaften: starttime und endtime. Sie sollen die Start- und Endzeit der Besprechung des Tagesordnungspunktes angeben. 12.7 Paper Neue Eigenschaften: übergeordnete Paper (Hauptdrucksachen), untergeordnete Paper (Unterdrucksachen). Die Eigenschaft relatedpaper soll bleiben für den Fall, dass es falls es verwandte Drucksachen gibt, die weder übergeordnet noch untergeordnet sind. 12.8 File Es soll die Möglichkeit geben, Links auf fremde Webseiten zu speichern (z.b. ein Link zu einem Video bei Youtube). 12.9 Location Es soll geprüft werden ob sich GeoJSON besser als WKT eignet. Die Eigenschaft zoomlevel soll aufgenommen werden. Sie gibt an wie weit in die Karte gezoomt wurde, als der Marker auf die Karte gepinnt wurde. Daran kann man besser erkennen, ob der Marker auf eine Straße (große Zoomstufe) oder auf den Ortsteil (kleinere Zoomstufe) zeigen soll. Am besten ist natürlich, wenn die betroffene Region mit einem Rechteck oder Polygon markiert wird, wir vermuten aber, dass es in der Praxis eher selten gemacht wird. Die Maßstäbe für die Zoomlevel soll Web Mercator sein, der von allen gängigen Web-Karten (Google Maps, Open Street Map, Bing Maps... ) verwendet wird. Es soll geprüft werden, ob es sinnvoll ist, Adressdaten (Straße und Hausnummer, Ort) als Eigenschaft mit aufzunehmen. Wenn sich zwei Objekte auf den selben Geopunkt beziehen, soll nach Möglichkeit das selbe Location-Objekt verwendet werden. 12.10 Membership Die Eigenschaft post soll entfernt werden, da es bereits die Eigenschaft role gibt. 12.11 LegislativeTerm start soll eine zwingende Eigenschaft werden. 7