XML Schema

Encoding Rules

The main functionality of ShapeChange is to generate XML Schema representations of application schemas, encoded as a set of XML Schema documents (XSDs). The conversion rules from UML to XML Schema are based on the encoding rules specified in Annex E of the GML 3.2 standard, in the GML 3.3 standard and ISO/TS 19139:2007 — as well as a series of extensions to the standardized rules.  These encoding rules are based on the general idea that the classifiers in the application schema are mapped to type and element declarations in XML Schema, so that the objects in the instance model can be mapped to corresponding element structures in the XML document. Different use cases result in different encoding rules. Currently, the geographic information standards specify the following XML-based encoding rules:

  • GML 3.2 Annex E specifies a XML-based encoding rule for ISO 19109 conformant application schemas that can be represented using a restricted profile of UML that allows for a conversion to XML Schema. The encoding rule has mainly been developed for the purpose of application schemas specifying feature types and their properties. GML 3.2 is also published as ISO 19136:2007. More information…
  • GML 3.3 specifies two extensions to the GML 3.2 encoding rules related to the encoding of code-list-valued properties and to support association classes. More information…
  • SWE Common Data Model 2.0 specifies a variation of the GML encoding rule for schemas that describe data in the context of measurements by sensors.
  • ISO/TS 19139 specifies a XML based encoding rule for conceptual schemas specifying types that describe geographic resources, e.g. metadata according to ISO 19115 and feature catalogues according to ISO 19110. The encoding rule supports the UML profile as used in the UML models commonly used in the standards developed by ISO/TC 211. More information…

The reader is directed to the GML 3.2, GML 3.3, SWE Common Data Model 2.0 and ISO/TS 19139 standards for further details of the encoding rules therein. In addition, ShapeChange supports a number of extensions to these encoding rules.

Specifying Encoding Rules

The range of possible encoding rules for the ShapeChange XML Schema conversion is represented by the following enumeration of text abbreviations:

Encoding Rule Identifier Description
iso19136_2007 The GML 3.2 (ISO 19136:2007) Annex E encoding rule. If not encoding rule is specified, this is the default encoding rule.
gml33 The GML 3.2 (ISO 19136:2007) Annex E encoding rule with the GML 3.3 extensions.
iso19139_2007 The ISO/TS 19139 encoding rule.
ogcSweCommon2 The SWE Common Data Model 2.0 encoding rule.

These standardized encoding rules are fixed as part of the Java code of ShapeChange. The standardized encoding rules build on a common set of schema conversion rules. While the GML 3.2 and GML 3.3 encoding rules have been specified in the context of these specific versions of GML, the encoding rules can also be applied with a target version of GML 2.1 or GML 3.1. The extensions can be aggregated into a new encoding rule as part of the configuration. Some examples of commonly used encoding rules are part of  StandardRules.xml that may be included in configuration files. These are:

Encoding Rule Identifier Description
iso19136_2007_INSPIRE_Extensions The GML 3.3 encoding rule with extensions related to INSPIRE, the Infrastructure for Spatial Information in the European Community. The encoding rule is described in INSPIRE document D2.7.
iso19136_2007_ShapeChange_1.0_Extensions The GML 3.2 encoding rule with a large number of the extensions implemented by ShapeChange.
notEncoded The model element is not encoded in the XML Schema.
gml21 Encoding rule that extends the ISO 19136:2007 encoding rules with additional rules to create a GML schema based on GML 2.1.
okstra The GML-3.2-based encoding rule used for the OKSTRA GML application schema. This includes support for an extended UML profile. OKSTRA is a feature catalogue and application schema for road and traffic related data. More information can be found on the OKSTRA website.
citygml-ade The GML-3.2-based encoding rule that can be used for CityGML Application Domain Extensions (ADEs) using GML 3.1. This includes support for an extended UML profile. It is planned to add support for ADEs in UML in the next version of CityGML. More information will be added as it becomes available.
metadata-profiles An ISO/TS-19139-based encoding rule for specifying ISO 19115 profiles in UML. More information will be added later.

Custom encoding rules may be specified in a configuration.

The encoding rule to apply in a conversion may be provided in two ways: as a conversion-wide default (specified in the configuration file), or as tagged values on individual model elements to control the conversion of those elements to XML Schema.

  • Model-Element-Specific Encoding Rule: To identify the applicable encoding rule for a model element (package, classifier or property), a tagged valuexsdEncodingRule” may be provided on that element.
  • Default Encoding Rule: In addition to model-element-specific encoding rules, it is common (indeed, desirable) to specify a default encoding rule.  The defaultEncodingRule” parameter specified in the <TargetXmlSchema> element of the ShapeChange configuration file represents the default encoding rule for that target/conversion.  This default is overridden by individual “xsdEncodingRule” tags on packages, classifiers and properties.

