LEVEL 3 USER
This section of the DATEX II document portal describes the basic methodology underlying the DATEX II content model. It is aiming at those readers that intend to start modelling themselves in DATEX II (e.g. to create a DATEX II extension) and who need to understand the basic rules that govern DATEX II content models. Readers of the sections addressing the Platform Independent Model should be familiar with the Unified Modelling Language UML. Readers also aiming to read and understand the XML schema encoding also need a good understanding of the XML Schema Definition standard.
The following documents, in whole or in part, are normatively referenced in this specification and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ISO/IEC 19505-1:2012, Information technology — Object Management Group Unified Modeling Language (OMG UML) — Part 1: Infrastructure
ISO/IEC 19508:2014, Information technology – Object Management Group Meta Object Facility (MOF) Core
ISO/IEC 14977:1996, Information technology — Syntactic metalanguage — Extended BNF
For the purposes of this specification, the following terms and definitions apply.
Terms and definitions adapted from ISO/IEC 19505-1:2012
Note
Definitions have been adapted to meet the particular use of UML within this specification.
Note
This characteristic is expressed in UML with an attribute named “isComposite” on the part end of the Association being set to “true”.
Note
The upper bound of the range cannot be below the lower bound. The lower bound must be a nonnegative integer. The upper bound must be a nonnegative integer or the special value unlimited, which indicates there is no upper bound on the range.
Note
The term profile within the term UML profile has a different meaning than the term profile defined in the definition of the term “Profile”.
Other terms and definitions
For the purposes of this specification, the following terms and definitions apply.
Note
Lower Camel Case describes the case where the initial letter is lower case, e.g. as in lowerCamelCase.
Note
Concrete implementations can be derived from the platform independent model by platform specific models or mappings.
Note
The “PayloadPublication” class is the top level root class for DATEX II Level A.
Note
Upper Camel Case describes the case where the initial is upper case, e.g. as in UpperCamelCase.
Note
Although developed for documents, it is today widely used for data exchange in general, usually in conjunction with an XML Schema Definition.
Note
It is today most commonly used to exchange UML models between UML tools. XMI is specified in ISO/IEC 19508:2014.
Note
XML Schema Definitions allow for formal validation of syntactical compliance of instance documents.
Symbols and abbreviations
GUID | Globally Unique identifier |
PIM | Platform Independent Model |
UCC | Upper Camel Case |
UML | Unified Modeling Language |
W3C | Unified Modeling Language |
The DATEX II data modelling methodology uses the Unified Modelling Language (UML), version 2 as specified in ISO/IEC 19505-1:2012. More accurately the release 2.4.1 of UML 2 is used.
UML provides a vast set of modelling elements that are not all used for DATEX II data modelling. In fact, DATEX II uses a fairly small UML profile, based on the following metaclasses from the Core::Basic and Core:Constructs packages specified in ISO/IEC 19505-1:2012:
DATEX II specifies metadata for the metaclasses in a UML profile with stereotypes which are assigned to the metaclasses, as listed above.
Simple types that may be assigned to attributes are defined as datatypes or enumerations.
Complex types (data structures) are defined as classes, with potential substructures connected via a composition.
Generalization between classes is allowed, but multiple inheritance is prohibited, i.e. each class shall have either zero or one superclass.
Classes, datatypes and enumerations may be structured in namespace packages, which define a namespace for their contained classes, datatypes, enumerations and sub-packages. They may also be structured simply in packages, which have no further semantics in DATEX II, they simply serve to structure DATEX II models and make them more accessible.
Namespaces, classes and datatypes also have an option to refer to an external namespace, class or datatype. The stereotypes defined for this purpose contain only the metadata required to refer to the external entity. The specification of such external model elements is entirely out of the scope of this specification.
Further to that, additional properties have been defined in this section to govern the platform specific mapping to XML schema definitions. Other property sets may be added to generate an alternative platform specific model. Models that claim to comply with this specification may use these UML elements but shall comply with all provisions regarding the use of these elements.
For readers not familiar with using UML or its graphical notations there is plenty of introductory material available to learn about UML in general and we would like to refer the reader to these resources for further study (e.g. to [1] or [2]). It should be noted that this specification uses only the default graphical representation of all UML elements used.
Note that no provisions are made regarding the existence and use of other UML elements. Thus, compliant models may use these other elements, but they have no defined semantics in the framework of DATEX II.
The stereotypes of the DATEX II UML profile related to the platform independent model have defined properties which are used in subsequent sections to specify metamodel aspects. The allocation of which properties are used by which stereotypes is depicted in the diagrams in section Platform independent model rules. Further to that, additional properties have been defined to govern the platform specific mapping to XML schema definitions. Note that the following list of properties constitutes the list of properties governed by this specification. Other properties may exist but are not governed by this specification and have no semantics in the DATEX II specifications.
Properties for the Platform Independent Model are:
Properties for the Platform Specific Model are:
All names used in DATEX II UML models shall comply with the following rule set.
The following UML constructs used in this specification may have a name that is used by the DATEX II metamodel: Attribute, Class, DataType, Enumeration, Package, Property. This name is specified via a “name” metaattribute from that metaclass. If such a name metaattribute is provided, it shall begin with a letter, followed by none or more letters or digits. A name is case sensitive. In formal terms, a DATEX II name shall comply with the following definition using Extended Backus Naur Form as of ISO/IEC 14977:1996.
name ::= letter , { letter | digit }
letter ::= “A” | “B” | “C” | “D” | “E” | “F” | “G” | “H” | “I” | “J” | “K” | “L” | “M” | “N” | “O” | “P” | “Q” | “R” | “S” | “T” | “U” | “V” | “W” | “X” | “Y” | “Z” | “a” | “b” | “c” | “d” | “e” | “f” | “g” | “h” | “i” | “j” | “k” | “l” | “m” | “n” | “o” | “p” | “q” | “r” | “s” | “t” | “u” | “v” | “w” | “x” | “y” | “z”
digit ::= “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”
The names of the instances of the following UML metaclasses shall be in Upper Camel Case notation, i.e. they shall start with an upper case letter (‘A’ to ‘Z’), they shall consist of one or more logical components, and each component itself shall again begin with an upper case letter (Example: Component1Component2Component3): Class, DataType, Enumeration, Package
The names of the instances of the following UML metaclasses shall be in Lower Camel Case notation, i.e. they shall start with a lower case letter (‘a’ to ‘z’), they shall consist of one or more logical components, and each component starting with the second component shall begin with an upper case letter (Example: component1Component2Component3): Attribute, Property
In all DATEX II names, acronyms should be avoided, but in cases where they are used, their capitalization shall be modified to comply with the provisions in subsections 0 and 3.
Note
In some parts of this specification, default names are defined by turning names of other constructs from Upper Camel Case to Lower Camel Case. This transformation is strictly defined as turning only the first character from upper case to lower case. Example: a proper class name may be “ANameExample”. If referred by another class via a composition without role name and qualifier, the XML schema encoding of the enclosing class will contain an attribute that will implicitly be named “aNameExample”.
The DATEX II modelling methodology implies a certain structure of a UML model that seeks to claim compliance with this specification. This subsection states the requirements that UML models shall comply with in terms of constraints on the use of certain UML constructs. Note that no statements are made concerning other UML constructs, i.e. models that contain other UML constructs may still claim DATEX II compliance, as long as all requirements for the named UML constructs are met.
The provisions in this subsection address the particular requirements for the platform independent model, i.e. they do not address requirements for mapping DATEX II models to specific transfer syntax for exchange of data. Such requirements are dealt with in later subsections of this specification.
Attributes of the base UML metaclasses, that are shown in Figure 1-8 but are not described in the corresponding parts, have no semantics in this specification, since they are tool related build-in metaclass properties.
Note
The DATEX II PIM does not contain a formal specification of a datatype (e.g. lexical space, value range, etc,). All required information needed to properly implement the concept intended with a datatype in any specific transfer syntax model shall be clearly specified in the definition.
Note
Not all generalisations have to have the stereotype “D2LevelBExtension”.
DATEX II models enable application specific extensions. These extensions may implement innovative concepts, and while they may happily reuse data types, enumerations, components and even identifiable entities from an existing model, they cannot seek any type of system level interoperability with systems being implemented without being cognizant of this particular extension. Such extensions are denoted as level C extensions.
In other scenarios, extensions may only seek to add some limited amount of application specific business logic whilst at the same time requiring backward compatibility with an existing model. “Compatibility” here means system level interoperability, e.g. for systems exchanging XML messages a valid instance of an extended model shall always be also a valid instance for the core model. This level of interoperability is in DATEX II denoted as level B extension. The levels’ names actually indicate a compatibility hierarchy where the top level (maximum compatibility) is denoted as level A, where both interacting systems use an identical model which is pre-defined in other parts of this specification, without any extensions.
Note
A compatible extension is denoted within the DATEX II specification as a level B extension. Non compatible extensions are denoted as level C extensions.
Note
Multiple level B extensions of one core model enumerations may exist.
The constructs of the UML profile for a platform independent model presented in the main sections of this specification – complemented by additional metadata for a platform specific model – govern the mapping of DATEX II models to XML Schema Definitions (XSD – see [3] and [4]). This section describes how the normative schemas used in all further parts of this specification are actually created from a UML model conform to the previous sections of this specification.
The XSD mapping is basically covered by a small set of general rules, which are then amended / extended by further detailed mechanisms that handle specific cases. These rules are described in the rest of this normative section.
A model that needs to be mapped to XML Schema Definition shall fulfil additional requirements on top of those specified in the previous sections of this specification. These additional requirements are captured in this annex. Conformant models fulfilling these requirements can be mapped to a corresponding XML Schema Definition according to the mapping described in subsequent subsections.
schema-type ::= “duration” , “dateTime” , “time” , “date” , “gYearMonth” , “gYear” , “gMonthDay” , “gDay” , “gMonth” , “boolean” , “base64Binary” , “hexBinary” , “float” , “double” , “anyURI” , “QName” , “NOTATION” , “string” , “decimal” , “normalizedString” , “token” , “language” , “Name” , “NMTOKEN” , “NCName” , “NMTOKENS” , “ID” , “IDREF” , “IDREFS” , “ENTITY” , “ENTITIES” , “integer” , “nonPositiveInteger” , “long” , “nonNegativeInteger” , “negativeInteger” , “int” , “unsignedLong” , “positiveInteger” , “short” , “unsignedInt” , “byte” , “unsignedShort” , “unsignedByte”
Note
This means that none of the listed names or “schemaName” values shall be lexically equal.
The following classes describe how the constructs of a DATEX II compliant UML model (i.e. a UML model compliant with the previous sections of this specification) can be mapped to XML Schema (XSD).
<xs:simpleType name=TypeNameFromUMLModel>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
<xs:restriction base=Namespace:RestrictionBase />
</xs:simpleType>
Note
The “annotation” element is optional and schemas may be produced with or without annotations
The value of “RestrictionBase” is determined according to the following algorithm:
<xs:restriction base=Namespace:RestrictionBase>
ContentOfFacetsPropertyHere
</xs:restriction>
Note
Note that according to Requirements for mapping to XML schema definition, the content of this UML Property shall be a valid content model for the “xs:restriction” element.
“D2Enumeration” classes – and their corresponding “D2Literal” classes – are always mapped to an XML Schema simple type definition with the following structure:
<xs:simpleType name=EnumerationNameFromUMLModel>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value=EnumerationLiteralNameFromUMLModel>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
</xs:enumeration>
...
<xs:enumeration value="_extended" />
</xs:restriction>
</xs:simpleType>
The literals are mapped in the order of increasing values of their “order” property.
Generated schemas may be profiled in the sense that types may be restricted as long as each valid instance of the restricted profile is also valid for the full mapping. For enumeration classes this means that profiled schemas may omit literals.
The last enumeration value “_extended” is automatically generated for all “D2Enumeration” classes in support of compatible extensions.
A second complex type is generated for all “D2Enumeration” classes:
<xs:complexType name=_EnumerationNameFromUMLModel>
<xs:simpleContent>
<xs:extension base=Namespace:EnumerationNameFromUMLModel>
<xs:attribute name="_extendedValue" type="xs:string" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Wherever a “D2Enumeration” is given as the type of a “D2Attribute”, the XML element created for this attribute uses this “_” type, which allows for setting the element content to “_extended” – in case none of the original literals is applicable – and providing the extended value via the “_extendedValue” attribute.
<xs:complexType name=ClassNameFromUMLModel>
…
<xs:sequence>
…
<xs:element name=AttributeNameFromUMLModel
type=Namespace:_EnumerationNameFromUMLModel
minOccurs="1" maxOccurs="1"/>
…
</xs:sequence>
…
</xs:complexType>
If in a level B model one or more level B extensions exist for a DATEX II enumeration, the literals specified in all these extensions are collected and a third enumeration type is added to the corresponding schema:
<xs:simpleType name="_"+ EnumerationNameFromUMLModel +"ExtensionType">
<xs:restriction base="xs:string">
<xs:enumeration value=NameOfLiteralFromExtension />
…
</xs:restriction>
</xs:simpleType>
In such a case, the type of the “_extendedValue” XML attribute is changed from “xs:string” to the new extension type name =”_”+EnumerationNameFromUMLModel+”ExtensionType”.
<xs:complexType name=ClassNameFromUMLModel>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name=NameFromUMLModel type=Namespace:TypeFromUMLModel
minOccurs=LowerBound maxOccurs=UpperBound>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
</xs:element>
…
</xs:sequence>
</xs:complexType>
The name of the generated XML Schema type is taken from the “name” metaattribute of the UML Class, the content of the “xs:documentation” element is taken from the mandatory “definition” Property of the assigned Stereotype from the DATEX II UML profile.
<xs:element name=NameFromUMLModel type=Namespace:TypeFromUMLModel
minOccurs=LowerBound maxOccurs=UpperBound>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
</xs:element>
If lower or upper bounds are not provided, a default of “1” is assumed. Note that “xs:annotation” elements may be omitted in cases where they are not required by rules and not provided by the model (e.g. in case of a single association between two “D2Class” classes).
Generated schemas may be profiled in the sense that multiplicity ranges may be restricted as long as each valid instance of the restricted profile is also valid for the full mapping. If an upper bound is reduced to zero, the element definition may be omitted. If such an element omission makes a class declaration obsolete – i.e. the class is no longer referenced anywhere in the model – the class declaration may be omitted as well. i.e. it is may be excluded from the generated schema.
In such a case, the mapping of a “D2Attribute” as of A.3.4.1.3 is changed to:
<xs:element name=NameFromUMLModel minOccurs=LowerBound maxOccurs=UpperBound>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base=Namespace:TypeFromUMLModel>
Facets
</xs:restriction>
</xs:simpleType>
</xs:element>
In this case, the type name is created as “_<name>” where <name> is determined according to the following hierarchy:
A definition for this type is then also added to the schema as:
<xs:complexType name="_"Name>
<xs:sequence>
<xs:element name=Name1 type=Name2 minOccurs="1" maxOccurs="1" />
</xs:sequence>
<xs:attribute name=NameFromUMLQualifier type="xs:int" use="required" />
</xs:complexType>
where Name2 is the “name” of the UML Class connected on the other side of the UML Association, whereas Name1 is the same name turned to LCC.
<xs:element name="_"ClassNameToLCC"Extension" type=Namespace:"_"ExtensionType minOccurs="0" />
Again, the name of this element is generated by taking the class’ name and turning it to lower camel case (by turning the first character to lower case), prefixing it with “_” (to indicate a generated name) and then appending the fixed string “Extension”.
<xs:complexType name=ClassNameFromUMLModel>
<xs:annotation>
...
</xs:annotation>
<xs:sequence>
...
</xs:sequence>
<xs:attribute name=AttributeNameFromUMLModel type=TypeFromUMLModel use=”required” />
...
</xs:complexType>
The ‘use=”required”’ is set if multiplicity is 1..1 and omitted in case of 0..1. Note that other multiplicities are not allowed and that the attribute’s mapped type shall be an XML Schema simple type according to Requirements for mapping to XML schema definition.
Those “D2Class” classes with a superclass are mapped in a similar way, just that they are mapped to extensions of their superclass:
<xs:complexType name=ClassNameFromUMLModel>
<xs:annotation>
<xs:documentation>
ContentOfDefinitionPropertyFromUMLModel
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base=Namespace:NameOfSuperclassFromUMLModel>
<xs:sequence>
...
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:attribute name="id" type="xs:string" use="required" />
For “D2VersionedIdentifiable” classes, a second attribute is created for the version number.
<xs:attribute name="version" type="xs:string" use="required" />
<xs:unique name="_"Element+TargetClass"Constraint">
<xs:selector xpath=".//"TargetClass} />
<xs:field xpath="@id" />
<xs:field xpath="@version" />
</xs:unique>
<xs:complexType name="Reference">
<xs:attribute name="id" type="xs:string" use="required" />
</xs:complexType>
and
<xs:complexType name="VersionedReference">
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="version" type="xs:string" use="optional" />
</xs:complexType>
Depending on whether the target type for a class TargetClass is versioned or not, the corresponding reference type looks like this
<xs:complexType name="_"TargetClass"Reference">
<xs:complexContent>
<xs:extension base=Namespace:Reference>
<xs:attribute name="targetClass" use="required" fixed=TargetClass />
</xs:extension>
</xs:complexContent>
</xs:complexType>
or like this
<xs:complexType name="_"TargetClass"VersionedReference">
<xs:complexContent>
<xs:extension base=Namespace: VersionedReference>
<xs:attribute name="targetClass" use="required" fixed=TargetClass />
</xs:extension>
</xs:complexContent>
</xs:complexType>
Note
The “version” attribute in type “VersionedReference” is optional. Hence it is possible to refer to a particular version of such a target or it is optional to refer just to the target, leaving the choice of the version at the discretion of the client receiving the data.
Note
This specification does not specify a minimum model structure. Hence, a model that claims conformance to this specification and wants to make use of the mapping for typed references specified in this section will itself have to ensure that the base classes “Reference” and “VersionedReference” are available by specifying corresponding DATEX II classes of that name in the “Common” namespace “http://datex2.eu/schema/3/Common”.
<xs:element name=NameFromRootELementProperty type=Namespace:ClassName />
The content of the “rootElement” UML Property is used for the “name” attribute and the class name itself is used for the “type” attribute.
<xs:attribute name="modelBaseVersion" type="xs:string" use="required" fixed="3" />
<xs:attribute name="extensionName" type="xs:string" use="optional"/>
<xs:attribute name="extensionVersion" type="xs:string" use="optional"/>
<xs:attribute name="profileName" type="xs:string" use="optional"/>
<xs:attribute name="profileVersion" type="xs:string" use="required"/>
This means that <xs:element name=”_”SomeClassExtension type=Namespace”:_ExtensionType” minOccurs=”0” /> is replaced by <xs:element name=”_”SomeClassExtension type=Namespace”:_”SomeClassExtensionType minOccurs=”0” /> Where “_”SomeClassExtensionType” is defined as:
<xs:complexType name="_"SomeClassExtensionType>
<xs:sequence>
<xs:element name=classA type=Namespace:ClassA minOccurs=”0” />
<xs:element name=classB type=Namespace:ClassB minOccurs=”0” />
...
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
Furthermore, the following type is created:
<xs:complexType name="_"ExtendedEnumerationName>
<xs:simpleContent>
<xs:extension base=Namespace:ExtendedEnumerationName>
<xs:attribute name="_extendedValue" type=Namespace":_"EnumerationNameExtensionType />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
The convention to use this new type is that if the value of an attribute of that type is a literal from the supertype, the literal is just used as the XML element content:
<ext:foo>OldLiteralFromSupertype</ext:foo>
If the value is a literal from the new, extended enumeration, the element content is either set to an applicable literal from the supertype (which may be “_extended”), and the XML attribute “_extendedValue” is set to the new literal:
<ext:foo _extendedValue=NewLiteralFromSubtype>LiteralFromSupertype</ext:foo>
The whole set of type and element definitions provided so far in this subsection is finally wrapped into multiple XML schema definition files, each with the following XML structure:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified"
xmlns:Prefix=NamespaceURL version=Version
targetNamespace=NamespaceURL
… {further namespace declarations where required}
xmlns:xs="http://www.w3.org/2001/XMLSchema">
…
</xs:schema>
The full DATEX II v3 Level A specification consists of the following packages, which are defined in further parts of this specification:
Note
that this package also hosts the “Reference” and “VersionedReference” type definition as specified in A.3.5.3.
Each of these packages has its own namespace and is mapped to its own XML Schema Definition file ({Namespace}.xsd), with appropriate “import” statements where required (e.g. all payload packages import Common).
The target namespace of each schema is: http://datex2.eu/schema/3/{Package}
The schemas of the Level A packages (“Common”, “LocationReferencing” plus all payload publication packages) further contain an XML element “version” that contains the DATEX model version 3.[n] (“n” being the minor version), taken from the “version” UML Property of the “D2ModelRoot” UML Stereotype.
[1] Grady Booch, James Rumbaugh, Ivar Jacobson (2005). Unified Modeling Language User Guide, The, 2nd Edition. Addison-Wesley. ISBN 0-3212-6797-4.
[2] Chonoles, Michael Jesse; James A. Schardt (2003). UML 2 for Dummies. Wiley Publishing. ISBN 0-7645-2614-6.
[3] World Wide Web Consortium. XML Schema Part 1: Structures Second Edition, ed. Henry S. Thompson, David Beech, Murray Maloney, and Noah Mendelsohn. W3C Recommendation 28 October 2004
[4] World Wide Web Consortium. XML Schema Part 2: Datatypes Second Edition, ed. Paul V. Biron, Ashok Malhotra. W3C Recommendation 28 October 2004