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:

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:

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 value “xsdEncodingRule” 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

basicTypeStyle

Type: String

Default Value: none

Explanation: If the value of this target parameter is equal to (ignoring case) “local” then rule-xsd-cls-local-basictype applies to the encoding rule of a given model element, even if that conversion rule is not part of that encoding rule.

NOTE: In general, it is recommended to add the conversion rule to the relevant encoding rule(s), rather than using this parameter.

Applies to Rule(s): none – general behaviour

defaultCodeListRepresentation

(since v2.6.0)

Type: String

Default Value: none

Explanation: This parameter can be used to provide a global default in case that, for a given code list, the tagged value codeListRepresentation is undefined or does not have a value, and a Schematron Schema with constraints to check code list typed properties shall be created as defined by rule-xsd-cls-codelist-constraints2.

Code list representations include:

• application/gml+xml;version=3.2 – A GML 3.2 dictionary (gml:Dictionary).
• application/x.iso19139+xml – An ISO 19139:2007 dictionary (gmx:CodeListDictionary or gmx:ML_CodeListDictionary).
  • NOTE: application/x.iso19139+xml is a preliminary identifier. It uses the unregistered x. Tree as defined by IETF RFC 6838 – Media Type Specifications and Registration Procedures.

One example where this parameter can be useful is the case of a metadata profile, where code lists are typically encoded as ISO 19139:2007 code list dictionaries. Then application/x.iso19139+xml could be configured as default code list representation, instead of modeling it on each code list.

Applies to Rule(s): rule-xsd-cls-codelist-constraints2

defaultCodeListValuePattern

(since v2.6.0)

Type: String

Default Value: none

Explanation: When an OCL constraint compares a code value (either as a literal value, or as an attribute access), then the pattern in which such values shall be encoded for a given code list is important. That pattern can be defined with tagged value codeListValuePattern on each code list. More information can be found in the OWS-8 CCI Schema Automation Engineering Report. This parameter can be used to configure a global default for the pattern.

One example where this would be useful is the case of a metadata profile, which is encoded according to ISO 19139:2007, and only depends on similarly encoded base schemas (like ISO 19115). Then {value} could be configured as default pattern, instead of modeling it on each code list – especially the code lists from the base schemas.

Applies to Rule(s): rule-xsd-pkg-schematron

defaultEncodingRule

Type: String

Default Value: iso19136_2007

Explanation: 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 complete discussion of GML encoding rules, see above.

Applies to Rule(s): none – general behaviour

defaultVoidReasonType

(since v2.9.0)

Type: String

Default Value: none

Explanation: Identifies an enumeration that shall be used as the default void reason type in rule-xsd-prop-nilReason-constraints.

The enumeration is identified by its name: the simple classifier name, if the enumeration belongs to the schema that is being processed by the XmlSchema target, or the full package-qualified name, starting with the package of the schema to which the enumeration belongs (e.g. “Some Application Schema::Some Subpackage::Another Subpackage::VoidReason”).

NOTE: If the enumeration is used as void reason type by multiple schemas, it is better to identify it using its full package-qualified name via the defaultVoidReasonType target parameter.

Applies to Rule(s): rule-xsd-prop-nilReason-constraints

documentationNoValue

Type: String

Default Value: the empty string

Explanation: 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.

Applies to Rule(s): none – general behaviour

documentationTemplate

Type: String

Default Value: [[definition]]

Explanation: 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]]

Applies to Rule(s): none – general behaviour

enumStyle

Type: String

Default Value: none

Explanation: If the value of this target parameter is equal to (ignoring case) “local” then rule-xsd-cls-local-enumeration applies to the encoding rule of a given model element, even if that conversion rule is not part of that encoding rule.

NOTE: In general, it is recommended to add the conversion rule to the relevant encoding rule(s), rather than using this parameter.

Applies to Rule(s): none – general behaviour

includeDerivedProperties

Type: Boolean

Default Value: none

Explanation:

If the value of this target parameter is equal to (ignoring case) “false” then rule-xsd-prop-exclude-derived applies to the encoding rule of a given model element, even if that conversion rule is not part of that encoding rule.

NOTE: In general, it is recommended to add the conversion rule to the relevant encoding rule(s), rather than using this parameter.

Applies to Rule(s): none – general behaviour

includeDocumentation

Type: Boolean

Default Value: none

Explanation: If the value of target parameter includeDocumentation is equal to (ignoring case) “true” then rule-xsd-all-no-documentation will be ignored.

