XML / XSD Representation

Mapping of UML VEC Model to XML Schema Definition (XSD)

The mapping of the VEC model to an XML schema definition (XSD) described in the following defines the standardized syntax for the exchange of harness design data across process steps and supporting tools. The dedicated namespace prefix of the schema definition is vec, the namespace is http://www.prostep.org/ecad-if/2011/vec.

The XSD defines a single VecContent-element as xs:element. This is the declared root element for all VEC compliant XML-documents. A VEC compliant XML-document is limited to one instance of a VecContent.

Classes

Each VEC UML model class (see figure below for an example from the VEC), which is not stereotyped as <<enumeration>>, are mapped in the following form.

1. Each regular UML class is mapped to a xs:complexType with the same name as the VEC model class name.
2. If the VEC model class is a derived subclass the corresponding xs:complexType defines a xs:extension.
3. VEC model class attributes & associations which are defined by the class itself and not inherited, are mapped to a xs:sequence of xs:elements with the same names as the names of the corresponding class attributes (see Attributes and Associations below).

 <xs:complexType name="DocumentVersion">
      <xs:complexContent>
         <xs:extension base="vec:ItemVersion">
            <xs:sequence>
               <xs:element name="DocumentNumber" type="xs:string"/>
               <xs:element name="DocumentType" type="vec:DocumentType" minOccurs="0"/>
               ...
               <xs:element name="DocumentClassification"
                           type="vec:DocumentClassification"
                           minOccurs="0"
                           maxOccurs="unbounded"/>
               <xs:element name="ReferencedPart" type="xs:IDREFS" minOccurs="0"/>
               ...
            </xs:sequence>
         </xs:extension>
      </xs:complexContent>
   </xs:complexType>

Identifiers

id-Attributes

All xs:complexType that are not a refinement of another type (via xs:extension) define a mandatory XML attribute id with the type xs:ID. Syntax restrictions and uniqueness constraints for xs:ID are defined by the XML standard itself. xs:ID values are required to be unique within a XML document. Assocations between objects within a VEC XML document are defined with the help of xs:IDREF(S). The values in a xs:IDREF(S) must be defined xs:ID values existing in the context of the document.

The values for the id-attributes are normally generated by exporter / XML processor during the XML file generation. Exporters are expected to generate valid values for the id-attributes so that Links (instances of associations) are expressed correctly and the resulting XML file is XSD compliant.

   <xs:complexType name="ExtendableElement" abstract="true">
      <xs:sequence>
      ...
      </xs:sequence>
      <xs:attribute name="id" type="xs:ID" use="required"/>
      <xs:attribute name="immutable-global-iri" type="xs:anyURI"/>
   </xs:complexType>

immutable-global-id-Attributes

As defined in the section above, each xs:complexType defines a XML-Attribute id with the type xs:ID, either by itself or by inheritance from a superclass. By nature, those ids are volatile and have a purpose only within a specific XML file.

However, there are requirements in advanced use cases where it is necessary to be able to identify objects in the VEC globally and in a temporally stable manner. Such use cases are for example, but not limited to:

• Change Management & Synchronization
• Integration with other Standards, e.g. the Asset Administration Shell (AAS)
• Provision of VEC objects via modular APIs (e.g. REST)
• Compliance with other serialization formats like RDF.

Therefore, each xs:complexType that defines an id-attribute also defines an immutable-global-iri attribute with the type xs:anyURI. Despite its name xs:anyURI is in fact the type for an Internationalized Resource Identifier (IRI), see “W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes”.

If two VEC objects, regardless of their context or their affiliation to a specific file, have the same immutable-global-iri, they are in fact a representation of the same (real world) object (potentially in a different state). The concept of IRIs allows the definition of global unique identifiers in various ways and with different strategies. For example, using http-IRIs allows the dereferencing (finding) of objects identified by such IRIs. However, the chosen strategy has a strong influence on the circumstances under which two objects in the VEC can be identified as the same. Both effects (same & not the same) can be desired effects in a specific use case / process / scenario. Therefore, this recommendation does not define a specific strategy for minting IRIs for VEC objects. It is also beyond the scope of this recommendation to describe or define valid strategies for minting IRIs.

