Non-Standard Conversion Rules

Contents

Using the non-standard conversion rules

An encoding rule that wishes to make use of the conversion rules specified in this section must specify an Encoding Rule as part of the configuration and list the desired conversion rules.

Definitions

In addition to the standard definitions, the extended conversion rules use the following terms, too:

  • basic type: classifier with the stereotype <<BasicType>>
  • derived property: property that is marked in the UML model as isDerived.

More information about the stereotypes and the associated tagged values is available in the description of the UML profile supported by ShapeChange.

Other Extensions

This section describes configuration options of the input that affect the XML Schema output, but which are not conversion rules. These are treated separately as they are already processed during the initial parsing of the input model. Model elements that do not meet the selection criteria are not included in the internal model representation and are not available during the conversion to target representations.

Components with non-public visibility

By default, only model elements with public visibility are read from the model. However, this can be relaxed to include all model elements regardless of their visibility .

This is controlled by setting the publicOnly parameter of the configuration file’s <input> element to “true” or “false”.

 

Non-Standard Conversion Rules

rule-xsd-all-gml21

Instructs ShapeChange to generate schema based on GML version 2.1. The map entries and namespaces need to be configured accordingly. The encoding takes into account certain limitations of GML 2.1:

  • Because GML 2.1 does not specify object types (GML 3.1 and 3.2 make a distinction between feature and object types), feature as well as object type classes from the application schema will derive from gml21:_Feature (of type gml21:AbstractFeatureType). This ensures that object type classes are represented in the GML schema as types with identity.
  • Because GML 2.1 does not support a common base type for data types and unions, these types are not assigned to a special GML substitution group (in GML 3.1 gml:_Object would be used in this case).

rule-xsd-all-notEncoded

This conversion rule suppresses the conversion to XML Schema of any model elements for which the “xsdEncodingRule” tag is set to “notEncoded”.

NOTE: If Schematron output is active:

  • Constraints of a class that is NOT encoded will not be included in the Schematron schema
  • A constraint of a class that IS encoded will be included in the Schematron schema, even if model elements required by the constraint are not encoded

rule-xsd-all-no-documentation

Documentation for a model element is by default exported as part of <annotation> elements in the XML Schema Document. The export of the documentation can be suppressed using this conversion rule.

NOTE:

  • Prior to ShapeChange 2.1.0 this rule was only applied if the XmlSchema target included the parameter includeDocumentation with value ‘false’.
  • Since ShapeChange 2.1.0 the rule applies unless the XmlSchema target includes the parameter includeDocumentation with value ‘true’.

rule-xsd-all-tagged-values

Within an XSD <annotation>, <appinfo> elements may be used to pass information to specific applications.  ShapeChange allows selected tagged values to be mapped to <appinfo> elements of the corresponding model element.

Tagged values to be mapped in this way can be specified in the representTaggedValues parameter of the ShapeChange configuration file’s <input> element .

Example, where the “primaryCode” and “secondaryCode” tagged values were listed under representTaggedValues in the configuration file for this transformation:

<complexType name="PAA010Type">
  <annotation>
    <documentation>Mine: An excavation made in the earth for the purpose of extracting natural deposits.</documentation>
    <appinfo>
      <sc:taggedValue tag="primaryCode">Mine</sc:taggedValue>
      <sc:taggedValue tag="secondaryCode">PAA010</sc:taggedValue>
    </appinfo>
  </annotation>
  …
</complexType>

rule-xsd-cls-adeelement

For classes with stereotype <<ADEElement>>, this conversion rule creates global CityGML property elements substitutable for the relevant _GenericApplicationPropertyOfXXX element of the CityGML supertype.

rule-xsd-cls-basictype

Basic types may be restricted with facets. For example, the length of a subtype of CharacterString may be restricted through the use of the “length” tagged value, or the allowed range of numeric values may be limited through the use of the tagged values “rangeMinimum” and “rangeMaximum”.

rule-xsd-cls-codelist-anonymous-xlink

