Mapping File¶

Mapping file schema¶

• AppSchemaDataAccess.xsd is optional because it is not used by GeoServer. The presence of AppSchemaDataAccess.xsd in the same folder as the mapping file enables XML editors to observe its grammar and provide contextual help.

namespaces¶

The namespaces section defines all the XML namespaces used in the mapping file:

<Namespace>
    <prefix>gsml</prefix>
    <uri>urn:cgi:xmlns:CGI:GeoSciML:2.0</uri>
</Namespace>
<Namespace>
    <prefix>gml</prefix>
    <uri>http://www.opengis.net/gml</uri>
</Namespace>
<Namespace>
    <prefix>xlink</prefix>
    <uri>http://www.w3.org/1999/xlink</uri>
</Namespace>

includedTypes (optional)¶

Non-feature types (eg. gsml:CompositionPart is a data type that is nested in gsml:GeologicUnit) may be mapped separately for its reusability, but we don’t want to configure it as a feature type as we don’t want to individually access it. Related feature types don’t need to be explicitly included here as it would have its own workspace configuration for GeoServer to find it. The location path in Include tag is relative to the mapping file. For an example, if gsml:CompositionPart configuration file is located in the same directory as the gsml:GeologicUnit configuration:

<includedTypes>
    <Include>gsml_CompositionPart.xml</Include>
</includedTypes>

sourceDataStores¶

Every mapping file requires at least one data store to provide data for features. app-schema reuses GeoServer data stores, so there are many available types. See Data Stores for details of data store configuration. For example:

<sourceDataStores>
    <DataStore>
        <id>datastore</id>
        <parameters>
            ...
        </parameters>
    </DataStore>
    ...
</sourceDataStores>

If you have more than one DataStore in a mapping file, be sure to give them each a distinct id.

catalog (optional)¶

The location of an OASIS XML Catalog configuration file, given as a path relative to the mapping file. See Application Schema Resolution for more information. For example:

<catalog>../../../schemas/catalog.xml</catalog>

targetTypes¶

The targetTypes section lists all the application schemas required to define the mapping. Typically only one is required. For example:

<targetTypes>
    <FeatureType>
        <schemaUri>http://www.geosciml.org/geosciml/2.0/xsd/geosciml.xsd</schemaUri>
    </FeatureType>
</targetTypes>

typeMappings and FeatureTypeMapping¶

The typeMappings section is the heart of the app-schema module. It defines the mapping from simple features to the the nested structure of one or more simple features. It consists of a list of FeatureTypeMapping elements, which each define one output feature type. For example:

<typeMappings>
    <FeatureTypeMapping>
        <mappingName>mappedfeature1</mappingName>
        <sourceDataStore>datastore</sourceDataStore>
        <sourceType>mappedfeature</sourceType>
        <targetElement>gsml:MappedFeature</targetElement>
        <attributeMappings>
            <AttributeMapping>
                ...

• mappingName is an optional tag, to identify the mapping in Feature Chaining when there are multiple FeatureTypeMapping instances for the same type. This is solely for feature chaining purposes, and would not work for identifying top level features.

• sourceDataStore must be an identifier you provided when you defined a source data store the sourceDataStores section.

• sourceType is the simple feature type name. For example:

  • a table or view name, lowercase for PostGIS, uppercase for Oracle.
  • a property file name (without the .properties suffix)

• targetElement is the the element name in the target application schema. This is the same as the WFS feature type name.

attributeMappings and AttributeMapping¶

attributeMappings comprises a list of AttributeMapping elements:

<AttributeMapping>
    <targetAttribute>...</targetAttribute>
    <idExpression>...</idExpression>
    <sourceExpression>...</sourceExpression>
    <targetAttributeNode>...</targetAttributeNode>
    <isMultiple>...</isMultiple>
    <ClientProperty>...</ClientProperty>
</AttributeMapping>

targetAttribute¶

targetAttribute is the XPath to the output element, in the context of the target element. For example, if the containing mapping is for a feature, you should be able to map a gml:name property by setting the target attribute:

<targetAttribute>gml:name</targetAttribute>

Multivalued attributes resulting from Denormalised sources are automatically encoded. If you wish to encode multivalued attributes from different input columns as a specific instance of an attribute, you can use a (one-based) index. For example, you can set the third gml:name with:

<targetAttribute>gml:name[3]</targetAttribute>

