ldproxy

Features - GML

specstableimplcandidate

Encode features as GML.

Scope

For a WFS feature provider, the features are accessed as GML from the WFS and rewritten to the response. In case of Features the root element is sf:FeatureCollection.

For a SQL feature provider, the features are mapped to GML object and property elements based on the provider schema. A number of configuration options exist to control how the features are mapped to XML.

All configuration options of this building block except gmlSfLevel are only applicable for collections with a SQL feature provider. For collections with a WFS feature provider, all other configuration options are ignored.

The following descriptions all apply only to collections with a SQL feature provider:

  • The feature property with the role ID in the provider schema is mapped to the gml:id
    attribute of the feature. These properties must be a direct property of the feature type.
    If gmlIdPrefix is set, the prefix is prepended to every gml:id value to keep them
    valid XML IDs. If appendTemporalSuffixToGmlId is true and the request's datetime
    parameter is an interval, the value of the primary temporal property is appended to the
    gml:id formatted as yyyyMMddTHHmmssX.
  • If gmlIdentifier is configured, a gml:identifier element is emitted as the first
    child of every feature, with the configured codeSpace attribute and the feature id
    (optionally substituted into valueTemplate) as text.
  • Geometry properties are mapped to GML 3.2 elements depending on the geometry type:
    Point is mapped to gml:Point (with gml:pos); MultiPoint to gml:MultiPoint;
    LineString to gml:LineString (with gml:posList); CircularString to gml:Curve
    with a gml:Arc segment (three control points) or gml:ArcString segment (more than
    three control points); CompoundCurve to gml:Curve with multiple segments;
    MultiLineString and MultiCurve to gml:MultiCurve; Polygon and CurvePolygon to
    gml:Polygon with gml:LinearRing rings; MultiPolygon and MultiSurface to
    gml:MultiSurface; PolyhedralSurface to gml:Solid (when closed) or
    gml:PolyhedralSurface (when open); and GeometryCollection to gml:MultiGeometry.
    With useSurfaceAndCurve: true, the following alternative encodings are used: simple
    line strings as gml:Curve with one gml:LineStringSegment; simple polygons (and
    CurvePolygon) as gml:Surface with one gml:PolygonPatch; compound curves as
    gml:CompositeCurve; and all rings inside polygons as gml:Ring with one or more
    gml:LineStringSegment curve members instead of gml:LinearRing. No gml:id is added
    to geometry elements unless gmlIdOnGeometries: true. The srsName attribute is set on
    every geometry; with srsNameStyle: TEMPLATE, the value is taken from srsNameMappings
    instead of the OGC URI form. With srsDimension: true, a srsDimension attribute is
    also added to pos and posList.
  • Properties that are OBJECTs with object type Link will be mapped to a gml:Reference
    value with xlink:href and xlink:title attributes, if set. For feature-reference
    properties (declared with refType), featureRefTemplate can rewrite xlink:href into
    a URN-style identifier (e.g. urn:adv:oid:{{value}}).
  • Properties that are OBJECTs with object type Measure will be mapped to a
    gml:MeasureType value. The object must have the properties value and uom, which
    both must be present in the data.
  • Properties that are FLOAT or INTEGER values with a unit property in the provider
    schema are also mapped to a gml:MeasureType value. The value of unit is mapped to
    the uom attribute. With uomStyle: TEMPLATE, the unit string is resolved via
    uomMappings.
  • Properties listed in codelistProperties are encoded as empty XML elements with
    xlink:href (constructed from codelistUriTemplate) and xlink:title (the codelist
    label, falling back to the raw value if no label is found), instead of writing the raw
    value as element text.
  • Each property element is named after the property in the feature schema; with
    useAlias: true, properties that declare an alias are encoded under that alias
    instead. The element is placed in the namespace of its parent object type as declared by
    objectTypeNamespaces. An explicit prefix:name in the schema or a rename
    transformation takes precedence over both the inherited namespace and the alias.
  • Properties listed in valueWrap have their scalar value wrapped in one or more nested
    XML elements declared in the configuration (outer to inner), with the value appearing
    inside the innermost wrapper. This is useful for application schemas that nest atomic
    values inside wrapper types.

