Mappings (normative)

Some mappings or serializations convert the type "Reference" into a single string. In this case, the following serialization is required:

Grammar:

Valid Examples:

External References:

Model References:

In many cases, applications using data from Asset Administration Shells already know the Submodel regarding its structure, attributes, and semantics. Consequently, there is not always a need to receive the entire model information, which can be requested separately via Content modifier set to Metadata, in each request since it is constant most of the time. Instead, applications are most likely only interested in the values of the modelled data. Furthermore, having limited processing power or limited bandwidth, one use case of this format is to transfer data as efficiently as possible. Semantics and data might be split into two separate architecture building blocks. For example, a database would suit the needs for querying semantics, while a device would only provide the data at runtime. Two separate requests make it possible to build up a user interface (UI) and show new upcoming values highly efficiently.

Values are only available for

Capabilities are excluded from the serialization scope since only data containing elements are in the focus. They are consequently omitted in the serialization.

The following rules shall be adhered to when serializing a submodel, a submodel collection or a submodel element list with the format "Value"^[2]:

The following rules shall be adhered to when serializing a single submodel element with the format "Value":

Submodel elements defined in the submodel other than the ones mentioned above are not subject to the Value-Only serialization.

Optional elements (like for example globalAssetId for an Entity submodel element) with no value shall be omitted in the serialization.

