Features

These types of feature providers are supported:

Provider Type	Classification	Description
SQL	implmaturemainfull	The features are stored in a SQL database (PostgreSQL/PostGIS, GeoPackage, SQLite/SpatiaLite).
WFS	implcandidatemainnone	The features are retrieved from an OGC WFS.
Oracle	implproposalmainnone	The features are stored in an Oracle Spatial database.
GraphQL	implproposalmainnone	The features are retrieved from a GraphQL API. This feature provider is experimental and has severe limitations.

Configuration

These are common configuration options for all provider types.

Name	Default	Description	Type	Since
`id`		Unique identifier of the entity, has to match the filename. Allowed characters are (A-Z, a-z), numbers (0-9), underscore and hyphen.	string	v2.0
`enabled`	`true`	Option to disable the entity, which means it will not be available to other entities and background tasks will not be running.	boolean	v2.0
`providerType`		Always `FEATURE`.	string	v2.0
`providerSubType`		`SQL` for SQL DBMS as data source, `WFS` for OGC Web Feature Service as data source.	string	v2.0
`nativeCrs`	`CRS84`	Coordinate reference system of geometries in the dataset. The EPSG code of the coordinate reference system is given as integer in `code`. `forceAxisOrder` may be set to use a non-default axis order: `LON_LAT` uses longitude/east as first value and latitude/north as second value, `LAT_LON` uses the reverse. `NONE` uses the default axis order and is the default value. Example: The default coordinate reference system `CRS84` would look like this: `code: 4326` and `forceAxisOrder: LON_LAT`.	object	v2.0
`nativeTimeZone`	`UTC`	A timezone ID, such as `Europe/Berlin`. Is applied to temporal values without timezone in the dataset.	string	v2.0
`typeValidation`	`NONE`	Optional type definition validation with regard to the data source (only for SQL). `NONE` means no validation. With `LAX` the validation will fail and the provider will not start, when issues are detected that would definitely lead to runtime errors. Issues that might lead to runtime errors depending on the data will be logged as warning. With `STRICT` the validation will fail for any detected issue. That means the provider will only start if runtime errors with regard to the data source can be ruled out.	string	v2.0
`labelTemplate`	`{{value}}`	A template for schema labels. By default, the label set in the schema is used - or the name, if no label is set. The template is a string template and can contain the variables `{{value}}` for the schema label and `{{unit}}` for the unit declared in the schema. For example, to append the unit of measure in square brackets to the property label, one can use `{{value}}{{unit \| prepend:' [' \| append:']'}}`. This option is only supported in the SQL feature provider.	string	v2.0
`extensions`	`[]`	Definition of extensions, see Extensions.	array	v2.0
`types`	`{}`	Definition of feature types. The entries have to be schema definitions with `type: OBJECT` and at least one property with `role: ID`.	object	v2.0
`fragments`	`{}`	Definition of reusable schema fragments that can be referenced using `schema` in `types`. The entries are arbitrary schema definitions.	object	v2.0
`auto`	`false`	Option to derive `types` definitions automatically from the data source. When enabled `types` must not be set.	boolean	v2.0

Schema Definitions