The valid values for “defaultEncodingRule” and “xsdEncodingRule” are the built-in encoding rule identifiers, the encoding rule identifiers specified in  StandardRules.xml or a custom encoding rule identifier specified in the configuration. The default, if no default encoding rule is provided in the configuration, is “iso19136_2007”.

Configuration

Overview

The XML Schema target in ShapeChange, as the main and most configurable target, is the only one to be represented by a unique target element: <TargetXmlSchema>.  This is a variant of a standard <Target> element except that the class attribute is fixed to de.interactive_instruments.ShapeChange.Target.XmlSchema.XmlSchema.  Like all target definitions, <TargetXmlSchema> is nested under the <targets> element.

The following is a sample <TargetXmlSchema> definition:

<TargetXmlSchema class="de.interactive_instruments.ShapeChange.Target.XmlSchema.XmlSchema" mode="enabled">
  <targetParameter name="outputDirectory" value="testResults/xmi"/>
  <targetParameter name="sortedOutput" value="true"/>
  <targetParameter name="defaultEncodingRule" value="iso19136_2007"/>
  <xi:include href="src/main/resources/config/StandardRules.xml"/>
  <xi:include href="src/main/resources/config/StandardNamespaces.xml"/>
  <xi:include href="src/main/resources/config/StandardMapEntries.xml"/>
  <xsdMapEntries>
    <XsdMapEntry type="URI" xsdEncodingRules="iso19136_2007" xmlPropertyType="anyURI" xmlType="anyURI" xmlTypeType="simple" xmlTypeContent="simple"/>
  </xsdMapEntries>
</TargetXmlSchema>

A <TargetXmlSchema> entry may contain:

  • <targetParameter> definitions;
  • one or more <rules> elements containing <EncodingRule> definitions;
  • one or more <xmlNamespaces> element containing <XmlNamespace> definitions;
  • one or more <xsdMapEntries> element containing <XsdMapEntry> definitions;
  • XInclude directives.

Target Parameters

The general <targetParameter> definitions for <TargetXmlSchema> are as follows. Additional parameters are specified by some conversion rules and are documented in the description of these extensions.

Parameter Name Default Value Explanation
defaultEncodingRule iso19136_2007 The identifier of the default encoding rule governing the conversion into XML Schema. This default value may be overridden by tagged values set on individual modeling elements. For a fuller discussion of GML encoding rules, see above.
documentationTemplate [[definition]] The template for the documentation that is added to XML Schema elements. Each occurrence of “[[descriptor]]” will be replaced by the value of the descriptor, or the value of the target parameter documentationNoValue, if the descriptor has no value for the model element. See here for more information about descriptors.

Example:

Definition: [[definition]] - Description: [[description]]
documentationNoValue the empty string If a descriptor is used in the documentation template, but has no value, the value of this parameter will be used. See here for more information about descriptors.
outputDirectory <the current run directory> The path to which the XML Schema documents will be written.
sortedOutput false A Boolean; if “true”, classes within a package will be sorted alphabetically before being output to the XSD (this aids in comparison with other models).

Encoding Rules

An <EncodingRule> element defines an encoding rule.

Example:

<EncodingRule name="iso19136_2007_INSPIRE_Extensions" extends="gml33">
 <rule name="req-all-all-documentation"/>
 <rule name="req-xsd-cls-codelist-asDictionary-true"/>
 <rule name="req-xsd-prop-codelist-obligation"/>
 <rule name="req-xsd-cls-codelist-extensibility-values"/>
 <rule name="req-xsd-cls-codelist-extensibility-vocabulary"/>
 <rule name="req-xsd-cls-datatype-noPropertyType"/>
 <rule name="req-xsd-cls-objecttype-noPropertyType"/>
 <rule name="req-xsd-cls-objecttype-byValuePropertyType"/>
 <rule name="req-xsd-cls-enum-no-supertypes"/>
 <rule name="req-xsd-cls-codelist-no-supertypes"/>
 <rule name="rule-xsd-cls-mixin-classes"/>
 <rule name="rule-xsd-prop-nillable"/>
</EncodingRule>

The name attribute of the <EncodingRule> element defines the identifier of the encoding rule to be used in the defaultEncodingRule parameter or xsdEncodingRule tagged values.

The optional extends attribute of the <EncodingRule> element includes all rules from the referenced encoding rule in this encoding rule, too. In the example, the INSPIRE encoding rules extends the GML 3.3 encoding rule.

