Mapping Aspect Models to Asset Administration Shell (AAS) Submodel Templates

The Asset Administration Shell (AAS) and its information model is a widely recognized standard developed by the Industrial Digital Twin Association (IDTA) to express and handle Digital Twins. Central element of the AAS is the concept of Submodels, which describe certain aspects of a Digital Twin.

The SAMM Aspect Meta Model allows to specify aspects of a digital twin and its semantics. The AAS Generator module provides mapping implementations to derive AAS Submodels from SAMM Aspect Models. On the one hand, this allows to integrate SAMM models in AAS environments and on the other hand it allows AAS submodels to be described with rich semantics, as it is possible with SAMM.

Details of the Mapping Concept

In the following section, the mapping rules applied by the generator are explained. The rules apply to SAMM v2.0.0 / v2.1.0 / v2.2.0 and AAS Specification Part 1 V3.0.

In the table below, bold entries denote SAMM model elements, while the plain entries following them are the attributes of the preceding model element.

SAMM AAS Comment

samm:Aspect

aas:Submodel

Generates an aas:Submodel with kind=Template (or kind=Instance if aspect data is supplied). An AssetAdministrationShell referencing the submodel is also created, containing AssetInformation with assetKind=Type (or assetKind=Instance if aspect data is supplied) and the Aspect URN as globalAssetId.

samm:name

aas:Submodel.idShort