The serialization of submodel element values is described in the following table. The left column "Data Type" shows the data types which can be used for submodel element values. The data types are defined according to the W3C XML Schema (https://www.w3.org/TR/xmlschema-2/#built-in-datatypes and https://www.w3.org/TR/xmlschema-2/#built-in-derived). "Value Range" further explains the possible range of data values for this data type. The right column comprises related examples of the serialization of submodel element values.

The following types defined by the XSD and RDF specifications are explicitly omitted for serialization - they are not element of DataTypeDefXsd or DataTypeDefRdf:

xs:language, xs:normalizedString, xs:token, xs:NMTOKEN, xs:Name, xs:NCName, xs:QName, xs:ENTITY, xs:ID, xs:IDREF, xs:NOTATION, xs:IDREFS, xs:ENTITIES, xs:NMTOKENS, rdf:HTML and rdf:XMLLiteral.

(See https://datatracker.ietf.org/doc/html/rfc8259#section-6)

The following example shows the JSON Value-Only serialization for a Submodel with name "Example" and two direct SubmodelElements "ProductClassifications" and "MaxRotationSpeed". "ProductClassifications" is represented by a SubmodelElementList with SubmodelElementCollections as its elements. Each of the SubmodelCollections has two mandatory elements "ProductClassificationSystem" and "ProductClassId" and one optional element "ProductClassificationVersion". All of these elements have data type "xs:string". "MaxRotationSpeed" is a property with data type "xs:int".

The JSON Value-Only serialization for the element "ProductClassifications", a SubmodelElementList, within the submodel above looks like this:

The JSON Value-Only serialization for the first element, a SubmodelElementCollection, within the "ProductClassifications" list above looks like this:

The JSON Value-Only serialization for the Property "MaxRotationSpeed" of the submodel above looks like this:

The Format "Normal" in comparison to this Value-Only serialization of the property "MaxRotationSpeed" would look like this:

In the following examples for Value-Only serializations for all submodel element types are given.

For a single Property named "MaxRotationSpeed", the value-Only payload is minimized to the following (assuming its value is 5000):

For a SubmodelElementCollection named "ProductClassification" or being part of a list "ProductionClassifications", the Value-Only payload is minimized to the following, i.e. the name of the SubmodelElementCollection or its index in the list is not part of the Value-Only serialization:

For a SubmodelElementList named "Authors" with string Properties as its value, the Value-Only payload is minimized to the following (values within a SubmodelElementList do not have idShort values)^[5]:

For a MultiLanguageProperty the Value-Only payload is minimized to the following:

For a Range named "TorqueRange", the Value-Only payload is minimized to the following:

For a ReferenceElement named "MaxRotationSpeedReference", the Value-Only payload is minimized to the following:

For a File named "Document", the Value-Only payload is minimized to the following:

For a Blob named "Library", there are two possibilities for the Value-Only payload. In case the Blob value - that can be very large - shall not be part of the payload, the payload is minimized to the following^[6]:

In the second case the Blob value is part of the payload.^[7], there is an additional attribute containing the base64-encoded value:

For a RelationshipElement named "CurrentFlowsFrom", the Value-Only payload is minimized to the following:

For an AnnotatedRelationshipElement named "CurrentFlowFrom", with an annotated Property-DataElement "AppliedRule", the Value-Only-payload is minimized to the following:

For an Entity named "MySubAssetEntity", the Value-Only-payload is minimized to the following:

For a BasicEventElement named "MyBasicEvent", the Value-Only-payload is minimized to the following:

Before we look into how to represent instances of classes, let us start bottom-up and see first how individual properties are represented.

We represent each property of a class with an XML element whose name corresponds to the property in the metamodel. The name is given in camel-case where all abbreviations are left as capitalized (dataSpecificationIec61360 instead of dataSpecificationIEC61360).

It is common in UML to use singular form for aggregations, which is the case for the metamodel. This is, however, in contrast to programming code, where plural form for sequences is common. Since the naming of XML elements has direct influence on the programming code, we name the properties in plural form diverging from the name in the metamodel. For example, submodelElements instead of submodelElement in case of Submodel/submodelElement property in the metamodel.

In cases where plural form made no sense for a property, we kept it as-is in singular form (e.g., isCaseOf). The full list of exceptions is available as code in aas-core-meta.

While some metamodel properties are indeed very apt to be succinctly represented as XML attributes, we decided not to use XML attributes at all for three reasons.

First, the XML attribute must be a string, and therefore does not allow for structured data to be represented with it. As the metamodel evolves, we need to be able to gracefully evolve the schema with as little breakages as possible. An XML attribute puts a limit in so far that an attribute can only be represented as string. Moreover, as the schema evolves, making diff’s is important to trace the changes. This is much harder when the attributes switch from an XML attribute to an XML element.

Second, many classes contain a mix of primitive properties and structured properties. If we allowed XML attributes, the former would be represented as XML attributes, while the latter would be represented as XML elements. This leads to confusion where the writer is forced to go back and forth in the specification, and always double-check whether a property should be represented as an XML attribute or an XML element.

Third, we automatically generate the schema from a machine-readable metamodel representation (see Section Background below). The mix of XML attributes and elements would have complicated the code and prolonged the development.

We finally decided that the drawbacks outlined above outweighed the advantage in form of succinct representation.

If a property has cardinality 0..1 or 0..* and is not specified in the instance, the element is simply omitted.

The property values given in the metamodel as simple data types (see Section Primitive Data Types) are serialized as text enclosed in the XML element corresponding to the property. Please see Section Why no XML attributes? on why we do not serialize them as XML attributes.

The byte arrays (BlobType in metamodel) are serialized as Base64-encoded text.

Simple type rdf:langString is serialized as if it were a proper metamodel class with properties language and text. See the following Section Instances of Classes as Property Values about how to serialize instances of classes in general as that section directly applies to rdf:langString.

To serialize instances of metamodel classes as values of properties, we need to nest them somehow within the XML element corresponding to the property. This is not as trivial as it seems.

If the property type is a concrete or abstract class with descendants, the deserializer needs to know the exact concrete class at the time of de-serialization. However, this information is obviously missing in the metamodel. For example, the property Submodel/submodelElement tells the deserializer that its items are instances of SubmodelElement, but the deserializer does not know which concrete deserialization method to apply to understand the nested XML data: is it Property , Range or some other descendant of SubmodelElement?

Therefore, the information about the concrete type of the serialized instance must be encoded somehow in XML when the type in the metamodel is too vague. This nugget of information is usually called a discriminator (e.g., see OpenAPI 3 specification on polymorphism).

On the other hand, when the metamodel mandates the type of property as a concrete class without descendants, the deserializer needs no additional information as the deserialization method is given by the metamodel. There is thus no need to include the discriminator in the serialization, and a redundant discriminator would only clutter the XML document.

We therefore distinguish two serializations of instances: one with discriminator, and one without, respectively.

Many properties in the metamodel do not represent a single value (be it primitive or structured as a class), but aggregate instances of metamodel classes. For example, Submodel/submodelElement aggregates instances of SubmodelElement’s.

If we just concatenated all the properties of the instances, we would not know which property belongs to which instance (or such distinction would be complicated). We need a delimiter!

Following the approach described in Section Instances Serialized with Discriminator, we delimit the instances simply by nesting them beneath the discriminator elements. If the type of the list items is a concrete class, we nest beneath the discriminator element regardless.

For example, here is an XML snippet of an example submodel elements, where the first element is a Property, the second one is a Range and the third is a Property:

We explicitly forbid empty lists in XML to avoid confusion about properties of cardinality 0..*. Namely, an empty list is semantically equal to an omitted property (according to the metamodel). Thus, the XML element representing an aggregation must be omitted if the aggregation is empty.

The following snippet is therefore invalid:

… and should be written as:

We fixed the order of the properties to match the metamodel for readability.

This is reflected in usage of xs:sequence throughout the XML schema.

Enumerations are serialized according to the exact values of enumeration literals in the metamodel as text.

For example, the enumeration literal EntityType/CoManagedEntity is serialized as CoManagedEntity, while the literal Direction/input as input.

There is an abstract definition of data specifications as templates in the metamodel (see Section Data Specification Templates). This definition does not specify, though, how to access them from within an Environment, which is a requirement for many systems. To address this practical issue, the metamodel indicates that they should be embedded in serializations (see Section Embedded Data Specifications).

We therefore add additional XML element, named embeddedDataSpecifications, in the XML representations of HasDataSpecification class, and omit dataSpecification property by design. The embedded data specifications are serialized just as all the other classes of the metamodel, following the procedure outlined above.

The XML elements representing the AAS model are explicitly required to live in our namespace. The namespace corresponds to the version of the metamodel.

For example, the serialization for the metamodel V3.0RC02 lives in the namespace https://admin-shell.io/aas/3/0/RC02.

When we started with the project, the schema had been manually written. One or two schema designers would sit down, follow the book and translate it into XML schema by best effort. This allowed for a lot of artistic freedom, but eventually caused problems due to mismatches with other serializations or internal inconsistencies. Especially as the metamodel evolved, maintaining the schema and keeping it up-to-date with the metamodel proved to be difficult.

While the handwritten schema is arguably elegant, the maintenance is too demanding. Therefore, we developed a schema generator based on the machine-readable representation of the metamodel. The generator is provided in aas-core-codegen project, while the metamodel lives in aas-core-meta.

This allowed us to evolve the XML schema more quickly while keeping it in sync with other serialization schemas and SDKs. However, we had to give up on elegant parts of the schema, and had to straightjacket the schema into form that can be programmatically generated. For example, all properties are serialized as XML elements, and we could not use XML attributes.

For each class of the AAS metamodel, we provide a definition in the JSON schema. The instances of the classes, abstract and concrete alike, are modeled as JSON objects.

The class properties of the metamodel (attributes and aggregations) correspond directly to JSON properties.

Optional attributes, i.e., the attributes with the cardinality 0..1, are modeled as non-required properties.

Aggregations, i.e., the properties with the cardinality 0.., 1.. etc., are modeled as JSON arrays.

We explicitly forbid empty JSON arrays to avoid confusion about properties which have cardinality 0..*. Namely, an empty array is semantically equal to an omitted attribute (according to the metamodel). Thus, the JSON property representing an aggregation attribute must be omitted if the aggregation is empty.

In UML, it is the convention to name associations and aggregations in singular form. The cardinality is to be taken into account to decide on whether there are none, a single or several elements in the corresponding association or aggregation. In JSON, it is best practice to use plural form for array in class properties. The singular name is used for its discriminator (see section on discriminators). Typically, the plural name is derived by just adding an "s" to the name. For example, submodelElements instead of submodelElement in case of Submodel class.

If plural form made no sense for a property, we kept it as-is (e.g., isCaseOf). The full list of exceptions is available as code in aas-core-meta.

The UML specification uses XSD types. For the mapping of XSD to JSON types please refer to Section Format "Value" (Value-Only Serialization) in JSON.

There are the following exceptions:

Property/value and Range/min and Range/max are mapped to a JSON string. The type it needs to be converted to by the data consumer is declared in Property/valueType or Range/valueType, resp.

Primitive type BlobType (group of `byte`s) is mapped to a JSON string with base64 encoding.

Note: in valueOnly Format value has the JSON type as declared in Property/valueType taking the mapping of XSD to JSON types into account.

The inheritance relationships between the classes are modeled using allOf composition. While JSON schema knows no inheritance, we enforce through allOf that all the properties of the parent are defined in the descendants.

Many attributes in the metamodel refer to an abstract class. When we de-serialize such attributes, we need to know the concrete class at runtime, since otherwise the de-serialization algorithm would not know how to interpret the properties of the object.

For example, consider the attribute Submodel which contains instances of SubmodelElement. When the de-serializer encounters the property submodelElements as an array and starts de-serializing its items, how can it know which constructor to call to parse the item? This necessary nugget of information is commonly called ``discriminator'' (e.g., see OpenAPI 3 specification on polymorphism).

We define the discriminator for our serialization as an additional property, modelType , which do not correspond to any attribute in the metamodel. Every class which has one or more descendants will have the discriminator modelType in its definition.

When a deserializer needs to de-serialize an instance of an abstract class, it can do so by dispatching the de-serialization to the appropriate de-serialization method based on modelType.

The enumerations of the metamodel are directly mapped to enumerated values in JSON schema. Each enumeration is defined separately, and we do not in-line enumerations for readability.

Enumerations which are not directly used in the schema are omitted. For example, subsets of KeyTypes are omitted since only KeyTypes is used to define value of an attribute.

The metamodel defines data specifications in abstract (see Section Data Specification Templates). However, the metamodel omits data specifications in an Environment, and data specifications are intentionally non-identifiable.

For practical applications, we need to access them somehow. Therefore, the metamodel mandates to embed them in serializations (see Section Embedded Data Specifications).

We consequently embed the data specifications by adding embeddedDataSpecifications property to the definition corresponding to HasDataSpecification, and deliberately omit the attribute HasDataSpecification/dataSpecification in the schema.

The serialization to and from JSON changed over the course of different versions of the metamodel. Originally, the schema had been manually designed, where a group of authors combed "the book" and manually transcribed it to JSON schema. This was obviously error-prone as it often caused mismatches between other serializations (e.g., XML and RDF), contained inconsistencies etc.

We eventually moved over to generate the serialization schemas based on a single-point-of-truth. The current source is aas-core-meta, a domain-specific Python representation of the metamodel. The schemas are generated using aas-core-codegen, a translating tool which transpiles aas-core-meta into different schemas and other targets such as SDKs.

While this approach reduced the rate of errors significantly, it also imposed certain limits on our schema design. For example, the classes and enumerations are now programmatically mapped to JSON definitions, allowing for no exceptions. Where we could in-line some of them for better readability, we are now forced to stick with the programmatic definitions.