Name	Default	Description	Type	Since
`embeddedRole`			string	v2.0
`sourcePath`		The relative path for this schema object. The syntax depends on the provider types, see SQL or WFS.	string	v2.0
`type`	`STRING/OBJECT`	Data type of the schema object. Default is `OBJECT` when `properties` is set, otherwise it is `STRING`. Possible values: - `FLOAT`, `INTEGER`, `STRING`, `BOOLEAN`, `DATETIME`, `DATE` for simple values. - `GEOMETRY` for geometries. - `OBJECT` for objects. - `OBJECT_ARRAY` for a list of objects. - `VALUE_ARRAY` for a list of simple values. - `FEATURE_REF` for a reference to another feature or external resource. - `FEATURE_REF_ARRAY` for a list of references to others features or external resources.	string	v2.0
`role`	`null`	Indicates special meanings of the property. `ID` is to be specified at the property of an object to be used for the `featureId` in the API. This property is typically the first property in the `properties` object. Allowed characters in these properties are all characters except the space character (" ") and the horizontal bar ("/"). `TYPE` can be specified at the property of an object that contains the name of a subobject type. If an object type has multiple geometry properties, then specify `PRIMARY_GEOMETRY` at the property to be used for `bbox` queries and to be encoded in data formats with exactly one or a singled out geometry (e.g. in GeoJSON `geometry`). If an object type has multiple temporal properties, then `PRIMARY_INSTANT` should be specified at the property to be used for `datetime` queries, provided that a time instant describes the temporal extent of the features. If, on the other hand, the temporal extent is a time interval, then `PRIMARY_INTERVAL_START` and `PRIMARY_INTERVAL_END` should be specified at the respective temporal properties.	string	v2.0
`valueType`	`STRING`	Only needed when `type` is `VALUE_ARRAY`. Possible values: `FLOAT`, `INTEGER`, `STRING`, `BOOLEAN`, `DATETIME`, `DATE`	string	v2.0
`geometryType`	`null`	The specific geometry type for properties with `type: GEOMETRY`. Possible values are simple feature geometry types: `POINT`, `MULTI_POINT`, `LINE_STRING`, `MULTI_LINE_STRING`, `POLYGON`, `MULTI_POLYGON`, `GEOMETRY_COLLECTION` and `ANY`	string	v2.0
`objectType`		Optional name for an object type, used for example in JSON Schema. For properties that should be mapped as links according to RFC 8288, use `Link`.	string	v2.0
`label`		Label for the schema object, used for example in HTML representations.	string	v2.0
`description`		Description for the schema object, used for example in HTML representations or JSON Schema.	string	v2.0
`unit`		The unit of measurement of the value, only relevant for numeric properties.	string	v2.0
`format`		The SQL date/time format string of the values in the database column. This parameter only applies to `DATE` and `DATETIME` values where the value is stored in a string column in a `PGIS` or `ORACLE` database.	string	v2.0
`constantValue`	`null`	Might be used instead of `sourcePath` to define a property with a constant value.	string	v2.0
`excludedScopes`	`[]`	Optional exclusion of a property from a schema scope. See Schema Scopes for a description of the scopes.	array	v2.0
`refType`		For a property of type `FEATURE_REF` or `FEATURE_REF_ARRAY` where the target is always a feature of another type in the same provider, declare the feature type identifier in `refType`. For details see Feature References.	string	v2.0
`refUriTemplate`		For a property of type `FEATURE_REF` or `FEATURE_REF_ARRAY` where the target is an external resource, declare the URI template of the link in `refUriTemplate`. For details see Feature References.	string	v2.0
`refKeyTemplate`		For a property of type `FEATURE_REF` or `FEATURE_REF_ARRAY` where the type of the target varies, declare the string template of the foreign key in `refKeyTemplate`. For details see Feature References.	string	v2.0
`embed`		For a property of type `FEATURE_REF` or `FEATURE_REF_ARRAY` where the target is always a feature of another type in the same provider, the value will be embedded, not referenced, if the value is `ALWAYS`. The `sourcePath` of the property must end at the referenced feature; that is, at least the `id` property of the reference must be declared explicitly.	string	v2.0
`schema`	`null`	Reference to an external schema definition. The default resolver will resolve references to entries in `fragments` e.g. `#/fragments/example`. For additional resolvers see Extensions.	string	v2.0
`ignore`	`false`	Option to completely ignore this schema object. Main purpose is to ignore parts of schemas referenced with `schema`.	boolean	v2.0
`transformations`	`[]`	Optional transformations for the property, see transformations.	array	v2.0
`constraints`	`{}`	Optional description of schema constraints, especially for JSON schema generation. See Constraints.	object	v2.0
`forcePolygonCCW`	`true`	Option to disable enforcement of counter-clockwise orientation for exterior rings and a clockwise orientation for interior rings (only for SQL).	boolean	v2.0
`linearizeCurves`	`false`	Option to linearize curve geometries (e.g., CircularString or CurvePolygon) to a Simple Features geometry. This option only applies to SQL feature providers of dialect PostGIS.	boolean	v2.0
`isLastModified`	`see description`	Identifies a DATETIME property as a property that contains the timestamp when the feature was last modified. This information is used in optimistic locking to evaluate the pre-conditions, if a mutation request includes a `Last-Modified` header.	boolean	v2.0
`properties`		Only for `OBJECT` and `OBJECT_ARRAY`. Object with the property names as keys and schema objects as values.	object	v2.0
`merge`	`[]`	If only some of the `properties` are defined in an external `schema`, or if some of the `properties` should be mapped to a different table, this provides a convenient way to define these properties alongside the regular properties. The option takes a list of schema objects, but only `sourcePath`, `schema` and `properties` are considered. For details see Mapping Operations.	array	v2.0
`coalesce`	`[]`	If the value for a property may come from more than one `sourcePath`, this allows to choose the first non-null value. This takes a list of value schemas, for details see Mapping Operations.	array	v2.0
`concat`	`[]`	If the values for an array property may come from more than one `sourcePath`, this allows to concatenate all available values. This takes a list of value or value array schemas, for details see Mapping Operations.	array	v2.0