However, two examples shall illustrate the influence of a choosen strategy. The examples are for illustrative purposes only and their description does not claim to be complete:

• UUIDs: IRIs can be created from UUIDs. UUIDs are generated random values that guarantee universal uniqueness. To satisfy the requirement of temporal stability, a source system has to maintain (store) those UUIDs for every object. Objects that are created and distributed at the same time in different locations are hard to handle. Objects deleted from the system (and then recreated) are always handled as different objects.
• Calculated IDs: IDs could be calculated from object keys in the domain (e.g. the identifying attributes of a PartVersion). Such IDs could be calculated on the fly and do not have the requirement to be stored along with the object, as they are stored implicitly via the attributes from which they are derived. If the same object (same identifying attributes) is created in different locations, both variants can still be recognized as identical. On the downside, an ID generation algorithm has to be defined, that generates those unique IDs for every possible object type and situation. The algorithm has to guarantee that the generated IDs fulfill uniqueness requirement, which depends on the naming / identification strategy of the process. And yet, there are still cases where objects can not be recognized as the same (e.g. renaming of “key”-attributes).

Attributes & Associations

In the XML Schema represention of the VEC, attributes and compositions are handled in the same way. The containing (or orginating) class defines a xs:element. The name-attribute of the xs:elementis equivalent to the name of the attribute or the target role in the UML model. The first letter is converted to upper case. The type of the xs:element is either a primitive type (see mapping below) or a reference to corresponding VEC schema type.

All associations in the VEC model are directed and therefore have a defined source and target. An association is mapped to an xs:element which is owned by the XSD complex type that represents VEC model class that is source of the association. The name of the element is equal to the name of the association target role name (first letter upper case). The type is xs:IDREF respectively xs:IDREFS depending on the associations target cardinality.

Primitives

The UML uses sereval primitive data types that are mapped to the correspondig XSD data types:

• xs:string (corresponding to the VEC model data type definition String)
• xs:dateTime (corresponding to the VEC model data type definition Date)
• xs:integer (corresponding to the VEC model data type definition Integer)
• xs:double (corresponding to the VEC model data type definition Double)
• xs:boolean (corresponding to the VEC model data type definition Boolean)

Meta Model annotations embedded in XML Schema

Due to the nature of XML Schema and XML files it is not possible to express all specifications, restrictions and additional information of the VEC model (defined as UML model) directly in XML Schema. In particular, these are:

• Target types for IDREF / IDREFS associations,
• Uniqueness of collections (bag vs. set semantics),
• Ordering of collections,
• Assignment of model elements to packages / namespaces in the model, and
• Deprecation of model elements.

To overcome this gap, additional meta information, embedded in the XML Schema will be provided for future versions (Version > 2.0.1). The extension is done with the annotation concept provided by XSD (xs:annotation / xs:appinfo see W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures / 3.15.1 The Annotation Schema Component).

The XSD schema for the content of the xs:appinfo can be downloaded here:

model-meta-1.0.0.xsd . The XML target namespace of the meta information is: http://www.prostep.org/ecad-if/2022/model-meta .

Package

All types defined in the VEC are associated with a namespace, e.g. core, electrical_parts, schematic. This meta information is defined as follows:

    <xs:element name="package" type="meta:Package"/>

    <xs:complexType name="Package">
        <xs:attribute name="name" type="xs:string"/>
    </xs:complexType>        

Deprecation

In case a model element (class, attribute, association, enumeration, literal etc.) gets deprecated, it will be annotated with deprecated along with further information about the reason for deprecation and the VEC version since when the deprecation is in place. Normally deprecated elements will be removed with the next major release.

    <xs:element name="deprecated" type="meta:Deprecation"/>

    <xs:complexType name="Deprecation">
        <xs:attribute name="reason" type="xs:string"/>
        <xs:attribute name="since" type="xs:string"/>
    </xs:complexType>

Collections

Meta information for associations / collections is defined as follows:

    ...
    <xs:element name="relationship" type="meta:Relationship" />
    
    <xs:simpleType name="RelationshipType">
        <xs:restriction base="xs:string">
            <xs:enumeration value="Attribute" />
            <xs:enumeration value="Association" />
            <xs:enumeration value="Composition" />
        </xs:restriction>
    </xs:simpleType>


    <xs:complexType name="Relationship">
        <xs:attribute name="element-type" type="xs:QName"/>
        <xs:attribute name="relationship-type" type="meta:RelationshipType" use="required"/>
        <xs:attribute name="unique" type="xs:boolean" default="true"/>
        <xs:attribute name="ordered" type="xs:boolean" default="false"/>
    </xs:complexType>
    ...

