CRUD

specdraftimplcandidate

Erzeugen, Ersetzen, Aktualisieren und Löschen von Features.

Umfang

Neue oder aktualisierte Features können in GeoJSON, JSON-FG oder GML übermittelt werden.

In POST- und PUT-Anfragen muss der Header "Content-Type" für GeoJSON und JSON-FG auf "application/geo+json" gesetzt sein, für GML auf "application/gml+xml". PATCH wird nur für "application/merge-patch+json" und "application/geo+json" unterstützt; PATCH mit "application/gml+xml" wird mit HTTP 415 ("Unsupported Media Type") abgelehnt.

In PATCH-Anfragen muss der Header "Content-Type" auf "application/merge-patch+json" gesetzt sein. Der Payload sollte nur die geänderten Werte (in den Eigenschaften "geometry"/"place" und "properties") enthalten. Details dazu finden sich in RFC 7396 (JSON Merge Patch).

Der GML-Payload muss aus einem einzelnen Feature-Element auf der obersten Ebene des Dokuments bestehen. Bodies mit mehreren Features (z.B. "wfs:FeatureCollection") werden mit HTTP 400 abgelehnt. Der Decoder unterstützt die Optionen des GML-Bausteins (Alias-Auflösung, Value-Wrapping, Namespace-Qualifizierung, Codelist-URI-Templates, srsName-Mappings, UoM-Mappings) symmetrisch zum Encoder; die vollständige Liste mit den Hinweisen pro Option findet sich im GML-Baustein. Die strukturelle Validierung beschränkt sich auf den Token-Stream - schemabasierte Prüfungen gegen das Feature-Schema der Collection erfolgen wie bei den JSON-Formaten nachgelagert.

Bei GML wird das Koordinatenreferenzsystem jeder Geometrie in dieser Reihenfolge aufgelöst: das eigene "srsName"-Attribut der Geometrie, der Header "OGC-Content-Crs" der Anfrage, das Storage-CRS der Collection. Ein einzelnes Feature darf keine unterschiedlichen Koordinatenreferenzsysteme über seine Geometrien hinweg verwenden; eine solche Anfrage wird mit HTTP 400 abgelehnt. ADV-URN-Formen für "srsName" (z.B. "urn:adv:crs:ETRS89_UTM32") werden über die Option "srsNameMappings" des GML-Bausteins aufgelöst.

Die Eigenschaften müssen in der Repräsentation für Receivables vorliegen, also entsprechend dem Schema der Collection ohne die als readOnly gekennzeichneten Eigenschaften. Bei Objektverweisen ist die Repräsentation für Receivables ein JSON-Objekt mit drei Eigenschaften (id, dem Fremdschlüssel, title, einem beschreibenden Text, und type, dem Namen des Typs im Objektschema). Um ein bestehendes Feature zu aktualisieren, kann das aktuelle zu bearbeitende Feature im Profil all-as-receivable angefordert werden.

Wenn ein neues oder aktualisiertes Feature eine Geometrie enthält, muss die URI des Koordinatenreferenzsystems im Header "Content-Crs" der Anfrage angegeben werden. Um Koordinatentransformationen zu vermeiden, sollte die Geometrie im Storage-CRS vorliegen. Es dürfen nur die Koordinatenreferenzsysteme der Collection verwendet werden (siehe die Eigenschaft crs der Collection), sowohl im Header "Content-Crs" als auch im Payload (eine "coordRefSys"-Eigenschaft in JSON-FG, ein "srsName"-Attribut in GML); jedes andere Koordinatenreferenzsystem wird mit HTTP 400 abgelehnt.

Features dürfen nur eine einzige Geometrieeigenschaft mit Scope RECEIVABLES haben. Die Geometrie muss in der Eigenschaft "geometry" oder "place" abhängig vom Format (mit oder ohne die JSON-FG-Erweiterungen), dem Koordinatenreferenzsystem und dem Geometrietyp dargestellt werden (Details dazu, wann "place" zu verwenden ist, finden sich in JSON-FG).

Ein neues Feature kann auf zwei Arten erstellt werden, abhängig von der Angabe der featureId. Wenn die featureId von ldproxy während der Erstellung generiert und zugewiesen wird, wird POST auf {landingPage}/collections/{collectionId}/items verwendet und die URI des generierten Features ist im Header "Location" der Antwort enthalten. Wenn die Feature-ID vom Client vergeben wird, ist PUT auf {landingPage}/collections/{collectionId}/items/{featureId} zu verwenden. Clients können das Verhalten aus dem OpenAPI-Dokument ermitteln oder durch Inspektion des Feldes supportsNonAutogeneratedResourceIds in der Collection. Eine "id"-Eigenschaft in einem in einer POST- oder PUT-Anfrage übermittelten Feature wird ignoriert; eine PATCH-Anfrage, die den Identifikator des Features ändern würde, wird mit HTTP 400 abgelehnt, da das Feature über die URI der Ressource identifiziert wird.

Um ein in einer POST- oder PUT-Anfrage übermitteltes neues oder aktualisiertes Feature gegen das Schema der Collection (GeoJSON/JSON-FG) oder die konfigurierten XML Schemas (GML) zu validieren, kann der Anfrage ein Header Prefer mit dem Wert "handling=strict" hinzugefügt werden. Wenn die Validierung fehlschlägt, wird ein Fehler zurückgegeben und die Antwort meldet die angewendete Präferenz in einem "Preference-Applied"-Header. Für die Validierung wird ein Schema benötigt: der Baustein SCHEMA_VALIDATION bei GeoJSON und JSON-FG, die Option "schemaLocations" des GML-Bausteins bei GML. Ohne ein Schema wird der Payload nicht validiert und die Präferenz ignoriert.