Connection Info

For data source specifics, see SQL and WFS.

Example Configuration (SQL)

See the feature provideropen in new window of the API Vineyards in Rhineland-Palatinate, Germanyopen in new window.

Mapping Operations

Mapping operations may be needed when the source and target schema structure diverge too much.

Merge

If only some of the properties are defined in an external schema, or if some of the properties should be mapped to a different table, this provides a convenient way to define these properties alongside the regular properties.

Examples

Define only some properties using an external JSON schema


example:
  sourcePath: /main
  type: OBJECT
  merge:
  - properties:
      id:
        sourcePath: id
        type: INTEGER
        role: ID
  - sourcePath: '[JSON]names'
    schema: names.json

Using columns from a joined table in the main feature


example:
  sourcePath: /main
  type: OBJECT
  merge:
  - properties:
      id:
        sourcePath: id
        type: INTEGER
        role: ID
  - sourcePath: '[id=id]names'
    properties:
      name1:
        sourcePath: name1
        type: STRING
      name2:
        sourcePath: name2
        type: STRING

Coalesce

If the value for a property may come from more than one sourcePath, this allows to choose the first non-null value.

Example


foo:
  type: OBJECT
  properties:
    bar:
      type: VALUE
      coalesce:
      - sourcePath: bar_stringValue
        type: STRING
      - sourcePath: bar_integerValue
        type: INTEGER
      - sourcePath: bar_booleanValue
        type: BOOLEAN

Type compatibility

Constraints on the types of inner properties depending on the type of the outer property are shown in the table below.

Outer type	Valid inner types	Remarks
`VALUE`	`INTEGER`, `FLOAT`, `STRING`, `BOOLEAN`, `DATETIME`, `DATE`
`INTEGER`	`INTEGER`
`FLOAT`	`FLOAT`
`STRING`	`STRING`
`BOOLEAN`	`BOOLEAN`
`DATETIME`	`DATETIME`
`DATE`	`DATE`
`OBJECT`	`OBJECT`	Different `objectType` with different schemas can be used
`FEATURE_REF`	`FEATURE_REF`	Different `refType` can be used

Concat

If the values for an array property or the instances of a feature type may come from more than one sourcePath, this allows to concatenate all available values.

For feature types using concat, the different concatenated "sub-types" must meet the following constraints:

All ID properties must have the same path and type.
All primary geometry properties must have the same path and be Simple Features geometries.
All primary temporal properties must have the same path and type (e.g., all are DATE instants).

Examples


foo:
  type: OBJECT
  properties:
    bar:
      type: FEATURE_REF_ARRAY
      concat:
      - sourcePath: '[id=foo_fk]baz1/id'
        refType: baz1
      - sourcePath: '[id=foo_fk]baz2/id'
        refType: baz2
      - sourcePath: '[id=foo_fk]bazn/id'
        refType: bazn


administrativeunit:
  type: OBJECT
  concat:
  - sourcePath: "/au1"
    type: OBJECT
    properties:
      id:
        sourcePath: id1
        type: STRING
        role: ID
  - sourcePath: "/au2"
    type: OBJECT
    properties:
      id:
        sourcePath: id2
        type: STRING
        role: ID

Type compatibility

Constraints on the types of inner properties depending on the type of the outer property are shown in the table below.

Outer type	Valid inner types	Remarks
`VALUE_ARRAY`	`VALUE_ARRAY`, `INTEGER`, `FLOAT`, `STRING`, `BOOLEAN`, `DATETIME`, `DATE`
`OBJECT_ARRAY`	`OBJECT_ARRAY`, `OBJECT`	Different `objectType` with different schemas can be used
`FEATURE_REF_ARRAY`	`FEATURE_REF_ARRAY`, `FEATURE_REF`	Different `refType` can be used
`OBJECT`	`OBJECT`	Only for feature types

Feature References

Feature references (type FEATURE_REF or FEATURE_REF_ARRAY) are object properties with three pre-defined properties: id, title, and type.

id is the foreign key, that is the ID property of a referenced feature, and is either a STRING or INTEGER.
title is the title to use when presenting the link to a user, a STRING. The default value is the id, if the property is not specified.
type is the feature type of the referenced feature in the same feature provider, a STRING.

Limitations: These properties do not support transformations (e.g. stringFormat) or coalesce.

Encoding feature references

When requested via the API, the feature reference can be encoded according to different profiles using the query parameter profile and depending on the negotiated feature format. The following profiles are supported:

rel-as-key: the identifier of the feature in its collection (the featureId);
rel-as-uri: the URI of the feature;
rel-as-link: an object with two properties: href with the URI of the feature and title with a title of the feature.

The rel-as-link profile is typically not supported for feature formats that do not support object properties, e.g., CSV or FlatGeobuf. In HTML, a link is encoded as an <a> element, in GML using XLink attributes.

The profile is negotiated based on the requested profile (default is rel-as-link) and the supported profiles of the negotiated format based on the Accept header and the query parameter f.

Configuration

Simple Case

If the default value of title (that is, the id) is sufficient and the target features are in the same API and all in the same collection, the properties of the object do not need to be specified in the schema. It is sufficient to specify the following configuration property:

sourcePath: The value with the id of the referenced feature.
type: The type of the id, either STRING (the default) or INTEGER.
refType: the identifier of the feature type / collection of the referenced feature.

In the following example, the abs column is the foreign key of the referenced feature in the abschnitteaeste feature type:


abs:
  sourcePath: abs
  type: FEATURE_REF
  label: Abschnitt/Ast
  description: 16-stellige Kennung des Abschnittes oder Astes
  refType: abschnitteaeste

In the next example, there are two columns (abs and ast) which are foreign keys of the referenced feature in the abschnitte or aeste feature type. Only one of the two values is set and the first value that is not null is used:


abs:
  type: FEATURE_REF
  label: Abschnitt/Ast
  description: 16-stellige Kennung des Abschnittes oder Astes
  coalesce:
  - sourcePath: abs
    refType: abschnitte
  - sourcePath: ast
    refType: aeste

Advanced Cases

If the title should differ from id, if the type of the referenced feature is determined from the data, or if the referenced resource is outside of the API, the properties of the feature reference are explicitly specified in the feature schema.

Example:


unfaelle:
  sourcePath: "[abs=abs]unfaelle_point"
  type: FEATURE_REF_ARRAY
  label: Unfälle
  description: Unfälle auf dem Abschnitt oder Ast
  properties:
    id:
      type: INTEGER
      sourcePath: fid
    title:
      type: STRING
      sourcePath: unfzeit
    type:
      type: STRING
      constantValue: unfaelle

In addition, the following configuration options can be specified:

refKeyTemplate: the string template for the value in the rel-as-key profile. Parameters are id and type. The default is {{id}}, if type is constant, otherwise {{type}}::{{id}}.
refUriTemplate: the string template of the URI of the referenced feature. Parameters are id, type, and apiUri (the URI of the landing page of the API). The default is {{apiUri}}/collections/{{type}}/items/{{id}}.

Example:


externalReferences:
  sourcePath: "[fk=oid]externalref"
  type: FEATURE_REF_ARRAY
  label: External References
  refUriTemplate: "https://example.com/foo/bar/{{type}}/{{id}}"
  refKeyTemplate: "{{type}}_{{id}}"
  properties:
  id:
    type: INTEGER
    sourcePath: oid
  title:
    type: STRING
    sourcePath: label
  type:
    type: STRING
    sourcePath: type

Embedding Feature References

Feature references can also be embedded inline instead of creating a reference/link. To always embed the referenced features, the embed option in the feature schema of the feature reference is set to ALWAYS.

Configuration

The sourcePath of the feature reference property must end at the referenced feature; that is, at least the id property of the reference must be declared explicitly.

In the following example, the abs column is the foreign key of the referenced feature in the abschnitteaeste feature type:


abs:
  sourcePath: '[abs=abs]abschnitteaeste_line'
  type: FEATURE_REF
  embed: ALWAYS
  label: Abschnitt/Ast
  description: 16-stellige Kennung des Abschnittes oder Astes
  refType: abschnitteaeste
  properties:
    id:
      type: STRING
      sourcePath: abs

# Features

# Configuration

# Schema Definitions

# Connection Info

# Example Configuration (SQL)

# Mapping Operations

# Merge

# Examples

# Define only some properties using an external JSON schema

# Using columns from a joined table in the main feature

# Coalesce

# Example

# Type compatibility

# Concat

# Examples

# Type compatibility

# Feature References

# Encoding feature references

# Configuration

# Simple Case

# Advanced Cases

# Embedding Feature References

# Configuration

Features

Configuration

Schema Definitions

Connection Info

Example Configuration (SQL)

Mapping Operations

Merge

Examples

Define only some properties using an external JSON schema

Using columns from a joined table in the main feature

Coalesce

Example

Type compatibility

Concat

Examples

Type compatibility

Feature References

Encoding feature references

Configuration

Simple Case

Advanced Cases

Embedding Feature References

Configuration