All elements in the model that are defined as an association, with or without composition, and all attributes receive a relationship annotation. Regarding the XML Schema alone, attributes and composite associations have a similar XSD definition. However, the modelling approach in VEC was chosen intentionally and there are subtle differences in semantics in the context of the specification.

The attribute representation is used for primitive types and structured value types (e.g. NumericalValue, Material or Color). Those elements do not have complex substructures and do not have incoming associations. On the other hand, composite associations are used for more complex substructures and elements that are relevant in a larger context (e.g. Slot, Cavity or WireElement).

• element-type: The schema type of elements referenced by the association as defined in the UML model, to preserve type info for IDREF(S), which will be lost otherwise in native XML schema. Only allowed on IDREF(S) elements.
• relationship-type: The type of the relationship as defined in the UML model.
• unique: Defines the collection semantics for elements referencing more than one element. unique=false means that the model allows duplication for this reference. In other words, the same object can be referenced multiple times (bag semantics). unique=true applies when an element should only be referenced once (set semantics). Composite associations can only be unique=true.
• ordered: Defines that the order of the collection has a semantic meaning and is not just given, because XML is an ordered format by definition.

The attributes of the relationship element are only present if the attribute has a reasonable, non-redundant meaning in the context. ordered or unique for a 0..1 association has questionable value, unique for composites can only be true and element-type is only relevant for IDREF(S) associations, because for composites the information is already contained in the regular schema definition.

Tailoring Concepts

Motivation and Objective

The VEC provides a comprehensive model for the digital description of a wide variety of information and their relationships to each other in the context of the electrical system development process.

Despite the striving for the greatest possible semantic precision, the demand for general applicability of the standard means that, at various points restrictions cannot be formulated to the same extent as it would be possible in the context of a very specific use case or a company context. This applies to the following examples, among others:

• The set of valid model elements: Probably no use case requires all 450+ classes of the VEC at the same time and the set of required model elements is highly dependant from the use case itself.
• Valid values for attributes: The allowed patterns and / or discrete values (enumerations) of attributes can depend on a specific use case or company context and can even change over time (e.g. new technologies)
• The balance between mandatory and optional information: The amount and completeness of information contained in a VEC depends on the use case and process. While it might perfectly ok the have some missing information in an early phase of the process, it might intolerable at a later stage.

This implementation guideline presents three approaches for adapting the XML representation of the model to address the above issues in specific application scenarios, while still maintaining compatibility with the standard:

1. Custom Open Enumerations: New literals can be added to open enumerations (see Open and Closed Enumerations)
2. XSD 1.1. Assertions: The schema can be enriched with assertions to be more restrictive.
3. Schema Filtering: With “Schema Filtering” the schema can be made less extensive and by this also more restrictive (Less allowed classes, attributes etc.).

All these approaches have in common, that the schema of the standard is adapted / modified in a suitable form. The result is a tailored VEC XML Schema that is specific for the use case, but still compatible with the regular VEC schema.

This Implementation Guideline explains how these modifications can be achieved in an efficient way based on XSLT. XSLT is a useful technology, when:

• you want to modify XML data,
• you can define the modification based on rules,
• the general structure of your result is close to the input,
• and performance is not critical.

This makes it the perfect solution for this use case, where we want to modify the XML Schema of the VEC at very specific locations while keeping the rest unchanged.

General Concept

The general concept is illustrated in the figure above. The customization rules are defined in an “compiler XSL-file”. This file defines how the extensions are defined syntactically in the schema. It compiles the customizations into an existing schema. For example, in case of open enumerations, the compiler file defines at which position in XSD new literals have to be inserted. The compiler files are universal and independent of the specific context (e.g. company, use case) of the customization. For open enumerations and assertions such compiler files are provided here.

