CRUD

specdraftimplcandidate

Create, replace, update and delete features.

Scope

New or updated features can be submitted in GeoJSON, JSON-FG or GML.

In POST and PUT requests, the "Content-Type" header must be set to "application/geo+json" for GeoJSON and JSON-FG, or to "application/gml+xml" for GML. PATCH is only supported for "application/merge-patch+json" and "application/geo+json"; PATCH with "application/gml+xml" is rejected with HTTP 415 ("Unsupported Media Type").

In PATCH requests, the "Content-Type" header must be set to "application/merge-patch+json". The payload should include only the changed values (in the "geometry"/"place" and "properties" members). See RFC 7396 (JSON Merge Patch) for details.

The GML payload must be a single bare feature element at the document root. Multi-feature bodies (e.g. "wfs:FeatureCollection") are rejected with HTTP 400. The decoder honours the options of the GML building block (alias resolution, value-wrapping, namespace qualification, codelist URI templates, srsName mappings, uom mappings) symmetrically with the encoder; see the GML building block for the full list and the per-option direction notes. Structural validation is limited to the token stream - schema-aware checks against the collection's feature schema happen downstream as for the JSON formats.

For GML, the coordinate reference system of each geometry is resolved in this order: the geometry's own "srsName" attribute, the "OGC-Content-Crs" request header, the collection's storage CRS. A single feature must not mix coordinate reference systems across its geometries; such a request is rejected with HTTP 400. ADV URN forms on "srsName" (e.g. "urn:adv:crs:ETRS89_UTM32") are resolved via the GML building block's "srsNameMappings" option.

The properties must be in the Receivables representation, that is, according to the schema of the collection excluding properties marked as readOnly. For feature references, the receivables representation is a JSON object with three properties (id, the foreign key, title, a descriptive text, and type, the name of the type in the feature schema). To update an existing feature, the current feature to be edited can be requested in the profile all-as-receivable.

If a new or updated feature includes a geometry, the URI of the coordinate reference system must be represented in the "Content-Crs" header of the request. To avoid coordinate transformations, the geometry should be in the storage CRS. Only the coordinate reference systems of the collection (see the crs member of the collection) may be used, in the "Content-Crs" header as well as in the request body (a JSON-FG "coordRefSys" member, a GML "srsName" attribute); any other coordinate reference system is rejected with HTTP 400.

Features may only have a single geometry property with scope RECEIVABLES. The geometry has to be represented in the "geometry" or "place" member depending on the format (with or without the JSON-FG extensions), the coordinate reference system and the geometry type (see JSON-FG for details when "place" has to be used).

A new feature can be created in two ways, depending on the specification of the featureId. If the featureId is generated and assigned by ldproxy during the creation, POST on {landingPage}/collections/{collectionId}/items is used and the URI of the generated feature is in the "Location" header of the response. If the feature ID is assigned by the client, PUT on {landingPage}/collections/{collectionId}/items/{featureId} has to be used. Clients can determine the behavior from the OpenAPI document or by inspecting the supportsNonAutogeneratedResourceIds field in the collection. An "id" member in a feature submitted in a POST or PUT request is ignored; a PATCH request that would change the identifier of the feature is rejected with HTTP 400, since the feature is identified by the URI of the resource.

To validate a new or updated feature submitted in a POST or PUT request against the schema of the collection (GeoJSON/JSON-GF) or the referenced XML Schemas (GML), a header Prefer with the value "handling=strict" can be added to the request. If the validation fails, an error is returned and the response reports the applied preference in a "Preference-Applied" header. The validation requires a schema: the building block SCHEMA_VALIDATION for GeoJSON and JSON-FG, the option "schemaLocations" of the GML building block for GML. Without it, the request body is not validated and the preference is ignored.

The option rejectEmptyValues adds a second check to "handling=strict": the request is rejected, if any value in the request body is an empty string or consists only of whitespace. The check is applied while the request body is decoded, so it needs no schema and is also applied where the request body cannot be validated against one.

A PUT, PATCH or DELETE request cannot be made conditional on an entity tag: no entity tag is known for the feature in a request that changes it, so an "If-Match" header cannot be met and the request is rejected with HTTP 412 ("Precondition Failed"). Use an "If-Unmodified-Since" header instead (see the option optimisticLockingLastModified).

If the feature in a POST or PUT request is GeoJSON without the JSON-FG extensions, include a header Link with the value "http://www.opengis.net/def/profile/OGC/0/rfc7946; rel=profile" in the request. For a feature with the JSON-FG extensions, use the value "http://www.opengis.net/def/profile/OGC/0/jsonfg; rel=profile".

Limitations

Only feature types from an SQL feature provider with dialect PGIS and datasetChanges.mode CRUD are supported.

The features may only have a single geometry property with scope RECEIVABLES.

Conformance Classes

The building block is based on the specifications of the conformance classes "Create/Replace/Delete", "Update", "Optimistic Locking using Timestamps", "Handling Preference" and "Features" from the Draft OGC API - Features - Part 4: Create, Replace, Update and Delete. The implementation will change as the draft will evolve during the standardization process.

Operations

Resource	Path	Methods	Media Types	Description
Features, Feature	collections/{collectionId}/items, collections/{collectionId}/items/{featureId}	DELETE, PATCH, POST, PUT		Create, Replace, Update and Delete features.

Path Parameters

Name	Resources	Description
collectionId	Features, Feature	The identifier of the feature collection.

Configuration

Options

Name	Default	Description	Type	Since
buildingBlock		Always CRUD.	string	v2.0
enabled	false	Enable the building block?	boolean	v2.0
optimisticLockingLastModified	false	Option to enable support for conditional processing of PUT, PATCH, and DELETE requests, based on the time when the feature was last updated. Such requests must include an If-Unmodified-Since header, otherwise they will be rejected with HTTP 428 ("Precondition Required"). A feature will only be changed, if the feature was not changed since the timestamp in the header (or if no last modification time is known for the feature), otherwise the response is HTTP 412 ("Precondition Failed"). The response to a successful PUT or PATCH request includes the new last modification time in a Last-Modified header, so that it can be used in the next conditional request. The last modification time of a feature is determined from a feature property with type DATETIME for which isLastModified is set to true in the schema in the feature provider; the property may be excluded from the scope RECEIVABLE.	boolean	v3.5
rejectEmptyValues	false	Option to reject empty values in the request body of a POST or PUT request. A value is empty, if it is a string without characters or with only whitespace. The check is only applied to requests with a Prefer header with the value "handling=strict"; such a request is rejected with HTTP 400 ("Bad Request") and the response states the first empty value. Values of other types cannot be empty, so where schema validation is also active an empty value can only occur in a string. The check is applied while the request body is decoded, so it needs no schema and is also applied, if no schema is available for validating the request body. A property that the request body omits, or states as null, is left without a value and is not affected.	boolean	v4.9

This building block does not require or support any additional configuration files.

Examples

- buildingBlock: CRUD
 enabled: true
 rejectEmptyValues: true