Die Option rejectEmptyValues ergänzt "handling=strict" um eine zweite Prüfung: Die Anfrage wird zurückgewiesen, wenn ein Wert im Payload eine leere Zeichenkette ist oder nur aus Leerraum besteht. Die Prüfung erfolgt beim Dekodieren des Payloads, benötigt daher kein Schema und wird auch angewendet, wenn der Payload nicht gegen ein Schema validiert werden kann.

Eine PUT-, PATCH- oder DELETE-Anfrage kann nicht von einem Entity-Tag abhängig gemacht werden: In einer Anfrage, die ein Feature ändert, ist kein Entity-Tag des Features bekannt, daher kann ein "If-Match"-Header nicht erfüllt werden und die Anfrage wird mit HTTP 412 ("Precondition Failed") zurückgewiesen. Verwenden Sie stattdessen einen "If-Unmodified-Since"-Header (siehe die Option optimisticLockingLastModified).

Wenn das Feature in einer POST- oder PUT-Anfrage GeoJSON ohne die JSON-FG-Erweiterungen ist, fügen Sie der Anfrage einen Header Link mit dem Wert "http://www.opengis.net/def/profile/OGC/0/rfc7946; rel=profile" hinzu. Für ein Feature mit den JSON-FG-Erweiterungen verwenden Sie den Wert "http://www.opengis.net/def/profile/OGC/0/jsonfg; rel=profile".

Limitierungen

Es werden nur Objektarten von einem SQL-Feature-Provider mit dialect PGIS und datasetChanges.mode CRUD unterstützt.

Die Features dürfen nur eine einzige Geometrieeigenschaft mit dem Geltungsbereich RECEIVABLES haben.

Konformitätsklassen

Der Baustein basiert auf den Vorgaben der Konformitätsklassen "Create/Replace/Delete", "Update", "Optimistic Locking using Timestamps", "Handling Preference" und "Features" aus dem Entwurf von OGC API - Features - Part 4: Create, Replace, Update and Delete. Die Implementierung wird sich im Zuge der weiteren Standardisierung der Spezifikation noch ändern.

Operationen

Ressource	Pfad	Methoden	Formate	Beschreibung
Features, Feature	collections/{collectionId}/items, collections/{collectionId}/items/{featureId}	DELETE, PATCH, POST, PUT		Erzeugen, Ersetzen, Aktualisieren und Löschen von Features.

Pfad-Parameter

Name	Ressourcen	Beschreibung
collectionId	Features, Feature	Der Identifikator der Feature Collection.

Konfiguration

Optionen

Name	Default	Beschreibung	Typ	Seit
buildingBlock		Immer CRUD.	string	v2.0
enabled	false	Soll der Baustein aktiviert werden?	boolean	v2.0
optimisticLockingLastModified	false	Option zur Aktivierung der Unterstützung für die bedingte Verarbeitung von PUT-, PATCH- und DELETE-Anfragen, basierend auf der Zeit, zu der das Feature zuletzt aktualisiert wurde. Solche Anfragen müssen einen If-Unmodified-Since-Header enthalten, andernfalls werden sie mit HTTP 428 ("Precondition Required") zurückgewiesen. Ein Feature wird nur dann geändert, wenn das Feature seit dem Zeitstempel im Header nicht geändert wurde (oder wenn kein letzter Änderungszeitpunkt für das Feature bekannt ist), andernfalls ist die Antwort HTTP 412 ("Precondition Failed"). Die Antwort auf eine erfolgreiche PUT- oder PATCH-Anfrage enthält den neuen Änderungszeitpunkt in einem Last-Modified-Header, damit er in der nächsten bedingten Anfrage verwendet werden kann. Der Zeitpunkt der letzten Änderung eines Features wird anhand einer Objekteigenschaft mit Datentyp DATETIME ermittelt, für die isLastModified im Schema des Feature Providers auf true gesetzt ist; die Eigenschaft kann vom Geltungsbereich RECEIVABLE ausgenommen werden.	boolean	v3.5
rejectEmptyValues	false	Option zur Zurückweisung leerer Werte im Request-Body einer POST- oder PUT-Anfrage. Ein Wert ist leer, wenn es eine Zeichenkette ohne Zeichen oder nur mit Leerraum ist. Die Prüfung wird nur auf Anfragen mit einem Prefer-Header mit dem Wert "handling=strict" angewendet; eine solche Anfrage wird mit HTTP 400 ("Bad Request") zurückgewiesen und die Antwort benennt den ersten leeren Wert. Werte anderer Datentypen können nicht leer sein, d.h. wenn zusätzlich die Schemavalidierung aktiv ist, kann ein leerer Wert nur in einer Zeichenkette auftreten. Die Prüfung erfolgt beim Dekodieren des Request-Body, benötigt daher kein Schema und wird auch angewendet, wenn kein Schema für die Validierung des Request-Body verfügbar ist. Eine Eigenschaft, die im Request-Body fehlt oder als null angegeben ist, bleibt ohne Wert und ist nicht betroffen.	boolean	v4.9

Dieses Modul benötigt bzw. unterstützt keine zusätzlichen Konfigurationsdateien.

Beispiele

- buildingBlock: CRUD
 enabled: true
 rejectEmptyValues: true