The actual customizations are defined in an external XML data file (Customization Definition in the figure above). For example, in case of open enumerations, the data file defines which enumerations should be extended with which literals. This information is specific to the customization context and has to be created during the customization process. The syntax of the data file depends on the compiler file, but is usually trivial.

To create a custom VEC schema, the desired schema variant (strict or not) of the underlying VEC version is passed into a XSLT transformation pipeline, with the Compiler XSL as transformation. The data file is side loaded from the Compiler XSL.

Run the Transformation

java -cp /path/to/saxon.jar net.sf.saxon.Transform \
   -xsl:./path/to/compiler.xsl 
   -s:/path/to/vec.xsd 
   -o:/path/to/result.xsd 
   data-file=url-to-data-file.xml

If the url-to-data-file.xml is a relative path, then it is relative to the compiler.xsl. The easiest way is to place required files (including the data file) in the current working directory.

Open Enumerations

Open Enumerations are a concept in the VEC to have predefined values for attributes, whilst being open for extension (for details see the corresponding recommendation chapter Open and Closed Enumerations). Two schema variants are provided officially for the VEC: the regular and the strict schema. The regular schema can be used for pure syntax validation of VEC files. However, it makes no restrictions for the use of values in attributes with an open enumeration type. The strict schema restricts these attributes to have only values that are defined literals from the VEC standardization board in the corresponding open enumeration. The advantage of using the strict schema is that you are able to validate that only defined literals have been used.

However, if you extend¹ an open enumeration with new literals, e.g. for your process specific requirements, or new wiring harness technologies, then the strict schema validation will break. In this case it is not possible anymore to check if only defined values, either by the standard or the process, have been used. Nevertheless, it would be highly appreciable to still have such a mechanism in place. To achieve this, you need an extended strict schema, that includes the values from the standardization board and the process specific values. This implementation guideline is about creating such an extended strict schema.

What you need

The generation of such an extended strict schema is done as described in section General Concept. As input, you need:

1. The Compiler XSL: vec-open-enum-compiler.xsl
2. A definition of your enumeration extensions, an example can be found here: enum-literals.xml

Define new Enumerations

The enum-literals.xml (link above) file contains examples on how to add custom enumerations.

<?xml version="1.0" encoding="UTF-8"?>
<enum-profile>
    <enum type="WireReceptionType">
        <literal name="MyExampleLiteral">
             My example description with html elements <br/>
        </literal>
        <literal name="MyExampleLiteral2" />
    </enum>
    <enum type="WireLengthType">
        <literal name="MyExampleLiteral3">
             My second example description
        </literal>
    </enum>
</enum-profile>

This example adds a literal with the name MyExampleLiteral to WireReceptionType with a description (Note that it is possible to include html tags) and a literal without a description named MyExampleLiteral2. It also adds MyExampleLiteral3 to WireLengthType.

If a new VEC version is released, this file can be used recreate an updated company specific scheme (without having to repeat all changes manual).

Schema Assertions

XSD 1.1 introduced a concept to define Assertions within a XSD:

An assertion is a predicate associated with a type, which is checked for each instance of the type. If an element or attribute information item fails to satisfy an assertion associated with a given type, then that information item is not locally valid with respect to that type.

Assertions are defined as XPath 2.0 expressions that are evaluated to true or false. This makes it possible to express much more meaningful rules in the schema than it is possible with the pure syntax checking of XSD 1.0. In particular, it is not only possible to further restrict the multiplicities of attributes, but more complex conditions, such as dependencies between attributes, can be expressed (e.g. like “if type is ‘rectangle’ then count(sides) must be greater equal 4”).

The great benefit of this approach is, that these rules are validated during a regular schema validation with a standard XML Parser.

What you need

The generation of such an asserted schema is done as described in section General Concept. As input, you need:

1. The Compiler XSL: vec-assertions-compiler.xsl
2. A definition your custom assertions, an example can be found here: data-profile.xml

Define Assertions

The data-profile.xml (link above) file contains examples on how to add custom assertions.

<?xml version="1.0" encoding="UTF-8"?>
<data-profile>
    <context type="ConductorSpecification">
        <rule test="CrossSectionArea">
             All conductors shall specify a cross section area. The cross section area is an 
             important parameter for numerous design rules (e.g. aggregated cross section area 
             of splices). 
        </rule>
        <rule test="CrossSectionArea/ValueComponent gt 0.0">
            A conductor with cross section area not greater than 0 is non-existent.
        </rule>
    </context>
    <context type="CavityAddOn">
        <rule test="WireAddOn/ValueComponent gt 0.0"/>
    </context>