The reserved name FEATURE_LINK is used to map data that is not encoded in XML but is required for use in Feature Chaining.

idExpression¶

A CQL expression that is used to set the gml:id of the output feature type. This could be a column in a database, the automatically generated simple feature ID obtained with getId(), or some other expression.

sourceExpression (optional)¶

Use a sourceExpression tag to set the element content from source data. For example, to set the element content from a column called DESCRIPTION:

<sourceExpression><OCQL>DESCRIPTION</OCQL></sourceExpression>

If sourceExpression is not present, the generated element is empty (unless set by another mapping).

You can use CQL expressions to calculate the content of the element. This example concatenated strings from two columns and a literal:

<sourceExpression>
    <OCQL>strConCat(FIRST , strConCat(' followed by ', SECOND))</OCQL>
</sourceExpression>

You can also use CQL expressions for vocabulary translations. Read more about it in Vocabulary functions.

linkElement and linkField (optional)¶

The presence of linkElement and linkField change the meaning of sourceExpression to a Feature Chaining mapping, in which the source of the mapping is the feature of type linkElement with property linkField matching the expression. For example, the following sourceExpression uses as the result of the mapping the (possibly multivalued) gsml:MappedFeature for which gml:name[2] is equal to the value of URN for the source feature. This is in effect a foreign key relation:

<sourceExpression>
    <OCQL>URN</OCQL>
    <linkElement>gsml:MappedFeature</linkElement>
    <linkField>gml:name[2]</linkField>
</sourceExpression>

The feature type gsml:MappedFeature might be defined in another mapping file. The linkField can be FEATURE_LINK if you wish to relate the features by a property not exposed in XML. See Feature Chaining for a comprehensive discussion.

For special cases, linkElement could be an OCQL function, and linkField could be omitted. See Polymorphism for further information.

targetAttributeNode (optional)¶

targetAttributeNode is required wherever a property type contains an abstract element and app-schema cannot determine the type of the enclosed attribute. This mapping must come before the mapping for the enclosed elements. In this example, gsml:positionalAccuracy is a gsml:CGI_ValuePropertyType which contains a gsml:CGI_Value, which is abstract. In this case, targetAttributeNode must be used to set the type of the property type to a type that encloses a non-abstract element:

<AttributeMapping>
    <targetAttribute>gsml:positionalAccuracy</targetAttribute>
    <targetAttributeNode>gsml:CGI_TermValuePropertyType</targetAttributeNode>
</AttributeMapping>

Note that the GML encoding rules require that complex types are never the direct property of another complex type; they are always contained in a property type to ensure that their type is encoded in a surrounding element. Encoded GML is always type/property/type/property. This is also known as the GML “striping” rule. The consequence of this for app-schema mapping files is that targetAttributeNode must be applied to the property and the type must be set to the XSD property type, not to the type of the contained attribute (gsml:CGI_TermValuePropertyType not gsml:CGI_TermValueType).

Because the XPath refers to a property type not the encoded content, targetAttributeNode often appears in a mapping with targetAttribute and no other elements.

isMultiple (optional)¶

The isMultiple element states whether there might be multiple values for this attribute.Because the default value is false and it is omitted in this case, it is most usually seen as:

<isMultiple>true</isMultiple>

ClientProperty (optional, multivalued)¶

A mapping can have one or more ClientProperty elements which set XML attributes on the mapping target. Each ClientProperty has a name and a value that is an arbitrary CQL expression. No OCQL element is used inside value.

This example of a ClientProperty element sets the codeSpace XML attribute to the literal string urn:ietf:rfc:2141. Note the use of single quotes around the literal string. This could be applied to any target attribute of GML CodeType:

<ClientProperty>
    <name>codeSpace</name>
    <value>'urn:ietf:rfc:2141'</value>
</ClientProperty>

When the GML association pattern is used to encode a property by reference, the xlink:href attribute is set and the element is empty. This ClientProperty element sets the xlink:href XML attribute to to the value of the RELATED_FEATURE_URN field in the data source (for example, a column in an Oracle database table). This mapping could be applied to any property type, such a gml:FeaturePropertyType, or other type modelled on the GML association pattern:

<ClientProperty>
    <name>xlink:href</name>
    <value>RELATED_FEATURE_URN</value>
</ClientProperty>

See the discussion in Feature Chaining for the special case in which xlink:href is created for multivalued properties by reference.