Properties of type codelist are represented in the GML schema as complex type with xlink simple attributes group. This is especially useful to encode such properties in GML 2.1 when codelist entries shall be referenced (note that GML 2.1 does not define a gml:CodeType or gml:ReferenceType).

rule-xsd-cls-codelist-constraints

If Schematron output is active (rule-xsd-pkg-schematron), additional constraints are added for code list values depending on several tagged values.

More information can be found in this OGC document (OWS-8 CCI Schema Automation Engineering Report).

rule-xsd-cls-codelist-constraints-codeAbsenceInModelAllowed

Some communities have the case where a code list does not contain any code value, but still OCL constraints exist in the application schema that refer to such code values. Usually, ShapeChange reports an error if such a situation occurs, and does not create the OCL expression. However, if this rule is enabled, code list values are not required to be present in the model.

rule-xsd-cls-codelist-gmlsf

(since v2.4.0)

Encodes a property with codelist value type as specified by the GML simple features profile (OGC document number 10-100r3), section 8.4.4.14.

NOTE: This rule has originally been developed during OGC Testbed 13, to derive an XML Schema that is compliant to GML-SF level 0. For further details, see the OGC NAS Profiling Engineering Report (OGC document number 17-020 – to be published).

rule-xsd-cls-enum-subtypes

This conversion rules includes also enumerants from subtypes in the enumeration type in XML Schema.

Note: This conversion rule is probably no longer in use and may be deleted.

rule-xsd-cls-enum-supertypes

This conversion rules includes also enumerants from supertypes in the enumeration type in XML Schema.

Note: This conversion rule is probably no longer in use and may be deleted.

rule-xsd-cls-local-basictype

Classes identified as basic types are by default converted to a named simpleType (for global scope). If this conversion rule is part of an encoding rule, these types are converted to an anonymous simpleType for local scope.

rule-xsd-cls-local-enumeration

<<enumeration>> and <<codeList>> classes are by-default converted to a named simpleType (for global scope). If this conversion rule is part of an encoding rule, these types are converted to an anonymous simpleType for local scope.

rule-xsd-cls-mixin-classes

Due to the fact that several implementation platforms including XML Schema support only single inheritance (type derivation from a single base type, element substitutablity in XML Schema is restricted to a single element, too), the use of multiple inheritance is currently not supported by GML 3.2 Annex E.

However, for conceptual modelling, the ability to define abstract types which capture a set of properties that are associated with a concept is sometimes very convenient.

More information…

rule-xsd-cls-mixin-classes-as-group

Extension to rule-xsd-cls-mixin-classes that converts mixin classes to groups and references the group from the suptypes.

rule-xsd-cls-mixin-classes-non-mixin-supertypes

Extension to rule-xsd-cls-mixin-classes that allows that supertypes of a mixin type is not a mixin type. Note that this has limitations in that the non-mixin supertype property type will not support taking subtypes of the mixin type as a value.

rule-xsd-cls-no-abstract-classes

Do not convert abstract classes to object elements and do not process their properties; create a property type with references to subtypes with object elements

rule-xsd-cls-no-base-class

Ignore base classes in the conversion process

rule-xsd-cls-no-gml-types

This conversion rule suppresses the use of the base types of GML (gml:AbstractObject, gml:AbstractGMLObject, gml:AbstractFeature, but also gml:AssociationGroup) either on a general or local scope.

rule-xsd-cls-okstra-fid

Supports OKSTRA <<FachID>> classes

rule-xsd-cls-okstra-lifecycle

Supports OKSTRA historisches_Objekt

rule-xsd-cls-okstra-schluesseltabelle

Do not convert OKSTRA <<Schluesseltabelle>> classes to object elements and do not process their properties; create a OKSTRA-specific property type

rule-xsd-cls-suppress

This conversion rule suppresses object elements, local properties and property types, if the class has a tagged value ‘suppress’ with the value ‘true’ or a stereotype <<ADEElement>>. However, if Schematron output is active, any constraints on the class will still be included in the Schematron schema.

rule-xsd-cls-union-asCharacterString

