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.

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

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

image
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]*
image
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]*
image
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.

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

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

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

image

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.

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

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

image

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.

image

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

image

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.

image

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.

image

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.

image

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.

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

image
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"