ConceptDescriptions with IEC61360 Data Specification

Introduction

The Asset Administration Shell provides the means to also define concept descriptions and not only reference external concept definitions via semanticId.

For concept descriptions there are two ways how to do it:

Often this is used to create some shadow copies of dictionary entries but it is also used to define concepts that are not yet defined in any dictionary, ontology of semantic model.

Aspect Models can be referenced via semanticId as explained in Using SAMM element identifiers for AAS semantics. In this section is is described how shadow copies of the concepts defined in Aspect Models can be generated.

The prefix for the rules defined start with "S2C".

Note: IEC61360 and AAS attribute "levelType" is not used in SAMM

ConceptDescriptions for SAMM Properties

In this section the general mapping of a samm:Property to an AAS ConceptDescription with data specification IEC61360 is specified.

Code example: a samm:Property definition
@prefix : <urn:samm:io.admin-shell.idta.example:1.0.0#> .

:latitude a samm:Property ;
   samm:preferredName "latitude"@en ;
   samm:description "The latitude is a geographic coordinate."@en ;
   samm:characteristic :Coordinate ;
   samm:exampleValue "9.1781"^^xsd:decimal .

Mapping to an AAS ConceptDescription:

Code example: samm:Property mapped to AAS ConceptDescription
<conceptDescription>
    <idShort>latitude</idShort>
    <id>urn:samm:io.admin-shell.idta.example:1.0.0#latitude</id>
    <embeddedDataSpecifications>
        <embeddedDataSpecification>
            <dataSpecification>
                <type>ExternalReference</type>
                <keys>
                    <key>
                        <type>GlobalReference</type>
                        <value>https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3</value>
                    </key>
                </keys>
            </dataSpecification>
            <dataSpecificationContent>
                <dataSpecificationIec61360>
                    <preferredName>
                        <langStringPreferredNameTypeIec61360>
                            <language>en</language>
                            <text>latitude</text>
                        </langStringPreferredNameTypeIec61360>
                    </preferredName>
                    <dataType>REAL_COUNT</dataType>
                    <definition>
                        <langStringDefinitionTypeIec61360>
                            <language>en</language>
                            <text>The latitude is a geographic coordinate.</text>
                        </langStringDefinitionTypeIec61360>
                    </definition>
                </dataSpecificationIec61360>
            </dataSpecificationContent>
        </embeddedDataSpecification>
    </embeddedDataSpecifications>
</conceptDescription>
No. Obligation SAMM (Aspect Model) AAS (Submodel Template) Notes

S2C-001

MUST

An embedded data specification with value https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3 MUST be added

S2C-002

should

:<nameOfSAMMProperty> a samm:Property ;

ConceptDescription/idShort: <nameOfSAMMProperty>

It is also possible to use the payload name if existing (compare to S2A-0013) but the idShort of the ConceptDescription is not relevant for the Value-Only payload.

S2C-003

MUST

:<nameOfSAMMProperty> a samm:Property

in namespace <namespace>

ConceptDescription/id: <namespace>#<nameOfSAMMProperty>

Compare to SA-0003

S2C-004

MUST

samm:preferredName

DataSpecificationIec61360/preferredName

Compare to S2A-0004

S2C-005

MUST

samm:description

DataSpecificationIec61360/definition

S2C-006

MUST

samm:dataType

Mapping of effective data type as defined in Table 2

S2C-007

 — 

samm:exampleValue

 — 

Example Values are not supported by the IEC61360 specification so there is no mapping for the samm:exampleValue. See Property samm:optional and samm:payloadName how samm:exampleValues can be handled in the Submodel Template itself

In the following table the mapping of IEC 61360 data types to xsd data types is defined.

Table 1. Mapping of xsd data types to IEC61360 data types
Data Type IEC61360

Core types

xsd:string

STRING

xsd:boolean

BOOLEAN

xsd:decimal and samm:Property is a Measurement

RATIONAL_MEASURE

xsd:decimal and samm:Property is not a Measurement

RATIONAL

xsd:integer and samm:Property is a Measurement

INTEGER_MEASURE

xsd:integer and samm:Property is not a Measurement

