ASAM OpenSCENARIO: UML Modeling Rules

Disclaimer

This document is the copyrighted property of ASAM e.V.

Any use is limited to the scope described in the license terms (https://www.asam.net/license). In alteration to the regular license terms, ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM’s regular license terms is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard ASAM OpenSCENARIO".

Foreword

A UML model should describe the domain aspects in a technology and platform independent manor (PIM, Platform Independent Model). The UML focuses on the domain concepts, not on the aspect how instances of the model are transported, exchanged or stored.

E.g. whether the lists are mapped to unwrapped or a wrapped list in the XSD file is not a domain specific aspect, but a question of how to map the data model to the XML technology. So, the UML model should abstract from these aspects.

Modelling from the scratch would prefer this approach. First create the platform independent model (PIM) and then generate an XSD representation out of the model (PSM, Platform Specific Model). In these terms, the OpenSCENARIO UML modeling is also a concession to the fact that the approach was vice-versa. The UML model is deduced out of the original XSD version 0.9.1. and it respects that it is important to draw the line back to the original XSD.

OpenSCENARIO chooses to add specific information to the platform independent model to enable a transformation to XSD and the XML technology. This is done with the help of stereotypes (e.g. <<XSDcomplexType>>)

The XSD transformation is considered such important, that the rules for transformation are part of the model. Nevertheless, the aspect of domain concepts and XSD mapping are strictly separated by the model itself (PIM) and the decorating aspects of how the model is transformed to the XML technology (stereotypes).

So, in these terms, the OpenSCENARIO UML model is a platform independent model that is decorated with stereotypes allowing the unambiguous transformation to XSD. By simply removing the XSD stereotypes from the model, you can extract the PIM and transforming this model in any other technology.

1. Introduction

1.1. Overview

The Unified Modeling Language (UML) is used to define the OpenSCENARIO data model formally and unambiguously. It enhances readability by graphical data model diagrams. A short introduction to UML is given in this document. Only those aspects of UML are described that are used in the OpenSCENARIO data model. Specifically, from the large set of available UML diagrams, only class diagrams for data modeling are applied.

2. Class Diagrams

2.1. Overview

In the OpenSCENARIO data model these types are used:

Classes
Enumerations
Interfaces
PrimitiveTypes

Constraints: All types have a name. The name of a type must follow the upper-camel-case notation, e.g. UserDefinedAction. It must be unique among the names of all types (interfaces, classes, enumerations, primitive types).

upper-camel-case notation pattern: ([A-Z][A-Za-z0-9]*

2.1.1. Class

The central modeling element in UML is a class. A class represents a set of similar objects, aka instances. Generally, a class can be instantiated many times. A class has attributes (defining the properties of these objects) and methods (defining the operations an object can perform). In general, for pure data models, methods are not relevant and are not used in the OpenSCENARIO data model.

Figure 1. Class example

2.1.2. Attributes and Cardinality

An attribute is either of type enumeration or of a primitive type. In OpenSCENARIO attributes have the cardinality 1..1 (required) or 0..1 (optional). In contrary to the XML schema notation, required is the default and 1..1 is not annotated to the attribute.

Constraints: The name of a property must follow a lower-camel-case notation, e.g. orientationType. They must be unique within the enclosing class.

lower-camel-case notation pattern: [a-z][A-Za-z0-9]*

2.1.3. Enumerations and Enumeration Literals

Enumerations are types in UML. They consist of a set of symbols which are called enumeration literals or enumeration tags. Instances of these types have one of these symbols as their value. In OpenSCENARIO an enumeration literal is considered a symbol that represents a specific semantic. In UML modeling no initial numerical values are assigned to the enumeration tags. In XML the symbol is used as its string representation.

Figure 2. RouteStrategy enumeration with the Enumeration literals fastest, leastIntersactions, random, shortest.

Constraints: The symbols for the enumeration literals must be in lower-camel-case notation and unique within the enclosing enumeration.

lower-camel-case notation pattern: [a-z][A-Za-z0-9]*

2.1.4. Interfaces and 'Realization' Relationships

Interfaces in UML provide a common semantic for any class that realizes this interface. Common UML also allows that interfaces inherit from other interfaces. This is not used in OpenSCENARIO. If a class realizes an interface, the relation between the class and the interface can be expressed as a "is considered a" relation. So, in the following example an instance of an ScenarioObject is considered an Entity. An EntitySelection is also considered an Entity. On the other hand, the set of any class that realizes an interface represents a closed set of types an instance can be of. An instance of Entity is either of type ScenarioObject or of type EntitySelection.

Figure 3. Interfaces and realization relations

2.1.5. Primitive Types

Primitive types represent the smallest atoms in a data model. To be consistent, a UML data model can define its own primitive types which then semantically refer to data system that have already defined primitive types (e.g. IEEE, Oracle, XSD) In OpenSCENARIO these types are used:

Boolean	Symbolic `True` or `False` or a $-notated parameter name
DateTime	from XSD DateTime or a $-notated parameter name
Double	IEEE 64-bit floating-point or a $-notated parameter name
Int	32-bit signed integer or a $-notated parameter name
String	any character string or a $-notated parameter name
UnsignedInt	Unsigned integer of 32 bits or a $-notated parameter name
UnsignedShort	Unsigned integer of 16 bits or a $-notated parameter name

2.1.6. Building Semantics with UML

With types and objects, sentences can build strong semantics that describe the domain knowledge precisely. If we are talking about instances, we say an instance of a specific type. E.g.: an instance of type FileHeader, or an object of class FileHeader. Also "a FileHeader" means an object of class FileHeader. Also compositions, relations, realizations and generalizations create good domain knowledge. E.g. "An Scenariobject is considered an Entity" can be deduced from the interface realization relation between ScenarioObject and Entity (see Section 2.1.4)

2.1.7. Inheritance Relationships

Inheritance is a relationship between two classes or two interfaces. In general, one class can inherit properties and behavior from a base class. In data models only attributes can be inherited. Inheritance is considered not such critical and sometimes not desirable. In fact, many real data systems like relational databases, ANSII C or Apache-Thrift do not support inheritance out of the box. The OpenSCENARIO data model does not use inheritance in the moment. A union like approach is used that is characterized by the choice constructs of the underlying schema. It is subject of discussion to introduce inheritance in the future.

2.1.8. Composition and Aggregation Relationships

When properties are not simple attributes of an enumeration type or a simple type, they form relations between classes. The relation that is most frequently used in OpenSCENARIO is a composition relation. Beyond the composition relation, there the aggregation relation has similar semantics. Both define an association between a containing class and a contained class. These two types of relation are drawn as a line with a diamond at the end of the containing class. A composition relationship’s diamond is filled, an aggregation is not.

The difference between these two kinds of relationships is as follows: The contained instance in a composition relationship is a part of the containing instance: If the containing instance is deleted, the contained instance no longer exists. Therefore, composition means an object may only be contained in one other object. An aggregation relationship is one of shared objects. This means, multiple objects may aggregate the same object. By consequence, an aggregated object still exists, even if the aggregating object is deleted.

The OpenSCENARIO data model is originally derived from an XML schema. In this hierarchical data structure, only compositions are used, since a child element cannot exist without the presence of its parent element. In a hierarchical data system, aggregations cannot be expressed. Being compatible to the XML schema is the reason, OpenSCENARIO uses exclusively composition relations.

Composition relations can be expressed as "owns" or "has" relations from the containing instance to the contained instance. Or "is owned by" or "is part of" from the contained instance to the containing instance.

Cardinality seen from the contained instance to the containing element is always exactly one. A contained instance is part of exactly one containing instance. On the other hand, there are no restrictions for the cardinalities (upper, lower) seen from the containing instance to the contained instance. The cardinalities are annotated at the contained class.

Compositions are considered properties of the containing class. Therefore, each composition has a name that is annotated at the contained class end of the association.

Constraints: the name of an association must be unique among the attribute names and any association, for which the containing class is the containing class or referencing class. Name follows the lower-camel-case notation.

lower-camel-case notation pattern: [a-z][A-Za-z0-9]*

Figure 4. Compositions

2.1.9. References

As aggregations and composition relations, a reference is an association between two classes or between a class and an interface. They are drawn as an arrow from the referencing type to the referenced type. The referencing type is always a class. The referenced type can be a class or an interface.

References are considered "references" or "points to" relations from the referencing instance to the referenced instance. Or, from the referenced instance to the referencing instance they form a "pointed by" or "referenced by" relation.

Cardinalities, seen from the referenced type are restricted by the fact, that the presence of a referenced instance is independent from the instance that is referencing it. So, the minimum cardinality must be zero. The maximum cardinality, if not restricted by some domain constraints is unbounded. In OpenSCEANRIO so far, the cardinalities from the referenced type to the referencing class are always 0..*. The upper and lower cardinality seen from the referencing class to the referenced class are not restricted. These are annotated at the referenced class.

References are considered properties of the referencing class. Therefore, each reference has a name that is annotated at the referenced class.

In a pure hierarchical data model, like XML, references cannot be expressed without the presence of constraints. Often, in these kinds of data models or data storing systems, references are expressed as symbolic links, either from the referencing instance to the referenced instance or vice-versa. In systems where the referencing instances and the referenced instances are identified by primary keys, these are used to express the symbolic link between the instances. In relational data base systems foreign keys of the referencing table row are incorporated in the referenced table row. In XML, the primary key of the referenced element is often expressed in a sub-element of the referencing element.

Without references, the data model would form a pure hierarchy. With the presence of references, the character of the data model becomes that of a network.

Constraints: the name of the association must be unique among the attribute names and any association, for which the referencing class is the containing class or referencing class. Name follows the lower-camel-case notation.

lower-camel-case notation pattern: [a-z][A-Za-z0-9]*

Figure 5. References

2.1.10. Packages

Packages are model elements in UML. A package is used to group elements in mid-size and large models. A package may contain other packages. Packages form dependencies which are implied by the elements the packages contain.

Currently, the packages in OpenSCENARIO are used to separate the different types and model elements like diagrams. It is subject of discussion reorganizing packaging to domain specific packages in the future. Packages like "Common", "Actions" or "Conditions" can rather be used to express domain specific dependencies than technical naming like "Enums", "Diagrams" and "Classes" which simply organize types of model elements.

2.1.11. Constraints

Defining constraints in UML is not supported very well. Neither by language elements nor by the UML tools, like Enterprise Architect. There is a constraint definition language that is called OCL (Object Constraint Language). Though, it is a formal way to define constraints, tools lack to support OCL well. There is some authoring support, but there are barely good parsers that allow automatic validation or code generation for programming languages. Also, there is no support for validating model instances with these constraints.

Taking these drawbacks into account, OpenSCENARIO takes this approach:

UML model elements are used to constrain the model as precise and restricted as possible. E.g. using string datatype instead of any or setting cardinality precisely are UML specific instruments to restrict a model properly. Also take into account that UML provides explicit and expressive model elements that already imply constraints. E.g.: A UML model provides an explicit reference as a model element instead of a foreign key constraint that is used in a RDBMS. Or cardinality is provided where NOT NULL constraints are used in RDBMS systems.
UML profiles can be used to add constrains to a model. For example adding a <<PrimaryKey>> stereotype to an attribute would indicate uniqueness in a certain namespace. Of course, as any user defined stereotype, the semantics must be defined properly.
Where UML is not sufficient to validate a model instance properly, checker rules are established to restrict a model and define validity. Checker rules are textual descriptions that use semantics from UML to describe restrictions. The benefit of human readable outscores the advantages that derive from a formal language that is not supported very well. Checker rules can be formally implemented by any programming language and have been proven to be practical for other standards (e.g. ODX [1]).
Checker rules can be categorized, to indicate groups of constraints. Like RDBS define UNIQUE constraints or PRIMARY KEY constraints, OpenSCEANARIO could benefit from such a categorization.

2.1.12. Summary

Here’s a summary of the model elements that are described in the OpenSCENARIO UML data model.

Classes (considered Types)
Interfaces (considered Types)
Enumerations (considered Types)
Primitive Types (considered Types)
Attributes (considered Properties of type Enumerations or Primitive Type)
Enumeration Literals
Composition Relationships (considered Associations and Properties of the containing class)
Reference Relationships (considered Associations and Properties of the referencing class)
Interface Implementation Relationships (considered an Association)
Inheritance Relationships (not used in the absence of inheritance, considered an Association)
Aggregation Relationships (not used)

3. UML Profiles

3.1. Introduction

In addition to the UML model elements, a domain can add semantics to an UML model. In contrary to the standard UML model elements like classes or interfaces, a domain can fully determine the semantics of the additional information. Usually this semantic is encoded with stereotypes. Stereotypes are named markers that can be applied to standard UML model elements like classes, interfaces, attributes.

The presence of these markers allows than to encode a domain specific information that can be formally exploited by technical systems. These technical systems can be transformation machines or generators. They may also help to visualize semantics in class diagrams.

Beyond the dual information whether a stereotype is applied or not, a stereotype can include name-value-pairs that carry further information. These are called tagged-values.

In OpenSCENARIO, stereotypes mainly decode information how to transform the existing UML into an XML-schema.

3.2. Defining a Profile

When defining a profile, stereotype definitions and tagged-value definitions are created. Also, it is defined to which standard UML elements a stereotype can be applied to. The following steps are necessary for each stereotype.

Define the stereotype with its name
Add tagged-value definitions to that stereotype (define name and datatype)
Define to which UML model elements the author of the model can apply the stereotype. Quite often, a stereotype can be applied to multiple model-elements like classes and interfaces.

3.3. Applied Profile Example

In OpenSCENARIO, stereotypes are mainly used to transform the existing model into an XML-schema. The transformation uses the applied stereotypes and tagged-values to add specific information to the transformation rules. The following example shows the stereotypes <<XSDcomplexType>> <<XSDgroup>> and <<enumeration>> that help the transformation to decide to which XML schema element a class or an enumeration should be transformed to.

Figure 6. Stereotypes that provide information for UML-to-XSD transformation.

3.4. EA Specific Profile

The following stereotypes are relevant for the EA internal transformation to an XML schema.

Table 1. Stereotypes of the EA specific profile "UML Profile for XSD Schema"
Stereotype Name	Applicable to	Semantic
XSDschema	Package	Marks a package as a source for XML-schema generation.
XSDgroup	Class	Class will be transformed to an `xsd:group`
XSDtopLevelElement	Class	Class is used to create the root element of the XML.
XSDcomplexType	Class	Creates a `xsd:complexType` from a class
XSDattribute	Class	Creates a `xsd:attribute` from a property.

Figure 7. The EA specific profile "UML Profile for XSD Schema"

For several reasons, more information is necessary for the UML-to-XSD transformation process and for a better understanding of the model.

Therefore, in an OpenSCENARIO specific profile stereotypes are introduced to add semantic to the model.

3.5. OpenSCENARIO Specific Profile

Table 2. Stereotypes of the OpenSCENARIO specific profile
Stereotype Name	Applicable to	Semantic
XSDschema	Package	Marks a package as a source for XML-schema generation.
XSDgroup	Class	Class will be transformed to an `xsd:group`
XSDtopLevelElement	Class	Class is used to create the root element of the XML.
XSDcomplexType	Class	Creates a `xsd:complexType` from a class
XSDattribute	Property, AssociationEnd	Creates a `xsd:attribute` from a property.
XSDunwrapped	Association	Marks an association as an unwrapped list in XSD. The name of the XSD Element that is used for the list items is given in the tag xsdElementName.
XSDwrapped	Association	Marks an association as wrapped list in XSD. He tags wrapperMin and wrapperMax are the cardinality the wrapper is included with.
XSDwrapperType	Class	If an element is used within a wrapped list, it defines its wrapping complex type in XML. The XSD transformation will create a complex type. For the creation of such a type the tags: xsdWrapperType, xsdWrapperElementName, min and max.
transient	Interface, Association	Marks that an interface or an association will not be transformed into an XML-schema.
nameRef	Association	This is added to a reference to imply that the association represents a property that is transformed in a `xsd:attribute`. The tagged-value xsdType carries the target datatype of for the `xsd:attribute`. E.g. string. Only string datatype is used so far for OpenSCENARIO.
xor	Association	Any composition of a union is marked with the stereotype xor. It visualizes the information that only one of the properties can be used at any given time. The containing class of such a composition must be tagged with the stereotype <<union>>
union	Class	Marks a class as a union like structure. Union like means that it acts as a container for many compositions. The class is not allowed to act as a referencing class for a reference. Any containing compositions of such a class must be tagged with the <<xor>>.

Figure 8. The OpenSCENARIO specific profile

4. Documentation Guidelines

The UML model is documented in Enterprise Architect (EA). Model elements are separated in these folders and packages:

ASAM                    - Root node for all model elements
    OpenSCENARIO        - All types and class specific diagrams.
        Classes         - All class types
        Diagrams        - All class specific diagrams. One diagram per class
        Enums           - All enumerations
        Interfaces      - All interfaces
        PrimitiveTypes  - All primitive datatypes.

Figure 9. Enterprise Architect Model Elements

5. Mapping to XML

The UML Profile will help to define a valid and unambiguous transformation into an XML schema.

5.1. XSD Transformation in Enterprise Architect

5.2. Description of the XSD Transformation

The model is feed into the XSD Transformation (for detailed transformation information see Section 6 ). Here is the schematic overview:

Classes with <<XSDcomplexType>> applied are transformed into xsd:complexType.

The name of the complexType is the name of the class.
Attributes with <<XSDattribute>> applied, are transformed into xsd:attributes.
Compositions for which the class acts as the containing class will be transformed into xsd:element or xsd:group. xsd:element is used when the contained class has <<XSDgroup>> applied. The ref value will be the class name of the contained class. xsd:group is used when the contained class has <<XSDcomplexType>> applied. The type value will be the class name of the contained class.
The minOccurs, maxOccurs are set to the corresponding cardinalities. They are discarded when the standard value is "1".
The tagged-value modelGroup is taken to decide whether the xsd:elements are enclosed into xsd:choice (value:choice), xsd:sequence (value: sequence) or xsd:all (value:all).

Classes with <<XSDgroup>> applied are transformed into xsd:group

The name of the xsd:group is the name of the class.
Compositions for which the class acts as the containing class will be transformed into xsd:element or xsd:group. xsd:element is used when the contained class has <<XSDgroup>> applied. The ref value will be the class name of the contained class. xsd:group is used when the contained class has <<XSDcomplexType>> applied. The type value will be the class name of the contained class.
The minOccurs, maxOccurs are set to the corresponding cardinalities.
The tagged-value modelGroup is taken to decide whether the xsd:elements are enclosed into xsd:choice (value:choice), xsd:sequence (value: sequence) or xsd:all (value:all).

Classes with <<XSDsimpleType>> applied are transformed into xsd:simpleType.

Base class is set after the generalized class (e.g. xsd:string)
Restriction etc. is set after the tagged-value "restriction"

Classes with <<enumeration>> applied are transformed into xsd:simpleType.

Xsd:restriction’s base is always xsd:string
The enumeration literals are transformed into a list of xsd:enumeration with the value set to the name of the symbolic name of the enumeration literal.

Classes with <<XSDsimpleContent>> applied are transformed into xsd:complexType with simple content (see CustomCommandAction as an example).

The tags umlPropertyName and xsdType are used to define the simple content.

Classes with <<transient>> applied are not transformed into the schema.

References with <<nameRef>> applied are transformed into attributes of their referencing classes.

For Classes with <<XSDwrapperType>> applied a wrapper is generated. See ParameterDeclaration: A complex type is genererated in XSD (see ParameterDeclarations as an example).

List associations with <<XSDunwrapped>> applied are using the xsdElementName tag for using an appropriate list element name in the schema.

List associations with <<XSDwrapped>> are reconnected to the wrapper complex type.

The mapping rules can be looked up in detail in the chapter .

5.3. Ordering XML Elements

In contrary to UML, XSD and XML imply an order for the occurrences of elements. This is true if sequence is used in the XSD file.

To ensure the right order for element generation, Enterprise Architect provides a mechanism to add a tag called position to the source role of an association.

Figure 10. The position tag that ensures the element generation order.

Please note: To ensure element generation order, all "outgoing" compositions of a class (see Section 2.1.8) must define a position tag as shown. The position tag values among these compositions of a class must start with 1 and must be in consecutive order. "Outgoing" means any association, for which the class is the containing class. Above, ScenarioDefinition is the containing class for the associations named parameterDeclarations, catalogLocations, roadNetwork, entities, storyboard.

Figure 11. Associations of the containing class ScenarioDefinition

5.4. Mapping of Lists

Neither in UML nor in XSD a generic list type exists. In UML, a list is basically a property or an association for which the maximum cardinality is greater than one. In XSD lists are usually defined as XSD elements with maxOccurs greater than one.

5.4.1. Wrapped Lists in XML

It is a good practice to wrap list elements into an element that represents the list in XML. The following example shows a list of ParameterDeclaration elements those are wrapped by a ParameterDeclarations Element.

Next example shows, how this is modelled in XSD. ParameterDeclarations represents the explicit complex type of the list. ParameterDeclaration represents the type of the list elements.

So, basically, if a complex type wants to declare a wrapped list of ParameterDeclaration elements, the complex type ParameterDeclarations can be used.

5.4.2. Unwrapped Lists in XML

Sometimes, unwrapped lists are preferred in the schema. In an unwrapped list, the elements are enumerated among with other elements which are enclosed in the common parent element. In the following example the complex type Maneuver is a composition of ParameterDeclarations and a list of elements named Event. Please note that the complex type Maneuver acts as an enclosing composition of two types (ParameterDeclarations, list of Event), not as a wrapper for an exclusive list type.

The next example shows the usage of unwrapped lists. Note that in an unwrapped list, the list elements (Event) and other elements (ParameterDeclarations) are enumerated in a common parent element (Maneuver). Also, the parent element may have attributes defined.

5.4.3. Abstracting from Wrapped and Unwrapped Lists in UML

As already mentioned, the UML model focuses on the on the domain concepts, not on the aspect how instances of the documents are transported, exchanged or stored. Therefore, lists in UML should abstract from the fact how they are mapped to an XSD.

Whether the lists are mapped to unwrapped or a wrapped list (see Section 5.4.1 and Section 5.4.2) is not a domain specific aspect, but a question of how to map the data model to an XSD file.

5.4.4. Mismatch of Unwrapped Lists and UML Property Names

Modelling unwrapped lists in XSD to properties in a UML model inevitably results in a mismatch between the element name in the XSD and property name in the UML. If we are regarding the maneuver example, the element name of the unwrapped list is Event. The list is represented by the list element (Event) that can occur multiple times.

If you are modelling such a list as a property/association in UML you would rather choose the name of such a property as Events (plural). So, there is the mismatch between the XSD describing a single Element (singular Event) and the UML model describing the property as a list of items (Events).

Neither solution is applicable and comprehensive: If you name the element in XML Events this is not very comprehensive, cause every list item rather represents a single event. If the name of the property in the UML is Event, you would rather assume that the property represents a single item. Look at the documentation in this case: "The property event represents a list of events." This looks weird and uncomprehensive.

5.4.5. UML Modeling of Unwrapped Lists

As a solution a new stereotype <<XSDunwrapped>> is introduced. The UML model defines a list and names it accordingly with its plural representation (e.g. events). The <<XSDunwrapped>> transports the following information:

The transformation instructs the XSD transformation that the property is transformed into XSD by using the pattern of an unwrapped list (see Section 5.4.2).
The tagged value xsdElementName is a property of the stereotype holding the name of the element name that is used in the XSD.

So as an example:

Name the list of events in the Maneuver class events. The naming is consistent with the fact that it represents a list of Event instances.
Add the stereotype <<XSDunwrapped>> to the property/association to instruct the XSD transformation, that the unwrapped list pattern is used (see Section 5.4.2).
The stereotype <<XSDunwrapped>> has a property xsdElementName. Assign it to the value 'Event' to make sure that Event is used in the XSD as the element name. Event is consistent with the fact that an Event element describes a single item.

5.4.6. Wrapped Lists and the Introduction of Unnecessary Classes in UML

As unwrapped lists result in a naming mismatches between UML and XSD, wrapped lists are leading to unnecessary classes when not designed properly.

Take the example ParameterDeclarations.

If we take the XSD as a starting point we see that wrapped lists result in two complex types (ParameterDeclarations, ParameterDeclaration). So as a designer, we could be tempted to create two UML classes. One named ParameterDeclarations and one named ParameterDeclaration.

This would force the UML design into:

Wherever the designer wants to define a property that represents a list of ParameterDeclaration instances, the indirection of using a ParameterDeclarations must be taken. The only reason for this is not that your domains demands such an indirection, but the representation in XSD as a wrapped list demands it.

Figure 12. Indirection

So, creating two classes in UML out of the wrapped list pattern has these drawbacks:

You are introducing an indirection (ParameterDeclarations) that obfuscates your intention of designing a list (list of ParameterDeclaration instances)
You are inconsistent and dependent on the fact how the list is mapped to a technology (XSD, either wrapped or unwrapped). A wrapped list demands an extra class and indirection, an unwrapped list does not.
You are introducing an additional class ParameterDeclarations that does not add additional knowledge to your domain model. This is the definition of noise.

This would couple domain decision (I want a list) to a technology decision (how do I want the list to be represented in XML).

So, the design issue is 'How can we consistently define a property as a list without being dependent how it is mapped to XSD?'

5.4.7. UML Modelling of Wrapped Lists

Again, we introduce a stereotype (<<XSDwrapped>>) to cleanly separate domain decisions from technology mapping decisions. Very consistently you would first define a property the same way as you would do it as an unwrapped list. For example: In the class Vehicle you would define a list of ParameterDeclaration.

The stereotype <<XSDwrapped>> would mark this list to be transformed to XSD using the wrapped list pattern (see Section 5.4.1).

Figure 13. Without indirection

The class ParameterDeclarations would not exist in the UML model. No indirections, no noise, no inconsistencies.

But when the complex type ParameterDeclarations exists in the XSD: How it is created and how does the XSD transformation know which wrapper that should be used?

The stereotype <<XSDwrapperType>>

As an instruction to the XSD transformation, every class that is used in a wrapped list (e.g. ParameterDeclaration) is decorated with the <<XSDwrapperType>> stereotype. This instructs the XSD transformation that a complex type (ParameterDeclarations) as a wrapper is created in the XSD. The tags of the stereotype describe the information that is needed to create such a wrapper.

For example: The type ParameterDeclaration defines its wrapping complex type ParameterDeclariations with these tags:

xsdWrapperType: _ParameterDeclarations_,
xsdWrapperElementName: _ParameterDeclaration_,
min: "0",
max: "unbounded"

5.4.8. Conclusion

With the introduction of the three stereotypes <<XSDwrapped>>, <<XSDunwrapped>> and <<XSDwrapperType>> it is possible to strictly separate domain concepts from technology mapping instruction. List properties can be defined in a consistent way, independent from the aspects, how they are mapped into XSD (wrapped or unwrapped). Once the properties are defined, the technology mapping instructions can be added independently by decorating the properties with stereotypes (<<XSDwrapped>>, <<XSDunwrapped>>).

With the strict separation these issues are solved:

The domain concept of defining a list is consistent and independent of the aspect whether the list is transformed into an wrapped or an unwrapped list.
Unwrapped lists: The mismatch between the element name in the XSD and property name in the UML is resolved (singular in XSD vs plural in UML)
Wrapped lists: Indirection and extra classes like (ParameterDeclarations) are no longer needed in the UML Model, while still being able to have them in XSD.

The following example shows the class Maneuver. It is a composite of an unwrapped list (property event) and a wrapped list property parameterDeclarations.

Figure 14. Class Maneuver as a composite of a wrapped list and a unwrapped list.

Reference: wrapped list stereotype is also a concept that drives the UML-To-XML transformation in the ODX Standard [1].

6. XSD Transformation

The unambiguous transformation into XSD is an important part in the standardization process. While UML is a formal way to describe domain specific aspects, the XML Schema and the XML documents as its instances are the most recognized part of the data model. The XSD and the XML technology determine an approach how documents can be exchanged between scenario authors, simulation system providers and other interested parties.

Currently scripting is available in the Enterprise Architect Corporate Edition and the Enterprise Architect Version 14.1 is used.

6.1. Preparing the model

With the XSD stereotypes described, the model is decorated. To start the transformation, select Scripting under Specialize menu.

Figure 15. Select Scripting in the Specialize Menu

In the Scripting Window, select the "Osc2XSD" folder and the script "OSC 2 XSD Transformation"

Figure 16. The Scripting Window

Make sure the OpenSCENARIO folder is selected and start the script.

Figure 17. Starting the Script

Enter the output filename and press Open

Figure 18. Enter filename

The Process starts, wait until "XSD Transformation done" appears in the System Output window.

Figure 19. Process has finished

View the created XSD file.

Bibliography

[1] ISO 22901-1: Road vehicles - Open diagnostic data exchange (ODX). International Organisation for Standardisation, 2008.

[2] Sparx Systems, Enterprise Architects. 2019.

Appendix A: XSD Generation Approaches in EA

There are different approaches to generate an XML schema from an Enterprise Architect model. Three approaches have been evaluated in respect to their complexity, their number of transformation steps and the comprehensiveness to the model architect.

A.1. Standard Transformation to XSD

Enterprise Architect is using the XSD profile to feed its own generator with the information needed to create an XML-schema out of an UML model (see [2]). Unfortunately, the EA specific transformation is not able to generate complex XML-schema mapping with all the information that we need for OpenSCENARIO.

These features are not supported by the standard transformation:

To translate references into xsd:attributes that hold the foreign keys of the referenced instance.
To translate naming conventions (translate names of associations from lower-camel-case to become an upper-camel-case element name in XML schema).
To imply rules for PrimitiveTypes and Enumerations that allow the use of $-notated parameters.
To create complex type (xsd:complexType) with simpleContent (xsd:simpleContent)

To be still able to use the standard UML-to-XSD transformation, its input must be prepared to fit in a first step. The input of this pre-transformation is our EA-UML-model. The output is a UML-model that fits the requirements for the input of the UML-to-XSD standard transformation. The pre-transformation can be defined in Enterprise Architect as a model-to-model transformation.

Figure 20. Steps of a UML-to-XSD transformation

The model-to-model transformation does the following:

Eliminate any interface that has the stereotype <<transient>> applied.
Eliminate any association that has the stereotype <<transient>> applied.
Eliminate any reference that has the stereotype <<namedRef>> applied. Instead create an attribute on the referencing class that has the same name as the association. The type of the attribute is the value of the tagged-value "xsdType". (Currently only the type "string" is useful).
Change the name of every association from lower-camel-case notation to upper-camel-case notation. In this way a generated xsd:element or xsd:group will be transformed into upper-camel-case. Attributes stay with the lower-camel-case notation to be transformed into xsd:attribute.
Eliminate any <<xor>> and <<union>> stereotype.
Eliminate package "Diagrams" (Not used for XSD Creation)
Restructure Packages Move any type from package "Class", "Enums", "Interfaces" into the package OpenSCENARIO. Remove the empty packages. This must be done because the EA Transformation creates an XML schema for every package by default. We want anything in one package.
Add a class with the name "parameter". Apply stereotype <<XSDsimpleType>>. Add a generalization from class “`xsd:string`”. Set the tagged-values:
derivation: "restricted"
pattern: $[A-Za-z_][A-Za-z0-9_]*

Make classes for primitive union types. Here example: Boolean

Rename Boolean type to BooleanTemp
Add a Class Boolean Apply Stereotype <<XsdUnion>>
Add a generalization from class parameter
Add a generalization from class xsd:boolean
Reconnect any attribute from BooleanTemp to Boolean
Eliminate BooleanTemp

Make the same for all enumerations. Here example: StoryboardElementState

Rename StoryboardElementState to StoryboardElementStateTemp
Add a class StoryboardElementState. Apply stereotype <<XSDunion>>
Add a generalization from class parameter
Add a generalization from StoryboardElementStateTemp
Reconnect any attribute from StoryboardElementStateTemp to StoryboardElementState.

Though the pre-transformation was implemented successfully, it is still not possible, to generate complex types with simple content within the EA XSD transformation. Another XSLT that transforms the output would solve the problem (post-processing).

This method was discarded due to the following facts:

Three transformations must be executed. Pre-transformation, EA XSD transformation and finally an XSTL transformation. Two must be completely engineered (pre-transformation with transformation templates and XSLT as post processing). Further, the EA XSD transformation is not documented very well.
The process overall is highly intransparent over the three steps. It spans three technologies (EA Model-to-Model transformation, EA-XSD transformation, XSLT). Only XSLT is non-propriate.
The propriate EA transformations are not very well documented and incorporate some undocumented "magic" in some steps.

A.2. Code Generation with Templates

With code templates, EA provides code generation capability. There have been successfully implemented code templates to generate valid XSD.

Nevertheless, the approach was discarded due to these drawbacks:

EA uses "languages" like Java, C\++, C' to generate code. A language must have been defined "OSC" and the model must be prepared for this.
Usually Enterprise Architect assumes that every class is generated into its own file. XSD should generate into one file. To achieve this, every class in the model must define the same file name to generate into the same file.
The main reason was that the connectors that are transformed into XSD elements cannot be sorted with the EA template language. So, there was no possibility to reproduce xsd:sequences from the original XSD.

With these drawbacks, this very complex and incomprehensive approach was discarded in favor of the Enterprise Architect scripting approach.

A.3. Enterprise Architect Script Execution

Writing a JScript from the scratch was the approach that was chosen to generate the XSD in one single step. It is by far the most transparent way to generate XSD and uses the well documented object API to the Enterprise Architect model. This approach is also encouraged in the newer versions of Enterprise Architect.

The script gives a complete understanding how the transformation is done and can be debugged. It represents a general approach within the modeling rules that are described in this document. No hidden Enterprise Architect magic and no extra steps to generate XSD.

Scripting enables the validation of modeling rules described in this document and the creation of useful error messages when the modeling rules are violated. E.g.: If the user has not defined a name for a connector or has not defined appropriate cardinality.