Conformance Classes

In general, Features GML implements all requirements of conformance class Geography Markup Language (GML), Simple Features Profile, Level 0 and Geography Markup Language (GML), Simple Features Profile, Level 2 from OGC API - Features - Part 1: Core 1.0open in new window. However, conformance depends on the conformance of the GML application schema with the GML Simple Features standard. Since the GML application schema is not controlled by ldproxy, the conformance level needs to be declared as part of the configuration.

For SQL feature providers a different root element than sf:FeatureCollection can be configured for the Features resource. In that case, the API cannot conform to any of the GML conformance classes of OGC API Features.

Configuration

By default, every GML property element will receive the property name from the feature schema. The element is placed in the namespace of its containing object type (declared via objectTypeNamespaces); if the parent object type has no namespace mapping, the element stays in the default namespace. A different name or an explicit namespace can be set using the rename transformation, which takes precedence over the inherited namespace.

Options

NameDefaultDescriptionTypeSince
buildingBlock
Always GML.
string
v2.0
enabled
false
Enable the building block?
boolean
v2.0
transformations
{}
Property transformations do not affect data sources, they are applied on-the-fly as part of the encoding. Filter expressions do not take transformations into account, they have to be based on the source values. That means queryable properties (see queryables in Features) should not use transformations in most cases. The exception to the rule is the HTML encoding, where readability might be more important than filter support.
object
v2.0
useAlias
false
If true, properties of the feature schema that declare an alias are encoded under their alias instead of their schema name. Useful for application schemas where each property carries both a short technical name and a longer mnemonic name (e.g. AdV NAS: arf / artDerFlurstuecksgrenze). An explicit rename transformation on a property still takes precedence over the alias. The flag only affects feature encoding output; queryables, sortables and other schema-derivation paths always use the schema names.
boolean
v2.0
gmlVersion
GML32
Selects the GML version to use: GML32 for GML 3.2, GML31 for GML 3.1 and GML21 for GML 2.1.
string
v3.3
gmlSfLevel
null
The default null declares that the GML support does not meet all requirements of the Geography Markup Language (GML), Simple Features Profile, Level 0 or the Geography Markup Language (GML), Simple Features Profile, Level 2 conformance classes from OGC API - Features - Part 1: Core 1.0open in new window. If the value is set to 0, 1 or 2, the conformance will be declared in the Conformance Declaration resource. If for a collection from a SQL feature provider a root element different to sf:FeatureCollection is configured in featureCollectionElementName, the value will be ignored and no conformance to a GML conformance class will be declared.
number
v3.3
conformance
string
v2.0
applicationNamespaces
{}
Every XML element will have and XML attribute can have an XML namespace. To improve readability of the XML documents, a namespace prefix is declared for every namespace. Common namespaces and prefixes are pre-defined, these are: gml (GML 3.2), xlink (XLink), xml (XML), sf (OGC API Features Core 1.0, Core-SF), wfs (WFS 2.0), and xsi (XML Schema Information). Additional namespaces that are used in the data (declared in GML application schemas and imported schemas), the namespaces are configured with their prefixes. Since feature data will always use elements in application-schema-specific namespaces, this confirguration parameter will always need to be specified.
object
v3.3
defaultNamespace
null
A default namespace that is used for XML elements, if no other namespace is specified, can be specified with this configuration parameter. The value will be the namespace prefix. It must be either a pre-defined prefix or a prefix declared in applicationNamespaces. This namespace will be declared as the default namespace of the XML document.
string
v3.3
schemaLocations
null
If any application namespace should be included in the xsi:schemaLocation attribute of the root element, the document URIs have to be provided. In addition, the schema location of the namespace of the root element will be added, if known. For the pre-defined namespaces (gml, sf and wfs), the canonical schema location in the OGC schema repository will be used unless another schema location for the namespace is configured. Note that to meet XML Schema validation requirements, the namespace of the root element must be declared in the xsi:schemaLocation attribute, even if the namespace is imported by another schema.
object
v3.3
objectTypeNamespaces
{}
All object/data type instances are represented through a GML object element. In the provider schema, a name must be provided for each OBJECT in the objectType property, including for the feature type itself. By default, this name will be used for the unqualified name of the GML object element. If the GML object element is not in the default namespace, this configuration parameter assigns a namespace prefix to an object type. The mapped prefix is also applied to the property elements declared by that object type (its child elements in the schema tree). This matches the XML Schema convention elementFormDefault="qualified": a property element lives in the target namespace of the complex type that declares it. Property names (or their aliases) should therefore be unprefixed in the provider schema; the namespace is added automatically from the parent object type's mapping. An explicit prefix:name in the schema name or alias still takes precedence.
object
v3.3
variableObjectElementNames
{}
There may also be cases, in particular when inheritance is used in the underlying application schema, where multiple object types are represented in the same table with an attribute that specifies the name of the feature/object type. This configuration parameter provides the capability to identify these properties and map the values to qualified names for the GML object element. In the example, _type is the feature property with three different values mapped to the qualified element name.
object
v3.3
featureCollectionElementName
sf:FeatureCollection
Various feature collection elements are in use and sometimes additional ones are specified in GML application schemas. The default is sf:FeatureCollection as specified by OGC API Features. This configuration parameter provides a capability to use a different feature collection element.
string
v3.3
featureMemberElementName
sf:featureMember
The feature collection element referenced in featureCollectionElementName has a child property element that contains each feature. The default is sf:featureMember as specified by OGC API Features. This configuration parameter provides a capability to declare the element name for the feature collection element.
string
v3.3
supportsStandardResponseParameters
false
The feature collection element referenced in featureCollectionElementName may support the WFS 2.0 standard response parameters (timeStamp, numberMatched, numberReturned). This configuration parameter controls whether the attributes are included in the feature collection element as XML attributes.
boolean
v3.3
xmlAttributes
[]
Properties are by default represented as the XML child element (GML property element) of the XML element representing the object (GML object element). Alternatively, the property can be represented as an XML attribute of the parent GML object element. This is only possible for properties of type STRING, FLOAT, INTEGER, or BOOLEAN.
array
v3.3
gmlIdPrefix
null
The feature property with role ID in the provider schema is mapped to the gml:id attribute of the feature. These properties must be a direct property of the feature type. If the values violate the rule for XML IDs, e.g., if they can start with a digit, this configuration parameter can be used to add a consistent prefix to map all values to valid XML IDs.
string
v3.3
gmlIdOnGeometries
false
This option adds a gml:id attribute on all GML geometry elements. The id attribute was required by GML 3.2 until 2016, older copies of the GML schema may still require the attribute. This option allows to create instances that are valid for such schemas.
boolean
v4.0
srsDimension
false
This option adds a srsDimension attribute on all GML posList and pos elements. Some GML readers expect this information, especially for 3D coordinates.
boolean
v4.6
useSurfaceAndCurve
false
If enabled, simple polygons are encoded as {@code gml:Surface} with a single {@code gml:PolygonPatch} instead of {@code gml:Polygon}, and simple line strings are encoded as {@code gml:Curve} with a single {@code gml:LineStringSegment} instead of {@code gml:LineString}. All rings are encoded as {@code gml:Ring} with a single {@code gml:LineStringSegment} curve member instead of {@code gml:LinearRing}. This option is useful when the target GML application schema requires these geometry types.
boolean
v4.8
defaultProfiles
{"rel": "rel-as-link", "val": "val-as-code"}
Change the default value of the profile parameter for this feature format. The value is an object where the key is the id of a profile set and the value is the default profile for the profile set. These defaults override the defaults specified in the Features building block. For GML, the following default profiles are set: "rel-as-link" for feature relationships and "val-as-code" for properties with coded values. Changing these profiles will likely result in a GML representation that is not valid against the GML application schema which typically do not support variations of the representation.
object
v4.2
srsNameStyle
OGC
Controls how the {@code srsName} attribute on geometries is rendered. {@code OGC} (the default) emits the OGC URI form (e.g. {@code http://www.opengis.net/def/crs/EPSG/0/25832open in new window}). {@code TEMPLATE} looks up the CRS in {@code srsNameMappings} and uses the mapped value; CRS without a mapping fall back to the {@code OGC} form.
string
v4.9
srsNameMappings
[]
Mapping list used when {@code srsNameStyle} is {@code TEMPLATE}. Each entry binds a CRS to a fixed {@code srsName} value. Useful for application schemas that require non-OGC URIs (e.g. AdV: {@code urn:adv:crs:ETRS89_UTM32}).
array
v4.9
uomStyle
RAW
Controls how the {@code uom} attribute on measure-typed properties is rendered. {@code RAW} (the default) writes the unit string from the provider schema verbatim. {@code TEMPLATE} looks up the unit in {@code uomMappings} and uses the mapped value; units without a mapping fall back to the raw value.
string
v4.9
uomMappings
[]
Mapping list used when {@code uomStyle} is {@code TEMPLATE}. Each entry binds a unit string to a fixed {@code uom} value. Useful for application schemas that require non-UCUM identifiers (e.g. AdV: {@code urn:adv:uom:m}).
array
v4.9
featureRefTemplate
null
URI/URN template applied to {@code xlink:href} of feature reference properties (i.e. properties with {@code refType}). The placeholder {@code } is replaced with the referenced feature id (the segment after {@code /items/} in the original href). Default {@code null} keeps the original href. Useful for application schemas that require URN-style references (e.g. AdV: {@code urn:adv:oid:}). Does not affect links inside generic {@code Link} objects.
string
v4.9
gmlIdentifier
null
If set, a {@code gml:identifier} child element is emitted as the first child of every feature with the configured {@code codeSpace} attribute. The element's text value is the raw feature id from the provider, optionally substituted into {@code valueTemplate} (where {@code } is replaced with the raw id). Useful for application schemas that mandate {@code gml:identifier} (e.g. AdV NAS).
object
v4.9
appendTemporalSuffixToGmlId
false
If {@code true} and the request's {@code datetime} parameter is an interval (contains {@code /}), the {@code gml:id} of every feature is suffixed with the feature's primary temporal property value formatted as {@code yyyyMMddTHHmmssX}. The source property is the one with role {@code PRIMARY_INSTANT}, falling back to {@code PRIMARY_INTERVAL_START}. Useful for application schemas that require {@code gml:id} to be unique per feature version (e.g. AdV NAS time-series queries). Does not affect {@code gml:identifier}.
boolean
v4.9
codelistUriTemplate
null
URI template used to construct the {@code xlink:href} for properties that carry a codelist value. The template may contain the placeholders {@code } (replaced with the codelist id from {@code codelistProperties}) and {@code } (replaced with the raw property value). When set together with {@code codelistProperties}, the matching property is encoded as an empty element {@code } where {@code xlink:title} is the codelist label looked up from the resolved codelist (falling back to the raw value if no label is found).
string
v4.9
codelistProperties
{}
Maps property paths (matching {@code FeatureSchema#getFullPathAsString()}) to a codelist id. Properties listed here are encoded as xlink elements using {@code codelistUriTemplate} instead of the raw value being written as element text. Entries defined at the building-block (API) level apply to all collections; per-collection entries are merged on top.
object
v4.9
valueWrap
{}
Maps property paths (matching {@code FeatureSchema#getFullPathAsString()} at encoding time, i.e. after any {@code rename} transformations) to a list of XML element names (outer to inner) that wrap the scalar value. When a path matches, the property element content is encoded as {@code } instead of the plain value. Element names may be namespace-qualified (e.g. {@code gco:DateTime}), provided the prefix is declared in {@code applicationNamespaces}.
object
v4.9

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

Examples

The following example shows a basic declaration of namespaces and their schema locations, the configuration of a gml:id prefix to ensure XML ID compatibility as well as specific configuration options for a feature type.


- buildingBlock: GML
 enabled: true
 applicationNamespaces:
   ns1: http://www.example.com/ns/ns1/1.0
   ns2: http://www.example.com/ns/ns2/1.0
 defaultNamespace: ns1
 schemaLocations:
   ns1: '{{serviceUrl}}/resources/ns1.xsd'
   ns2: '{{serviceUrl}}/resources/ns2.xsd'
 gmlIdPrefix: '_'
collections:
 some_type:
   ...
   api:
   - buildingBlock: GML
     xmlAttributes:
       - someAtt
     transformations:
       someOtherAtt:
         rename: 'ns2:someOtherAtt'

The following example combines all options that are typically required to publish data according to the German AFIS-ALKIS-ATKIS NAS application schema. Each option is individually opt-in and reusable for other GML application schemas.

The useAlias: true option causes every feature-schema property that declares an alias (see the alias field in the feature provider schema) to be encoded under its alias instead of its short three-letter code, if that is used in the provider schema.


- buildingBlock: GML
 enabled: true
 useAlias: true
 useSurfaceAndCurve: true
 applicationNamespaces:
   aaa: 'http://www.adv-online.de/namespaces/adv/gid/7.1'
 defaultNamespace: aaa
 schemaLocations:
   aaa: 'https://repository.gdi-de.org/schemas/adv/nas/7.1/aaa.xsd'
 featureRefTemplate: 'urn:adv:oid:{{value}}'
 gmlIdentifier:
   codeSpace: 'http://www.adv-online.de/'
   valueTemplate: 'urn:adv:oid:{{value}}'
 appendTemporalSuffixToGmlId: true
 srsNameStyle: TEMPLATE
 srsNameMappings:
   - crs:
       code: 25832
       forceAxisOrder: NONE
     value: 'urn:adv:crs:ETRS89_UTM32'
   - crs:
       code: 25833
       forceAxisOrder: NONE
     value: 'urn:adv:crs:ETRS89_UTM33'
   - crs:
       code: 4326
       forceAxisOrder: NONE
     value: 'urn:adv:crs:WGS84_Lat-Lon'
   - crs:
       code: 4326
       forceAxisOrder: LON_LAT
     value: 'urn:adv:crs:WGS84_Lon-Lat'
 uomStyle: TEMPLATE
 uomMappings:
   - uom: 'm'
     value: 'urn:adv:uom:m'
   - uom: 'grad'
     value: 'urn:adv:uom:grad'
 codelistUriTemplate: 'https://registry.gdi-de.org/codelist/de.adv.alkis/{{codelistId}}/{{value}}'
 codelistProperties:
   anlass: AX_Anlassart
 objectTypeNamespaces:
   LI_Lineage: gmd
   LI_ProcessStep: gmd
   LI_Source: gmd
 valueWrap:
   lebenszeitintervall:
     - AA_Lebenszeitintervall
     - beginnt
   qualitaetsangaben.herkunft.processStep.description:
     - AX_LI_ProcessStep_Punktort_Description
   qualitaetsangaben.herkunft.processStep.dateTime:
     - gco:DateTime
   qualitaetsangaben.herkunft.processStep.source.description:
     - AX_Datenerhebung_Punktort
Legal NoticePrivacy Notice