INTEGER_COUNT

 — 

INTEGER_CURRENCY

IEEE floating-point numbers

xsd:double or xsd:float and samm:Property is a Measurement

REAL_MEASURE

xsd:double or xsd:float and samm:Property is not a Measurement

REAL_COUNT

 — 

REAL_CURRENCY

Time and dates

xsd:date

DATE

xsd:time

TIME

xsd:dateTime

TIMESTAMP

Recurring and partial dates

xsd:gYear

DATE

xsd:gMonth

DATE

xsd:gDay

DATE

:gYearMonth

DATE

xsd:gMonthDay

DATE

xsd:duration

TIME

Limited-range integer numbers

xsd:byte

Like xsd:integer

xsd:short

Like xsd:integer

xsd:int

Like xsd:integer

xsd:long

Like xsd:integer

xsd:unsignedByte

Like xsd:integer

xsd:unsignedShort

Like xsd:integer

xsd:unsignedInt

Like xsd:integer

xsd:unsignedLong

Like xsd:integer

xsd:positiveInteger

Like xsd:integer

xsd:nonNegativeInteger

Like xsd:integer

xsd:negativeInteger

Like xsd:integer

xsd:nonPositiveInteger

Like xsd:integer

Encoded binary data

xsd:hexBinary

BLOB

xsd:base64Binary

BLOB

Miscellaneous types

xsd:anyURI

IRI

rdf:langString

STRING_TRANSLATABLE

Other

If samm:Property is mapped to a SubmodelElement File

FILE

 — 

HTML

ConceptDescriptions for measurable SAMM Properties

Code example: a measurable SAMM Property
@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.2.0#>.

:temperature a samm:Property ;
   samm:preferredName "temperature"@en ;
   samm:characteristic :Temperature .

:Temperature a samm-c:Measurement ;
   samm:dataType xsd:float ;
   samm-c:unit unit:degreeCelsius .

unit:degreeCelsius a samm:Unit ;
   samm:preferredName            "degree Celsius"@en ;
   samm:commonCode               "CEL" ;
   samm:conversionFactor         "1 × K" ;
   samm:numericConversionFactor  "1.0"^^xsd:double ;
   samm:quantityKind             unit:temperature ;
   samm:referenceUnit            unit:kelvin ;
   samm:symbol                   "°C" .
Code example: a measurable samm:Property mapped to AAS ConceptDescription
<conceptDescription>
    <idShort>temperature</idShort>
    <id>urn:samm:io.admin-shell.idta.example:1.0.0#temperature</id>
    <embeddedDataSpecifications>
        <embeddedDataSpecification>
            <dataSpecification>
                <type>ExternalReference</type>
                <keys>
                    <key>
                        <type>GlobalReference</type>
                        <value>https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3</value>
                    </key>
                </keys>
            </dataSpecification>
            <dataSpecificationContent>
                <dataSpecificationIec61360>
                    <preferredName>
                        <langStringPreferredNameTypeIec61360>
                            <language>en</language>
                            <text>temperature</text>
                        </langStringPreferredNameTypeIec61360>
                    </preferredName>
                    <unit>CEL</unit>
                    <unitId>
                        <type>ModelReference</type>
                        <keys>
                            <key>
                                <type>Submodel</type>
                                <value>urn:samm:org.eclipse.esmf.samm:unit:2.2.0#degreeCelsius</value>
                            </key>
                        </keys>
                    </unitId>
                    <sourceOfDefinition>something_1bd907c8</sourceOfDefinition>
                    <symbol>°C</symbol>
                    <dataType>REAL_MEASURE</dataType>
                    <definition>
                        <langStringDefinitionTypeIec61360>
                            <language>en</language>
                            <text>degree celsius</text>
                        </langStringDefinitionTypeIec61360>
                    </definition>
                </dataSpecificationIec61360>
            </dataSpecificationContent>
        </embeddedDataSpecification>
    </embeddedDataSpecifications>
</conceptDescription>

SAMM elements not mentioned are not mapped.

No. Obligation SAMM (Aspect Model) AAS (Submodel Template) Notes

S2C-007

MUST