Each <rule> references either a requirement or recommendation to be tested during the validation before the schema conversion process or a conversion rule. The implemented conversion rules are documented on the subpages to this page, for use in encoding rules defined in configurations the non-standard conversion rules are the most relevant ones.

 

Namespace Identifiers

An <XmlNamespace> element defines a namespace and its properties.

Examples:

<xmlNamespaces>
 <XmlNamespace nsabr="icism" ns="urn:us:gov:ic:ism:v2" location="http://schemas.opengis.net/ic/2.1/IC-ISM-v2.1.xsd"/>
</xmlNamespaces>

The attributes for <XmlNamespace> are as follows:

Attribute Name Default Value Explanation
ns (Required) The full namespace.
nsabr (Required) The namespace abbreviation.
location (Optional) The location of the corresponding XML Schema document.
packageName The package name.

The file StandardNamespaces.xml contains a series of standard namespace definitions, and is included by default (via XInclude) in configuration files. Alternative versions exist for GML 3.1 (StandardNamespaces-v31.xml) and GML 2.1 (StandardNamespaces-v21.xml).

 

XSD Map Entries

<xsdMapEntries> may contain individual <XsdMapEntry> elements, which represent additional mappings from UML types (classes) to GML elements, types and attributes (compare with Table D.2 of GML 3.2).  The definition of an <XsdMapEntry> is a narrowing of the <MapEntry> concept.

Examples:

<xsdMapEntries>
 <XsdMapEntry type="URN" xsdEncodingRules="*" xmlPropertyType="anyURI" xmlType="anyURI" xmlTypeType="simple" xmlTypeContent="simple"/>
 <XsdMapEntry type="URI" xsdEncodingRules="*" xmlPropertyType="anyURI" xmlType="anyURI" xmlTypeType="simple" xmlTypeContent="simple"/>
 <XsdMapEntry type="URL" xsdEncodingRules="*" xmlPropertyType="anyURI" xmlType="anyURI" xmlTypeType="simple" xmlTypeContent="simple"/>
 <XsdMapEntry type="CharacterString" xsdEncodingRules="iso19139_2007" xmlElement="gco:CharacterString" xmlPropertyType="gco:CharacterString_PropertyType" xmlType="gco:CharacterString_Type"/>
 <XsdMapEntry type="SecurityAttributesGroupType" xsdEncodingRules="iso19136_2007 iso19136_2007_ShapeChange_1.0_Extensions iso19136_2007_INSPIRE_Extensions" xmlAttributeGroup="icism:SecurityAttributesOptionGroup"/>
</xsdMapEntries>

An <XsdMapEntry> element contains the following attributes:

Attribute Name Default Value Explanation
type (Required) The UML class name of the type.
xsdEncodingRules (Required) The XSD encoding rules to which this mapping applies.  May be “*” or a space-delimited sequence of encoding rule abbreviations. “*” indicates that the mapping applies to all encoding rules.
xmlElement (no XML element represents the UML class) The global XML element that corresponds to the UML class.
xmlType (no XML type represents the UML class) The global XML type that represents the XML content model of the UML class.
xmlPropertyType (no XML type represents the property type for the UML class)

The type name of the XML Schema type to be used in a property element if the value of the property is the UML class.

If no pre-defined property type exists and xmlElement has been provided then a value of “_P_” will result in the use of an anonymous complex type as property type. A value of “_MP_”  will result in the use of an anonymous complex type as property type that extends gml:AbstractMetadataPropertyType.

xmlTypeType complex Identifies, if the xmlType is “simple” or “complex”.
xmlTypeContent complex Identifies, if the content of the xmlType is “simple” or “complex”.
xmlTypeNilReason true Identifies, if the xmlPropertyType contains a nilReason attribute in its content model.
xmlAttribute (no XML attribute represents the UML class) The global XML attribute that corresponds to the UML class. This requires that the conversion rule extension “rule-xsd-prop-att-map-entry” is part of the encoding rule.
xmlAttributeGroup (no XML attribute group represents the UML class) The global XML attribute group that corresponds to the UML class. This requires that the conversion rule extension “rule-xsd-prop-att-map-entry” is part of the encoding rule.

The file “StandardMapEntries.xml” defines the complete mapping of large sections of the ISO 19100 model and OGC standards into corresponding GML (3.2) elements, and is included in ShapeChange configuration files by default (via XInclude).  It should not be changed. Additional XInclude files, or individual <XsdMapEntry> elements added to the <xsdMapEntries> section of the configuration file, may be used to customize the map entries to support additional pre-defined conceptual UML classes, encoding rules, and existing XML grammars.

If using a version of GML other than 3.2, the mappings in StandardMapEntries.xml may not apply and the map entries will have to be configured as part of the configuration.