</data-profile>

context type="..." defines the VEC class to which an assertion should be added. rule test="..." defines the XPath expression of the assertion that should be added to corresponding type. The above data-profile results in the following XSD:

<?xml version="1.0" encoding="UTF-8"?>
...
<xs:complexType name="ConductorSpecification" abstract="true">
    <xs:complexContent>
        <xs:extension base="vec:Specification">
            <xs:sequence>
                ...
            </xs:sequence>
            <xs:assert test="CrossSectionArea">
                <xs:annotation>
                    <xs:documentation xml:lang="en"> All conductors shall specify a cross section
                        area. The cross section area is an important parameter for numerous design
                        rules (e.g. aggregated cross section area of splices). </xs:documentation>
                </xs:annotation>
            </xs:assert>
            <xs:assert test="CrossSectionArea/ValueComponent gt 0.0">
                <xs:annotation>
                    <xs:documentation xml:lang="en"> A conductor with cross section area not greater
                        than 0 is non-existent. </xs:documentation>
                </xs:annotation>
            </xs:assert>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>
...

Schema Filtering

The VEC is a comprehensive model with a variety of classes and attributes. In very few cases all of them are needed at the same time. For this reason it may be desirable to restrict the number of valid schema elements for specific interfaces. Schema Filtering can be useful in these cases.

For example, an interface for the exchange of UsageNodes would only require a handful of VEC core classes. Another scenario might be that you want to prohibit the use of CustomProperty in your own process. Many scenarios are conceivable, in the core it always burns down to limiting the power of the VEC purposefully to achieve a better controllability for certain use cases and interfaces.

Since the scenario of Schema Filtering is more complex and less straight forward, than the Open Enumerations scenario, the following section just provides an idea for a possible approach and not a “ready-to-use” solution.

The basic idea here is, that an XSLT script simply removes all unnecessary elements and leaves the rest unchanged. You can use either a positive or negative filter approach. In our example, we use a negative filter list (all elements on the list are removed). When removing a class it is not sufficient to only remove the class itself. All usages of the class must be removed as well. A class that has mandatory usages by other classes, can not be removed unless all usages are removed recursively till an optional point is reached.

The file vec-tailor-schema.xsl contains an example on how to remove the Transformation2D from the VEC scheme. The following snippet shows the relevant parts only. The rest of the XSLT script is known known as identity transformation (copy of the source into the destination without changes).

The first line removes the class itself. The second line removes all optional attributes with the type Transformation2D. If you validate the resulting schema you can easily check if the Transformation2D has any mandatory usage that have been overlooked (it has not).

    ...
    <xsl:template match="xs:complexType[@name='Transformation2D']" />

    <xsl:template match="xs:element[@type='vec:Transformation2D' and @minOccurs=0]" />
    ...

Unfortunately IDREF attributes cannot be handled in this fashion automatically, but have to be checked manually. The figure on the right side displays the occurrenceOrUsage association between OccurrenceOrUsageViewItem2D and OccurrenceOrUsage. Associations are translated into IDREF or IDREFS in the XML Schema, in contrast to aggregations that are translated into contained xs:element (compare Mapping of the VEC Model to XML schema definition (XSD)). The XML Schema representation of the association is the following:

<xs:complexType name="OccurrenceOrUsageViewItem2D">
    <xs:complexContent>
        <xs:extension base="vec:ExtendableElement">
        <xs:sequence>
            ...
            <xs:element name="OccurrenceOrUsage" type="xs:IDREFS" minOccurs="0"/>
            ...
        </xs:sequence>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

That means a filtering rule cannot be formulated based on the target type of the association, as this type unknown in the XSD (in contrast to contained elements). Therefore a filtering rule must be more specific by explicitly addressing each relevant association, like this:

    ...
    <xsl:template match="xs:element[@name='OccurrenceOrUsage' and
        ancestor::xs:complexType[@name='OccurrenceOrUsageViewItem2D']]" />
    ...