samm-c:unit with value unit:<nameOfSAMMUnit>

with "unit:" is the predefined name space of the units

DataSpecificationIec61360/unitId = <namespace of unit>#<NameOfSAMMUnit>

The namespace for units is predefined in SAMM. It is urn:samm:org.eclipse.esmf.samm:unit:<version>

S2C-009

MUST

samm:symbol

DataSpecificationIec61360/symbol = <value of samm:symbol>

and

DataSpecificationIec61360/unit = <value of samm:commonCode>

ConceptDescriptions for samm:Values

Code example: a samm:Value
@prefix : <urn:samm:io.admin-shell.idta.example:1.0.0#> .

:GreenLight a samm:Value ;
   samm:value "green" ;
   samm:preferredName "Normal"@en ;
   samm:description "Indicates that the speed of position change is within specification."@en ;
   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
Code example: a samm:Value mapped to AAS ConceptDescription
<conceptDescription>
    <idShort>GreenLigth</idShort>
    <id>urn:samm:io.admin-shell.idta.example:1.0.0#GreenLight</id>
    <embeddedDataSpecifications>
        <embeddedDataSpecification>
            <dataSpecification>
                <type>ExternalReference</type>
                <keys>
                    <key>
                        <type>GlobalReference</type>
                        <value>https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3</value>
                    </key>
                </keys>
            </dataSpecification>
            <dataSpecificationContent>
                <dataSpecificationIec61360>
                    <preferredName>
                        <langStringPreferredNameTypeIec61360>
                            <language>en</language>
                            <text>GreenLight</text>
                        </langStringPreferredNameTypeIec61360>
                    </preferredName>
                    <dataType>STRING</dataType>
                    <definition>
                        <langStringDefinitionTypeIec61360>
                            <language>en</language>
                            <text> Indicates that the speed of position change is within specification.</text>
                        </langStringDefinitionTypeIec61360>
                    </definition>
                    <value>green</value>
                </dataSpecificationIec61360>
            </dataSpecificationContent>
        </embeddedDataSpecification>
    </embeddedDataSpecifications>
    <isCaseOf>
        <reference>
            <type>ExternalReference</type>
            <keys>
                <key>
                    <type>GlobalReference</type>
                    <value>https://en.wikipedia.org/wiki/Traffic_light</value>
                </key>
            </keys>
        </reference>
    </isCaseOf>
</conceptDescription>
No. Obligation SAMM (Aspect Model) AAS (Submodel Template) Notes

S2C-010

should

:<nameOfSAMMValue> a samm:Value ;

ConceptDescription/idShort: <nameOfSAMMValue>

Compare to S2C-002

S2C-011

MUST

::<nameOfSAMMValue> a samm:Value

in namespace <namespace>

ConceptDescription/id: <namespace><nameOfSAMMValue>#

Compare to SA-0003 and S2C-003

S2C-012

MUST

samm:preferredName

DataSpecificationIec61360/preferredName

Compare to S2A-0004 and S2C-004

S2C-013

MUST

samm:value of a samm-c:Value

DataSpecificationIec61360/value = <value of samm:Value>

ConceptDescriptions for Enumerations with implicit values

Code example: samm-c:Enumeration with implicit values
@prefix : <urn:samm:io.admin-shell.idta.example:1.0.0#> .

:status a samm:Property;
   samm:preferredName "status"@en ;
   samm:characteristic :Status .

:Status a samm-c:Enumeration ;
   samm:dataType xsd:string ;
   samm-c:values ( "Complete" "In Progress" "Created" ) .
