Merge pull request #397 from OParl/f_omit_internal

Option zum Auslassen von eingebetteten Listen mit einem Filter für #396

Author: konstin

schema/AgendaItem.json

@@ -4,7 +4,8 @@
     "type": "object",
     "required": [
         "id",
-        "type"
+        "type",
+        "order"
     ],
     "properties": {
         "id": {
@@ -25,6 +26,10 @@
             "description": "{{ AgendaItem.properties.number.description }}",
             "type": "string"
         },
+        "order": {
+            "description": "{{ AgendaItem.properties.order.description }}",
+            "type": "integer"
+        },
         "name": {
             "description": "{{ AgendaItem.properties.name.description }}",
             "type": "string"
@@ -97,4 +102,4 @@
             "type": "boolean"
         }
     }
-}
+}

schema/Body.json

@@ -169,6 +169,16 @@
                 "schema": "Location.json"
             }
         },
+        "legislativeTermList": {
+            "description": "{{ Body.properties.legislativeTermList.description }}",
+            "type": "string",
+            "format": "url",
+            "references": "externalList",
+            "items": {
+                "type": "object",
+                "schema": "LegislativeTerm.json"
+            }
+        },
         "membership": {
             "description": "{{ Body.properties.membership.description }}",
             "type": "string",

schema/strings.yml

@@ -16,6 +16,10 @@ de:
     wie z. B. "10.", "10.1", "C", "c)" o. ä. Die Reihenfolge wird nicht dadurch,
     sondern durch die Reihenfolge der TOPs im `agendaItem`-Attribut von `oparl:Meeting`
     festgelegt, **sollte** allerdings zu dieser identisch sein.
+  AgendaItem.properties.order.description: |
+    Neu in OParl 1.1: Die Position des Tagesordnungspunkts in der Sitzung,
+    wenn alle Tagesordnungspunkte von 0 an durchgehend numeriert werden.
+    Diese Nummer entspricht der Position in `Meeting:agendaItem`
   AgendaItem.properties.name.description: Das Thema des Tagesordnungspunktes.
   AgendaItem.properties.public.description: |
     Kennzeichnet, ob der Tagesordnungspunkt zur Behandlung in öffentlicher Sitzung
@@ -113,6 +117,7 @@ de:
   Body.properties.file.description: "**ZWINGEND** Link zur [Objektliste](#objektlisten) mit allen Dateien der Körperschaft. Neu in OParl 1.1."
   Body.properties.membership.description: "**ZWINGEND** Link zur [Objektliste](#objektlisten) mit allen Mitgliedschaften der Körperschaft. Neu in OParl 1.1."
   Body.properties.locationList.description: "**ZWINGEND** Link zur [Objektliste](#objektlisten) mit allen Ortsangaben der Körperschaft. Neu in OParl 1.1."
+  Body.properties.legislativeTermList.description: "**ZWINGEND** Link zur [Objektliste](#objektlisten) mit allen Legislaturperioden der Körperschaft. Neu in OParl 1.1. Die externe Objektliste enthält die gleichen Objekte wie `legislativeTerm`"
   Body.properties.shortName.description: Kurzer Name der Körperschaft.
   Body.properties.name.description: Der offizielle lange Name der Körperschaft.
   Body.properties.website.description: Allgemeine Website der Körperschaft.

src/2-05-objektlisten-und-paginierung.md

@@ -223,6 +223,19 @@ beziehen sich auf die entsprechenden Attribute der jeweiligen Objekte, wobei
 reservierte Zeichen URL-Kodiert werden müssen. Ein Server muss diese Parameter
 bei allen externen Objektlisten unterstützen.
 
+Neu in OParl 1.1: Wenn ein Client den Parameter `omit_internal` mit dem Wert
+`true` angibt, dann **soll** der Server auf die Ausgabe von internen Listen
+verzichten. Konkret bedeutet das, dass die folgenden Attribute nicht ausgegeben
+werden müssen:
+
+ - `auxiliaryFile` in `AgendaItem`
+ - `auxiliaryFile` in `Meeting`
+ - `auxiliaryFile` in `Paper`
+ - `location` in `Paper`
+ - `membership` in `Person`
+ - `agendaItem` in `Meeting`
+ - `legislativeTerm` in `Body`
+
 Die Filter werden vom Client benutzt, indem die gewünschten URL-Parameter an
 die URL der ersten Listenseite angehängt werden. Bei allen weiteren Seiten,
 genauer gesagt bei den Werten von `links`, **muss** der Server sicherzustellen,
@@ -271,9 +284,9 @@ Drucksachen herunterladen und in einer Datenbank speichern.
 
 Um den Datenbestand am nächsten Tag zu aktualisieren, ruft der Client die selbe
 URL auf, diesmal jedoch mit dem Parameter `modified_since` mit dem Wert
-`2014-01-01T02:00:00+01:00`.
+`2014-01-01T02:00:00+01:00` und mit `omit_internal`.
 
-    https://oparl.example.org/papers/?modified_since=2014-01-01T02%3A00%3A00%2B01%3A00
+    https://oparl.example.org/papers/?modified_since=2014-01-01T02%3A00%3A00%2B01%3A00&omit_internal=true
 
 Diese Liste ist in der Regel deutlich kürzer als die Liste aller Objekte,
 sodass die Aktualisierung bedeutend schneller ist als der erste Abruf. Der

src/4-01-oparl-1-1.md

@@ -6,7 +6,6 @@ Das bedeutet, dass ein für OParl 1.0 entwickelter Client auch die Ausgabe von
 OParl 1.1 versteht. Dadurch ist wird der Migrationsaufwand von OParl 1.0 zu
 OParl 1.1 gering gehalten.
 
-
 OParl 1.0 wurde in der Annahme geschrieben, dass für sechs Objekttypen
 (LegislativeTerm, Membership, AgendaItem, Consultation, File, Location)
  keine verlässlichen Werte für `created` und `modified` existieren.
@@ -17,17 +16,19 @@ OParl 1.0 wurde in der Annahme geschrieben, dass für sechs Objekttypen
  bei der Synchronisation.
 
 Konkret sind `created` und `modified` in OParl 1.1 für alle Objekte zwingend
- und es gibt fünf neue externe Objektlisten in Body: AgendaItem, Consultation,
-  File, Location und Membership. LegislativeTerm wird weiterhin als
-  eingebettete Liste direkt in Body ausgegeben. Das Attribut für die
-  Location-Liste in Body heißt dabei `locationList`, um eine Kollision
-  mit dem bereits existierenden `location` zu vermeiden.
+und es gibt fünf neue externe Objektlisten in Body: AgendaItem, Consultation,
+File, LegislativeTerm, Location und Membership. Das Attribut für die
+Location-Liste in Body heißt dabei `locationList`, um eine Kollision
+mit dem bereits existierenden `location` zu vermeiden. Das gleiche gilt auch für
+`legislativeTermList`.
 
 Es entsteht dabei Redundanz zwischen den bereits existierenden Objektlisten mit
 eingebetteten Objekten (Body, Paper, Meeting, Person, Organization) und den
 neuen externen Listen, die die bisher eingebetteten Objekte extern ausgeben.
 Diese Redundanz lässt sich auf Grund der Semver-Regeln in Version 1.1 nicht
-vermeiden und kann erst in einer Version 2 beseitigt werden.
+vermeiden und kann erst in einer Version 2 beseitigt werden. Um diese Redundanz
+zumindest bei der Aktualisierung eines lokalen Datenbestands vermeiden zu können  
+wurde die URL-Paramter `omit_internal` eingeführt.
 
 ### Weitere Änderungen
  * Namespace-URLs werden durchgängig im Camel Case geschrieben