Do not convert union with a tagged value ‘gmlAsCharacterString’ set to ‘true’ in the usual way, but convert it as if it would be a CharacterString.

rule-xsd-cls-union-asGroup

If a <<Union>> class has a tagged value “gmlAsGroup” with a value of “true”, then the class is encoded as a global group which is referenced wherever a property is defined that has the union class as its value. (Note that this is only valid if it is clear from the context how to map the individual values to the conceptual model.)

rule-xsd-cls-union-direct

A union with two properties and where one property has a tagged value ‘implementedByNilReason’ set to ‘true’ is converted as follows under this conversion rule:

A property that has the union type as its value receives the value type of the property in the union that is not implementedByNilReason as its type.

The property element is made nillable and receives a nilReason attribute.

rule-xsd-cls-union-omitUnionsRepresentingFeatureTypeSets

(since v2.4.0)

A union with tagged value representsFeatureTypeSet = true is not encoded. Properties with such a union as type are encoded as elements with type gml:ReferenceType. If rule-xsd-prop-targetElement is enabled, an annotation is added with one gml:targetElement appinfo element for each feature type represented by the union.

NOTE: This rule has originally been developed during OGC Testbed 13, to derive an XML Schema that is compliant to GML-SF level 0. For further details, see the OGC NAS Profiling Engineering Report (OGC document number 17-020 – to be published).

rule-xsd-pkg-dgiwgsp

This conversion rule adds information to the XML Schema to indicate the DGIWG Spatial Profile (DGIWGSP) compliance level.

The following tagged values must be set for an application schema that is converted to XML Schema, if the DGIWGSP information is to be included:

Tagged Value Name Explanation
dgiwgComplianceLevel According to DGIWGSP specification one of: L1_2D, L2_2D, L3_2D, L4_2D, L5_2D, L6_2D, L1_3D, L2_3D, L3_3D,
L4_3D, L5_3D, L6_3D
dgiwgGMLProfileSchema http://schemas.dgiwg.org/gml/3.2/spatial/1.0/{X}, with {X} being one of: 2dGeometry.xsd,  3dGeometry.xsd,  2dComplex.xsd,  3dComplex.xsd, 2dTopology.xsd, 3dTopology.xsd

The resulting import and annotation in the XSD can look like this:

  <annotation>
    <appinfo source="">
      <ComplianceLevel xmlns="http://www.dgiwg.org/gml/3.2/profiles/spatial/1.0/">L1_3D</ComplianceLevel>
      <GMLProfileSchema xmlns="http://www.dgiwg.org/gml/3.2/profiles/spatial/1.0/">http://schemas.dgiwg.org/gml/3.2/spatial/1.0/3dGeometry.xsd</GMLProfileSchema>
    </appinfo>
  </annotation>
  <import namespace="http://www.dgiwg.org/gml/3.2/profiles/spatial/1.0/"/>

Note: currently the import only contains the namespace because there is no XML Schema at the schema location required by the DGIWG Spatial Profile specification. That is also why the source attribute on the annotation is empty. This behavior can be changed by setting the schema location at the according entry in the standard XML namespaces.

rule-xsd-pkg-gmlsf

(since v2.4.0)

Creates a schema annotation to indicate the GML-SF compliance level as defined by the GML simple features profile (OGC document number 10-100r3), section 7.4. The compliance level is read from tagged value gmlsfComplianceLevel on the application schema. Furthermore, the rule creates an import for the gmlsfLevels.xsd, as defined by GML-SF section 8.3.2.

NOTE: This rule has originally been developed during OGC Testbed 13, to derive an XML Schema that is compliant to GML-SF level 0. For further details, see the OGC NAS Profiling Engineering Report (OGC document number 17-020 – to be published).

rule-xsd-pkg-schematron

An application schema may contain OCL (Object Constraint Language) constraints related to the feature type or its attributes.  On the XML level, Schematron (ISO/IEC 19757-3:2006) is used in most cases to express constraints. Schematron is already used by GML to express constraints that cannot be represented in XML Schema, and is currently considered the most appropriate language to express constraints on the XML level. Tools exist to process Schematron constraints and assert the compliance of an instance document with the specified constraints, e.g. here.

