Transactions

specdraftimplcandidate

Atomic and batch transactions over multiple feature collections.

Scope

Provides a single resource POST /transactions that accepts a transaction document describing one or more insert, replace, update or delete actions across one or more feature collections of the API. The canonical request encoding is application/ogc-tx+json; the response is application/json.

Two semantics are supported: atomic transactions execute all actions as a single database transaction (rollback on failure), batch transactions execute each action independently and report per-action results.

For interoperability with WFS 2.0 producers the building block can additionally accept wfs:Transaction XML payloads in atomic mode.

The Prefer request header is honoured per RFC 7240: return=representation (the default), return=minimal, or return=none controls how much of the transaction response is returned; handling=strict validates every insert and replace payload against the feature-type schema before any provider write (this only takes effect when the collection has schema validation configured \u2014 JSON Schema for GeoJSON payloads, XSD for GML payloads). respond-async is rejected with 501.

The Content-Crs request header declares the CRS of coordinates in the request body. When omitted, the API's default CRS (CRS84 unless overridden) is assumed; values that are syntactically invalid or name a CRS not in the API's supported list are rejected with a 4xx error.

Both successful and atomic-failed responses use the same Part 11 Transaction Response document shape (with summary, the per-action result arrays, and an exceptions[] array when applicable), so clients do not need to branch on the response status to parse the body.

Limitations

The following restrictions apply:

• Provider and request scope:
• Only feature types from an SQL feature provider that supports mutations
  (datasetChanges.mode CRUD) are supported.
• Asynchronous transactions are not supported.
• Responses are always JSON; the WFS wfs:TransactionResponse XML response is not produced.
• wfs:Transaction XML payloads are accepted in atomic mode only.
• Filters in update, replace, and delete actions:
• Filters are restricted to selecting features by id. JSON action bodies accept only a CQL2
  id IN (...) expression (the _ID_ placeholder); other CQL2 predicates (comparison,
  spatial, temporal, or boolean operators on regular properties) are rejected with a 4xx
  error.
• wfs:Transaction XML accepts only fes:ResourceId/@rid; no other fes:Filter element
  types are recognised.
• update semantics:
• Updates are applied as an RFC 7396 JSON Merge Patch over a GeoJSON representation of the
  current feature, regardless of the payload encoding.
• In an atomic transaction, an update cannot target a feature that was inserted, replaced,
  updated, or deleted earlier in the same transaction; the action is rejected up front,
  because the read inside the update goes through the provider's normal query path and
  cannot see the transaction's still-uncommitted writes.
• In a wfs:Update, the wfs:ValueReference of each wfs:Property must be the GeoJSON
  property name (the wire name), not the underlying GML element or schema name; an unknown
  name is silently ignored and the property is not changed.

Conformance Classes

The building block is based on the conformance classes "Transactions", "Atomic Semantics", "Batch Semantics", "JSON Encoding" and "Features" from the Draft OGC API - Features - Part 11: Atomic and Batch Transactions.

Configuration

Options

Name	Default	Description	Type	Since
buildingBlock		Always TRANSACTIONS.	string	v2.0
enabled	false	Enable the building block?	boolean	v2.0
atomic	true	Advertises the conformance class for atomic transactions. When enabled, requests without a semantic parameter or with semantic=atomic are executed as a single database transaction; any failure rolls back the whole request.	boolean	v4.8
batch	true	Advertises the conformance class for batch transactions. When enabled, requests with semantic=batch execute each action independently and report per-action results, including exceptions for failures.	boolean	v4.8
wfsTransaction	false	Enables decoding of WFS 2.0 wfs:Transaction XML payloads at POST /transactions. Only valid when atomic is true and the GML building block is enabled.	boolean	v4.8
defaultSemantic	ATOMIC	Semantic applied to requests that do not specify one. The default matches the OGC API Features Part 11 specification default.	string	v4.8
maxActionsPerRequest	0	Optional upper bound on the number of actions per request. A value of zero or null disables the limit.	number	v4.8

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

Examples

- buildingBlock: TRANSACTIONS
 enabled: true
 atomic: true
 batch: true
 wfsTransaction: false
 defaultSemantic: ATOMIC