Applies to Rule(s): rule-xsd-all-no-documentation

outputDirectory

Type: String

Default Value: <the current run directory>

Explanation: The path to which the XML Schema documents will be written.

Applies to Rule(s): none – general behaviour

realisationLikeGeneralisation

Type: Boolean

Default Value: none

Explanation: By default, the XmlSchema target treats a realization relationship to a mixin type as a generalization relationship to that type. If this target parameter is set to “false” (ignoring case) then realization relationships will completely be ignored.

NOTE: Realization relationships to class categories other than mixins are always ignored.

Applies to Rule(s): none – general behaviour

schematron

Type: Boolean

Default Value: none

Explanation: If the value of this target parameter is equal to (ignoring case) “true” then rule-xsd-pkg-schematron applies to the encoding rule of a given model element, even if that conversion rule is not part of that encoding rule.

NOTE: In general, it is recommended to add the conversion rule to the relevant encoding rule(s), rather than using this parameter.

Applies to Rule(s): none – general behaviour

schematronFileNameTemplate

(since v2.6.0)

Type: String

Default Value: [[SCHEMA_XSD_BASENAME]].xsd_SchematronSchema.xml

Explanation: The template for the name of schematron files generated by the target. Each occurrence of “[[SCHEMA_XSD_BASENAME]]” will be replaced by the base name of the XSD file that belongs to the schema for which a schematron file is generated.

For example, if the application schema has tagged value xsdDocument=example.xsd, and parameter schematronFileNameTemplate has value [[SCHEMA_XSD_BASENAME]]_SchematronSchema.sch, then the name of the schematron file for the application schema would be example_SchematronSchema.sch.

Applies to Rule(s): rule-xsd-pkg-schematron

schematronXlinkHrefPrefix

Type: String

Default Value: #

Explanation: Prefix to be used when constructing a concat( ) operation for testing the value of an @id or @gml:id attribute against the value of an @xlink:href.

Applies to Rule(s): rule-xsd-pkg-schematron

schematronXlinkHrefPostfix

Type: String

Default Value: the empty string

Explanation: Postfix to be used when constructing a concat( ) operation for testing the value of an @id or @gml:id attribute against the value of an @xlink:href.

Applies to Rule(s): rule-xsd-pkg-schematron

segmentSchematron

(since v2.10.0)

Type: Boolean

Default Value: false

Explanation: If set to ‘true’, Schematron assertions are segregated into multiple Schematron files – one per XML Schema document created for the application schema (which is typically controlled by setting the tagged value xsdDocument on the packages of the application schema). If such a Schematron schema would contain no assertions, i.e. it would not check anything, it should not be created.

Applies to Rule(s): rule-xsd-pkg-schematron

skipXmlSchemaOutput

(since v2.6.0)

Type: Boolean

Default Value: false

Explanation: If set to ‘true’, the target does not output XML Schemas. That can be useful if only the Schematron schema is of interest.

Applies to Rule(s): none – general behaviour

sortedOutput

Type: Boolean (true or false)

Default Value: false

Explanation: If “true”, classes within a package will be sorted alphabetically before being output to the XSD (this aids in comparison with other models).

Applies to Rule(s): none – general behaviour

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:

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).

NOTE (relevant for ShapeChange v2.10.0 and later): ShapeChange automatically creates XML Schema imports and includes. By default, it does not import XML Schemas that are not directly used by the GML application schema that is produced by the XmlSchema target. In some use cases, however, it can be useful to enforce certain XML Schema imports in the GML application schema. An example would be where the GML application schema imports the XML Schema (B) of an abstract type (e.g. a metadata type), but the imported XML Schema (B) does not define any non-abstract implementation of that type. In such a situation, the application schema designer may want to enforce imports of additional XML Schemas (C, D, …) that define non-abstract implementations of the abstract type. Then an XML instance document that defines the GML application schema in its xsi:schemaLocation attribute will be able to validate the non-abstract definitions of the abstract type from XML Schema B, without having to add the namespaces and locations of XML Schemas C, D, etc. to the xsi:schemaLocation attribute (which can easily be forgotten). In order to enforce the import of another XML Schema, set tagged value xsdForcedImports on the (application) schema package. The value is a comma-separated list of XML namespace abbreviations (as configured in the XmlSchema target using <XmlNamespace> elements) that identify the XML Schemas that shall be imported.

XSD Map Entries

<xsdMapEntries> contain <XsdMapEntry> and <XsdPropertyMapEntry> elements, which map UML types (classes) as well as UML properties (attributes and association roles) to corresponding XML Schema elements, types and attributes.