ShapeChange includes a OCL 2.2 parser and Schematron code-generator, allowing for a fairly complete range of OCL expressions. The supported expressions are documented here.

The Schematron schema for an application schema is written in the same output directory as the XML Schema Document and with the same name, except that the file name ends in “_SchematronSchema.xml” instead of “.xsd”.

The conversion rule uses four additional target parameters:

Parameter Name Default Value Explanation
schematronExtension.matches.namespace <none> Namespace specification for XPath 2.0 extensions to Schematron to support the “matches” function; see here for details.
schematronExtension.matches.function <none> Function/pattern specification for XPath 2.0 extensions to Schematron to support the “matches” function; see here for details.
schematronXlinkHrefPrefix # Prefix of a Schematron “xlink:href” reference.
schematronXlinkHrefPostfix <blank> Postfix of a Schematron “xlink:href” reference.

rule-xsd-prop-att-map-entry

This conversion rule supports XsdMapEntry elements with attribute/attributeGroup mappings. This allows to reuse global attribute and attributeGroup schema components from existing XML grammars, e.g. IC-ISM.

rule-xsd-prop-constrainingFacets

(since v2.4.0)

Generate constraining facets based on tagged values length, maxLength, size, pattern, rangeMaximum, and rangeMinimum of a property:

  • The value of tag length, maxLength, or size (in descending order of priority) is used to populate facets totalDigits and maxLength.
  • Facet pattern is read from the according tagged value.
  • Facet maxInclusive is read from tagged value rangeMaximum.
  • Facet minInclusive is read from tagged value rangeMinimum.

NOTE: A facet is only created if the (base) type of the property supports it.

rule-xsd-prop-exclude-derived

By default, derived properties are included during the conversion. They can be suppressed using this conversion rule.

rule-xsd-prop-gmlArrayProperty

For properties with a tagged value ‘gmlArrayProperty’ set to ‘true’ and with complex content that is always inline, i.e. the property has the tagged value ‘inlineOrByReference’ set to ‘inline’, an array property is created instead of using the standard GML property types.

Examples:

An attribute “geometry : GM_Point [0..3]” is converted to:

<element name="geometry" minOccurs="0">
 <complexType>
  <sequence minOccurs="0" maxOccurs="3">
   <element ref="gml:Point"/>
  </sequence>
 </complexType>
</element>

An attribute “<<voidable>> event : Event [1..*]” is converted to:

<element name="event" nillable="true">
 <complexType>
  <sequence maxOccurs="unbounded">
   <element ref="app:Event"/>
  </sequence>
  <attribute name="nilReason" type="gml:NilReasonType"/>
 </complexType>
</element>

A navigable association role “role : Feature [1..*]” is converted to:

<element name="role">
 <complexType>
  <sequence maxOccurs="unbounded">
   <element ref="app:Feature"/>
  </sequence>
  <attributeGroup ref="gml:OwnershipAttributeGroup"/>
 </complexType>
</element>

Note that no OwnershipAttributeGroup is added for attributes as attributes are equivalent to compositions.

rule-xsd-prop-gmlListProperty

For properties with a tagged value ‘gmlListProperty’ set to ‘true’ and with a simple type as value, maxOccurs is suppressed and a list type is created.

Examples:

An attribute “string : CharacterString [1..*]” is converted to:

<element name="string">
 <simpleType>
  <list itemType="string"/>
 </simpleType>
</element>

An attribute “integer : Integer [0..3]” is converted to:

<element name="integer" minOccurs="0">
 <simpleType>
  <list itemType="integer"/>
 </simpleType>
</element>

If this property is also marked for conversion to an attribute (‘xsdAsAttribut’ set to ‘true’ and rule ‘rule-xsd-prop-xsdAsAttribute’ is active), the result is:

<attribute name="integer">
 <simpleType>
  <list itemType="integer"/>
 </simpleType>
</attribute>