All generated idShorts are sanitized to match the AAS idShort pattern [a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+: leading non-letters and invalid characters are removed, trailing hyphens are stripped, single-character results are suffixed with an underscore and empty results fall back to idShort.

samm:preferredName

aas:ConceptDescription.displayName

Mapped to displayName and IEC61360 preferredName on the ConceptDescription of the Aspect. (Not mapped to aas:Submodel.displayName).

samm:description

aas:Submodel.description

Also mapped to description and IEC61360 definition on the ConceptDescription of the Aspect.

samm:property

see samm:Property

samm:operation

see samm:Operation

samm:Aspect.urn

aas:Submodel.semanticId

Also used as the identifier for the ConceptDescription, the AssetAdministrationShell, and the AssetInformation globalAssetId. The aas:Submodel.id is the Aspect URN with the suffix /submodel.

samm:see

aas:Submodel.supplementalSemanticIds, aas:SubmodelElement.supplementalSemanticIds

samm:see references of Aspects, Properties, Operations, Entities and Characteristics are added as external global references to the supplementalSemanticIds of the corresponding aas:Submodel or aas:SubmodelElement. URNs and HTTP(S) URLs are used as they are, bare IRDIs are converted to urn:irdi: references with # encoded as %23, and local file paths are ignored unless their last segment is an IRDI.

samm:Property

aas:Property, aas:SubmodelElementCollection, aas:SubmodelElementList, aas:MultiLanguageProperty, aas:ReferenceElement

The AAS element depends on the SAMM property type: an Entity becomes a SubmodelElementCollection; a Collection type (see Characteristics taxonomy) becomes a SubmodelElementList; a MultiLanguageText becomes a MultiLanguageProperty; a Reference becomes a ReferenceElement. In all other cases, an aas:Property is generated. In template mode, SMT/Cardinality qualifiers (ZeroToOne, One, ZeroToMany, OneToMany) are also attached. Abstract Properties and Properties without a Characteristic are excluded from the mapping.

samm:Property.name

aas:SubmodelElement.idShort

The idShort is derived from the Property’s payloadName, which falls back to the Property name if no payloadName is defined, and is sanitized as described above. SubmodelElements that are direct children of an aas:SubmodelElementList carry no idShort.

samm:Property.urn

aas:ConceptDescription.id, aas:SubmodelElement.semanticId

Always used as the id of the generated ConceptDescription. It is used as semanticId for aas:Property, aas:MultiLanguageProperty and aas:ReferenceElement, and for aas:SubmodelElementList only if the Collection Characteristic is named. For Entity-typed Properties, the semanticId of the aas:SubmodelElementCollection is the Entity URN, and the aas:SubmodelElementList generated for samm-c:Either carries no semanticId.

samm:Property.preferredName

aas:SubmodelElement.displayName

Mapped to displayName on the SubmodelElement. Also mapped to displayName and IEC61360 preferredName on the ConceptDescription.

samm:Property.description

aas:ConceptDescription (IEC61360 definition), aas:SubmodelElement.description

Mapped to aas:DataSpecificationIEC61360.definition of the ConceptDescription. Also mapped to description on complex SubmodelElements (Collection, List, MultiLanguageProperty, ReferenceElement), but omitted on scalar aas:Property.

samm:Property.exampleValue

aas:Property.value

In templates, exampleValue is used as aas:Property.value and added as an SMT/ExampleValue qualifier of kind TemplateQualifier. When data is provided, the real value is used and no qualifiers are generated.

samm:Characteristic.dataType

aas:Property.valueType

Mapped to aas:Property.valueType using a fixed XSD type mapping, where types without explicit mapping default to xsd:string. The dataType of the DataSpecificationIEC61360 in the ConceptDescription is set accordingly, defaulting to STRING. For aas:SubmodelElementList, the typeValueListElement is SubmodelElementCollection in template mode and SubmodelElement when aspect data is supplied; if the element type is an Entity, its URN is used as semanticIdListElement.

samm:Operation

aas:Operation

in/out parameters are not used in SAMM so the mapping only generates input variables and output variables in AAS. A ConceptDescription is also created.

samm-c:Characteristic

aas:SubmodelElement, aas:ConceptDescription

Characteristics in SAMM define the meaning and type of a property. In AAS, type and description are separated. Characteristics help create the SubmodelElements and fill the ConceptDescriptions (with DataSpecificationIEC61360).

samm-c:Collection

aas:SubmodelElementList, aas:ConceptDescription

The general remarks to Characteristics apply also to Collection type Characteristics. Properties referencing Collections (including samm-c:List, samm-c:Set, samm-c:SortedSet, and samm-c:TimeSeries) are mapped to SubmodelElementLists with orderRelevant set to false. Uniqueness and sorting constraints are not represented in AAS. When aspect data is supplied and the element type is a scalar, all values are serialized into a single aas:Blob with content type text/plain and comma-separated values.

samm-c:Quantifiable

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Quantifiable type Characteristics. Quantifiables (also Duration and Measurement) reference a unit, which is added to the ConceptDescription corresponding the mapped Characteristic.

samm-c:Either

aas:SubmodelElementList, aas:ConceptDescription

The Either characteristic has two distinct entries of which one is to be selected. When generating templates, both entries are written to a SubmodelElementList. When generating with instance data, only the present side is generated.

samm-c:Trait

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Trait. However, the constraint of a trait will be ignored and only the base type will be evaluated, which will act as the characteristic of a property.

samm-c:Code

aas:SubmodelElement, aas:ConceptDescription

Similar to plain Characteristic.

samm-c:Reference

aas:ReferenceElement, aas:ConceptDescription

Properties referencing a Reference characteristic are mapped to an aas:ReferenceElement. Its value is an external global reference built from the property value, or from the exampleValue when a template is generated; if neither is available, no value is set.

samm-c:StructuredValue

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to StructuredValue. AAS has no concept like deconstruction rule. Thus, the deconstruction rule is ignored and only the Characteristic is mapped.

samm-c:Enumeration

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Enumerations. Additionally, the values of an Enumeration are mapped to a valueList of a DataSpecificationIEC61360.

samm-c:State

aas:SubmodelElement, aas:ConceptDescription

Same as Enumeration.

samm-c:MultiLanguageText

aas:MultiLanguageProperty, aas:ConceptDescription

Every Property with the data type rdf:langString, as used by MultiLanguageText, is mapped to a MultiLanguageProperty in AAS. Its localized values are taken from the aspect data when it is supplied.

Known Limitations

The AAS Generator implements a base set of features, which are mapped from SAMM to AAS. However, there are still limitations:

  • Predefined entity mapping (FileResource would be mapped to aas:File)

  • samm-c:Either is mapped to aas:SubmodelElementList with two entries for left and right side

  • Recursive optional properties of SAMM model are not included in output but dropped straight away

  • Abstract Properties and Properties without a Characteristic are skipped during mapping

  • Constraints of samm-c:Trait as well as uniqueness and ordering of collections are not represented in AAS

  • Collections of scalar values are represented as a single aas:Blob when aspect data is supplied

Translate Aspect Model to AAS

The following code demonstrates how the API to translate an Aspect Model into one of the valid AAS formats (JSON, XML, AASX) is used:

Show used imports 
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfig;
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfigBuilder;
import org.eclipse.esmf.aspectmodel.aas.AspectModelAasGenerator;
import org.eclipse.esmf.aspectmodel.aas.AasFileFormat;
import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
import org.eclipse.esmf.metamodel.Aspect;
import org.eclipse.esmf.metamodel.AspectModel;
// AspectModel as returned by the AspectModelLoader
final AspectModel aspectModel = // ...

final AasGenerationConfig config = AasGenerationConfigBuilder.builder()
      .format( AasFileFormat.AASX )
      .aspectData( null ) // Optional: Provide a JsonNode representing Aspect data
      .propertyMappers( List.of() ) // Optional: Customize SAMM->AAS property mapping
      .build();
new AspectModelAasGenerator( aspect, config ).generate( this::outputStreamForName );

To include the translator artifact, use the following dependencies:

Maven
<dependency>
    <groupId>org.eclipse.esmf</groupId>
    <artifactId>esmf-aspect-aas-generator</artifactId>
    <version>2.16.0</version>
</dependency>
Gradle Groovy DSL
implementation 'org.eclipse.esmf:esmf-aspect-model-aas-generator:2.16.0'
Gradle Kotlin DSL
implementation("org.eclipse.esmf:esmf-aspect-model-aas-generator:2.16.0")

Translate AAS to Aspect Model

It is also possible to translate AAS Submodel Templates to Aspect Models using a best-effort. The following example shows how the API to translate an AAS environment containing one or more Submodel Templates to Aspect Models:

Show used imports 
import java.io.File;

import org.eclipse.esmf.aspectmodel.aas.AasFileFormat;
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfigBuilder;
import org.eclipse.esmf.aspectmodel.aas.AasToAspectModelGenerator;
import org.eclipse.esmf.aspectmodel.aas.AspectModelAasGenerator;
import org.eclipse.esmf.aspectmodel.generator.AspectArtifact;
import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
import org.eclipse.esmf.metamodel.AspectModel;
final File file = // an AAS file that ends in .aasx, .xml or .json

// Multiple "from" methods are available: fromFile (which checks the file extension),
// fromAasJson, fromAasXml, fromAasx as well as fromEnvironment (for an AAS4J AAS environment)
final AasToAspectModelGenerator generator = AasToAspectModelGenerator.fromFile( file );
generator.generate().map( AspectArtifact::getContent ).forEach( aspect -> {
   // do something with the generated aspect
} );

To include the translator artifact, use the same dependencies as shown above in section Translate Aspect Model to AAS.