Code example: samm-c:Enumeration with implicit values mapped to AAS
<conceptDescription>
    <idShort>status</idShort>
    <administration/>
    <id>urn:samm:io.admin-shell.idta.example:1.0.0#status</id>
    <embeddedDataSpecifications>
        <embeddedDataSpecification>
            <dataSpecification>
                <type>ExternalReference</type>
                <keys>
                    <key>
                        <type>GlobalReference</type>
                        <value>https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3</value>
                    </key>
                </keys>
            </dataSpecification>
            <dataSpecificationContent>
                <dataSpecificationIec61360>
                    <preferredName>
                        <langStringPreferredNameTypeIec61360>
                            <language>en</language>
                            <text>status</text>
                        </langStringPreferredNameTypeIec61360>
                    </preferredName>
                    <valueList>
                        <valueReferencePairs>
                            <valueReferencePair>
                                <value>Complete</value>
                            </valueReferencePair>
                            <valueReferencePair>
                                <value>In Progress</value>
                            </valueReferencePair>
                            <valueReferencePair>
                                <value>Created</value>
                            </valueReferencePair>
                        </valueReferencePairs>
                    </valueList>
                </dataSpecificationIec61360>
            </dataSpecificationContent>
        </embeddedDataSpecification>
    </embeddedDataSpecifications>
</conceptDescription>
No. Obligation SAMM (Aspect Model) AAS (Submodel Template) Notes

S2C-014

MUST

samm-c:Enumeration

DataSpecificationIec61360/valueList

S2C-015

MUST

samm-c:values within samm-c enumeration

with implicit values

per value in samm-c:values:

ValueReferencePair/value

# within a DataSpecificationIec61360/valueList

ConceptDescriptions for Enumerations with explicit values

Code example: samm:Enumeration with explicit values
:trafficLight a samm:Property;
   samm:preferredName "traffic light"@en ;
   samm:characteristic :TrafficLight.

:TrafficLight a samm-c:Enumeration ;
   samm:preferredName "Warning Level"@en ;
   samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
   samm:dataType xsd:string ;
   samm-c:values (
      :GreenLight
   ) .

:GreenLight a samm:Value ;
   samm:value "green" ;
   samm:preferredName "Normal"@en ;
   samm:description "Indicates that the speed of position change is within specification."@en ;
   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
Code example 4: samm-c:Enumeration with explicit values mapped to AAS ConceptDescription
<conceptDescription>
    <idShort>TrafficLight</idShort>
    <administration/>
    <id>urn:samm:io.admin-shell.idta.example:1.0.0#trafficLight</id>
    <embeddedDataSpecifications>
        <embeddedDataSpecification>
            <dataSpecification>
                <type>ExternalReference</type>
                <keys>
                    <key>
                        <type>GlobalReference</type>
                        <value>https://admin-shell.io/DataSpecificationTemplates/DataSpecificationIec61360/3</value>
                    </key>
                </keys>
            </dataSpecification>
            <dataSpecificationContent>
                <dataSpecificationIec61360>
                    <preferredName>
                        <langStringPreferredNameTypeIec61360>
                            <language>en</language>
                            <text>traffic light</text>
                        </langStringPreferredNameTypeIec61360>
                    </preferredName>
                    <valueList>
                        <valueReferencePairs>
                            <valueReferencePair>
                                <value>green</value>
                                <valueId>
                                    <type>ExternalReference</type>
                                    <keys>
                                        <key>
                                            <type>GlobalReference</type>
                                            <value>urn:samm:io.admin-shell.idta.example:1.0.0#GreenLight</value>
                                        </key>
                                    </keys>
                                </valueId>
                            </valueReferencePair>
                        </valueReferencePairs>
                    </valueList>
                </dataSpecificationIec61360>
            </dataSpecificationContent>
        </embeddedDataSpecification>
    </embeddedDataSpecifications>
</conceptDescription>

For the mapping of the samm:Value GreenLight see ConceptDescriptions for samm:Values:

No. Obligation SAMM (Aspect Model) AAS (Submodel Template) Notes

S2C-016

MUST

samm-c:Enumeration

DataSpecificationIec61360/valueList

See S2C-014

S2C-017

MUST

samm-c:values within samm-c enumeration

with explicit values

per value in samm-c:values:

ValueReferencePair/value : <samm:value of samm:Value>

within a DataSpecificationIec61360/valueList

Compare to S2C-015

S2C-018

MUST

samm-c:values within samm-c enumeration

with explicit values

per value in samm-c:values:

ValueReferencePair/valueId : <namespace of samm:Value>#<element name of samm:Value>

within a DataSpecificationIec61360/valueList

In contrast to implicitly defined value lists there MUST be a valueId added to the value.