rule-xsd-prop-featureType-gmlsf-byReference

(since v2.4.0)

Applies simple byReference encoding of properties with a feature type as value type. In other words, such properties are encoded as elements with type gml:ReferenceType.

NOTE: This rule has originally been developed during OGC Testbed 13, to derive an XML Schema that is compliant to GML-SF level 0. For further details, see the OGC NAS Profiling Engineering Report (OGC document number 17-020 – to be published).

rule-xsd-prop-initialValue

If an attribute has an initial value, it is converted to a default value in XML Schema. If the attribute carries the constraint “{frozen}”, too, the initial value is converted to a fixed element value in XML Schema.

rule-xsd-prop-length-size-pattern

CharacterString valued properties that carry the tagged values ‘length’, ‘size’ or ‘pattern’ are converted to anonymous types with restricting facets according to the tagged values.

rule-xsd-prop-metadata-gmlsf-byReference

(since v2.4.0)

Applies simple byReference encoding of properties with metadata as value type (determined by tagged value isMetadata on the property, and map entries in the ShapeChange configuration). In other words, such properties are encoded as elements with type gml:ReferenceType.

NOTE: This rule has originally been developed during OGC Testbed 13, to derive an XML Schema that is compliant to GML-SF level 0. For further details, see the OGC NAS Profiling Engineering Report (OGC document number 17-020 – to be published).

rule-xsd-prop-nillable

Converts properties with stereotype <<voidable>> – or alternatively with a tagged value nillable set to ‘true’ – to property elements that are nillable.

In GML this implies that xsi:nil is set to ‘true’ and a nilReason attribute is added to the content model of the property element.

In ISO/TS 19139, the property element may have no element content and the content model has a gco:nilReason attribute.

rule-xsd-prop-nilReasonAllowed

Extension: nillable, nilReasonAllowed and implementedByNilReason

If an attribute has a tagged value “nillable” with value “true”, the property element will be defined with its nillable attribute set to “true”.

If a type has a tagged value “nilReasonAllowed” with value “true”, all property types for this property will be defined with an optional nilReason attribute.

If a property of the conceptual model is implemented by the nilReason concept of GML, the tagged value “implementedByNilReason” is set.

Note that there is considerable overlap with rule-xsd-prop-nillable. This should be cleaned up in a future version.

rule-xsd-prop-qualified-associations

For associations with qualifiers, the qualifiers are converted to XML attributes of the reverse property element. The multiplicity is set to minOccurs=”0″ and maxOccurs=”unbounded”. Qualifiers with types that map to simple types use the type directly. Qualifiers with types that map to types with identity use xs:anyUri. In all other cases xs:string will be used as a fallback.

Examples:

An association role “role1” (multiplicity “1”, by-reference encoding) with a single qualifier “q : Integer” in the reverse role is converted to:

<element maxOccurs="unbounded" minOccurs="0" name="role1">
 <complexType>
  <simpleContent>
   <extension base="gml:ReferenceType">
    <attribute name="q" type="integer"/>
   </extension>
  </simpleContent>
 </complexType>
</element>

An association role “role2” (multiplicity “0..1”, inline encoding) with the qualifiers “q1 : CharacterString; q2: SomeObject” in the reverse role is converted to (Parcel is a feature type):

<element maxOccurs="unbounded" minOccurs="0" name="role2">
  <complexType>
   <sequence>
    <element ref="app:SomeFeature"/>
   </sequence>
   <attribute name="q1" type="string"/>
   <attribute name="q2" type="anyUri"/>
  <complexType>
</element>

rule-xsd-prop-targetCodeListURI

(since v2.4.0)

For a property with a code list as value type, and the code list has non-empty tagged value codeList (or vocabulary), add an sc:targetCodeListURI appinfo element with the value of the according tag.

rule-xsd-prop-xsdAsAttribute

If the tagged value ‘xsdAsAttribute’ is set to ‘true’ on a property, the property has a maximum multiplicity of 1 and the value of the property is simple, the property is converted to an XML attribute instead of an XML element.

 

Top