NOTE:
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 typically in-cluded in ShapeChange configuration files via XInclude. It should not be changed. Additional XInclude files, or individual <XsdMapEntry> and <XsdPropertyMapEntry> 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.

XsdMapEntry

An <XsdMapEntry> element represents a mapping from a UML type (class) to a GML element, type, or attribute (compare with Table D.2 of GML 3.2).

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>

XsdPropertyMapEntry

(since v2.7.0)

<xsdMapEntries> may also contain <XsdPropertyMapEntry> elements, which represent mappings from UML properties (attributes and association roles) to XML elements defined in external XML Schemas.

NOTE: XsdPropertyMapEntry does not apply to enums and codes.

If an XsdPropertyMapEntry provides a mapping to an XML Schema element for a UML property from the processed schema, then the UML property is not encoded. Instead, whenever the UML property is used in the schema, the target element specified by the map entry is used in the XML Schema implementation. By not providing a target element, an XsdPropertyMapEntry can also be used to fully omit the conversion of a UML property.

Examples:

<xsdMapEntries>
 <!-- Omit 'identifier' from MyFeatureType in Test Schema1 -->
 <XsdPropertyMapEntry property="MyFeatureType::identifier" schema="Test Schema1"/>
 <!-- Map other occurrences of 'identifier' to dcterms:identifier - but only in Test Schema1. -->
 <XsdPropertyMapEntry property="identifier" schema="Test Schema1" targetElement="dcterms:identifier"/>
 <!-- Map occurrences of 'creator' to dcterms:creator - in any schema selected for processing. -->
 <XsdPropertyMapEntry property="creator" targetElement="dcterms:creator"/>
 <XsdPropertyMapEntry property="date" schema="Test Schema1" targetElement="dcterms:date"/>
 <XsdPropertyMapEntry property="format" schema="Test Schema1" targetElement="dcterms:format"/>
 <XsdPropertyMapEntry property="title" schema="Test Schema1" targetElement="dcterms:title"/>
 <XsdMapEntry type="URI" xsdEncodingRules="iso19136_2007 gml33" xmlPropertyType="anyURI"
  xmlType="anyURI" xmlTypeType="simple" xmlTypeContent="simple"/>
</xsdMapEntries>
<xmlNamespaces>
 <XmlNamespace nsabr="dcterms" ns="http://purl.org/dc/terms/" location="http://dublincore.org/schemas/xmls/qdc/2008/02/11/dcterms.xsd"/>
</xmlNamespaces>

An <XsdPropertyMapEntry> element contains the following attributes:

NOTE: The configuration may contain multiple XsdPropertyMapEntry elements that apply to a UML property P. When mapping the UML property, the applicable map entry is looked up as follows:

• If a map entry has the same combination of class name, property name, and schema then that map entry is chosen (because it is most specific for P).
• Otherwise, if a map entry has the same property name and schema, but the property name is not scoped to a specific class (example: att4) then that map entry is chosen (because it provides a generic mapping for the property that is specific to its schema).
• Otherwise, if a map entry does not define any schema, but has the same combination of class name and property name, then it is chosen (because it is a slightly more specific mapping for P compared to the generic mapping).
• Otherwise, if a map entry does not define any schema, but has the same property name and is not scoped to a specific class, then it is chosen (because it is a generic mapping for P).

NOTE: Using an XsdPropertyMapEntry to map a UML property to an XML element from another XML Schema can result in an invalid Schematron implementation of OCL constraints in which the UML property occurs. The most prominent example of why the Schematron would be invalid is if the type of the XML element is incompatible with the type of the UML property. If the UML property has a type like CharacterString, which is typically mapped to xs:string, and the XML element has a different simple type, like xs:boolean, or has a complex type, then that would clearly be a type mismatch. If an OCL constraint contains a comparison involving the UML property then with mismatching types of the UML property and the XML element to which it is mapped, the comparison in the resulting Schematron assertion would be invalid or non-sensical. Another example of a type mismatch resulting in invalid Schematron is if the UML property occurs in an OCL constraint as an intermediate navigation step, and the XML element to which the UML property is mapped does not have child elements similar to what would result when converting the value type of the UML property to XML Schema. If the structure is different then navigation steps within the OCL constraint that follow the navigation step of the UML property would never succeed. Using an XsdPropertyMapEntry to omit encoding of a UML property altogether woud be another, obvious example for a situation in which the Schematron conversion of an OCL constraint that uses that property is not possible.