search

admin-shell-io / questions-and-answers

This repository aims for providing answers to often asked questions in the context of the Asset Administration Shell.
https://admin-shell-io.github.io/questions-and-answers/
Creative Commons Attribution 4.0 International
25 stars 6 forks source link

readme

Asset Administration Shell Frequently Asked Questions List

Disclaimer

This Q&A has been initially created by a Task Force of "ZVEI SG Modelle und Standards". It now is maintained by the IDTA Workstream "Best Modeling Practice".

Primary URI for end-user usage and references is: https://admin-shell-io.github.io/questions-and-answers/, cross-link single questions as follows https://admin-shell-io.github.io/questions-and-answers/#id18

Please address discussions and proposals via issues and pull requests in the github repository: https://github.com/admin-shell-io/questions-and-answers/

FAQ

Assets and Asset Types

Asset Administration Shell

Submodels and Submodel Templates

SubmodelElements

Identification

Referencing

Infrastructure and Versioning

AAS Registry

Semantics / ECLASS

Answers

How to define optional and mandatory elements for a submodel of kind=Template?

Currently (September 2021) there is no clean solution for that. Plattform Industrie 4.0 is evaluating different modeling options.

As a temporary workaround we propose to use the qualifier name is "Multiplier" with values "One", "ZeroToOne", "ZeroToMany", "OneToMany" as done by many practitioners defining submodel templates.

How should submodel templates (kind=Template) and submodel instances (kind=Instance) be linked together?

The submodel template with kind=Template and the submodel instance with kind=Instance should have the same semanticID to indicate the applicability of the template on the instance.

How does the version of a submodel impact referencing of a submodel?

AAS provides two approaches for versioning:

1) Versioning within semantic ID, e.g., for URIs "0173-xxx-zzz-zzz#version" or "https://admin-shell.io/sandbox/zvei/nameplate/0/1/Nameplate":

2) Changes within "administrative information" within AAS:

As of now, references ignore versioning information. In case versioning is essential, the versioning information must be part of the element's ID.

How to use isCaseOf to indicate 'alternative' semanticIDs of AAS elements?

Note: This answer is only valid for V2 of the meta-model. We work on re-phrasing it for V3.

This AAS example contains a template of "Technical Data" submodel with two properties indicating how alterantive semantic IDs can be used in AAS modeling. For example, the "ManufacturerName" property, has a semantic ID "https://admin-shell.io/sandbox/SG2/TechnicalData/ManufacturerName/1/1" and two isCaseOf references to a ECLASS and a CDD IRDIs (the references are within the ConceptDescription).

What are best practices for creating a system of Asset Administration Shells?

There are currently two ways to create/reference further AAS: 1) Using a BOM (Bill of Material) submodel, a dedicated submodel with self- or co-managed assets

Note: Scope of the BOM submodel are relations between assets and not AASs. BOM submodel defined “isPartOf” and “isIdentical” relation types between assets.

    Advantages: BOM-AAS is self-contained and has no “external” dependencies such as references to AAS, probably will be used as blueprint for further submodels.

    Disadvantages: AAS infrastructure for resolution of asset ID to AAS is needed.

2) Direct references to external AAS or Submodels using ReferenceElements or RelationshipElements. We currently do not recommend this method in case of lacking generalizability and creation of tight couplings between AAS (by taking over the “resolution” part).

(Answered: 2021-06-28)

How shall a link to a website be entered in an AAS, as File or as ReferenceElement object?

Links to websites shall be entered as File object (physical reference). ReferenceElement objects represent logical references. A typical usage for logical references is in the description of a topology of the asset or „consist of” hierarchies.

(Answered: 2020-08-13)

If the same properties are used in several submodels, shall they also be entered several times or shall they be referenced?

Submodels shall be as independent as possible so that they can be changed and developed separately. Consequently, the same properties shall be copied to another submodel and references shall not be used in such case. The concept description referenced in semanticId, however, should be the same.

(Answered: 2020-08-13)

How to use physical units for quantifiable properties?

AAS defines specific constructs of unit and unitID for concept descriptions (template DataSpecificationIEC61360). We advise you to use unitIDs that refer to pre-defined ECLASS IRDIs, e.g., 0173-1#05-AAA480#002 for millimeters. In a non-likely case of non-existent global IRDI for a unit, please follow the general guidance for custom semantic IDs to create a custom unitID.

(Answered: 2020-08-13)

What shall be entered for the semanticId attribute if a related concept description does not exist in ECLASS or IEC CDD?

Besides ECLASS and IEC CCD also other domain specific dictionaries may be used. The only prerequisite is that the id can be uniquely resolved.

This also holds true for proprietary dictionaries. For example, the id of a proprietary concept description defined by your own company could be //”. This id is also used as semanticId of the property then.

Alternatively, an agile flexible approach using GITHUB has been defined. You may store your CDs there which are defined as “http://admin-shell.io/[/[/]]/”. The working draft repository is placed at https://github.com/admin-shell-io/id.

(Answered: 2020-08-13)

How shall the ECLASS group “Zusatzdokumentation (e.g. IRDI 0173-1#02-ADN464#..)” be used for documentation?

Please use the submodel template based on VDI 2770 for documentation instead. It will be released soon.

(Updated: 2020-08-14)

How to treat values of Properties with values in multiple languages?

Details of the Asset Administration Shell Part 1 provides the MultiLanguageProperty entity for this case since version 2.0.

(Answered: 2020-08-13)

How shall a document be handled which includes different content according to VDI 2770 and the related DocumentClassIDs?

Currently, VDI 2770 only allows exactly one DocumentClassID per document. A proposal has been already made to the VDI 2770 workgroup to extend this. In AAS it is suggested to list several properties with different DocumentClassIDs for such a multipurpose document.

(Answered: 2020-08-13)

Which names are already defined for important submodels?

The following names shall be used for submodels:

(Answered: 2020-08-13)

How to store certificates and conformance declarations within AAS/Submodels?

A dedicated submodel with IdShort “CertificatesAndDeclarations” with ID https://admin-shell.io/submodels/CertificatesAndDeclarations is proposed. This model shall contain boolean properties or text-properties indicating conformance to certificates. Actual certificate documents, e.g., scanned TÜV reports, shall be contained in the “Documentation” submodel and referenced from “CertificatesAndDeclarations” elements.

Examples are the boolean property 0173-1#02-BAF053#008 set to true if a CE qualification is present, or the text-property 0173-1#02-AAE327#001 for a textual name of the fulfilled conformance.

(Answered: 2020-08-13)

Which mechanisms can be used to structure complex data?

Collections can be used to “physically” separate and structure submodel elements into different topics.

Qualifiers can be used to add additional meta-information to AAS elements that is not included in the model of AAS. Currently (Details of AAS Part 1 Version 2), concrete qualifiers are not specified, however the document provides some non-normative examples for qualifiers: e.g. the indication of a lifecycle state of a value by “as-specified” or “as-measured”, or e.g. the indication of multiplicity of allowed components for modelling by “greater than 0” and others.

(Answered: 2020-08-13)

Where are examples of AAS available?

Examples of several suppliers are found at: http://admin-shell-io.com/samples/

(Answered: 2020-08-13)

What are best practices for creating custom IRI identifiers for generic concepts?

What are best practices for creating custom IRI identifiers for generic concepts. We advise using “https://admin-shell.io/” prefix for those identifiers (see guides via https://github.com/admin-shell-io/id/) for generic concepts. Note that we advise to use “https:” protocol and avoid adding “www.” subdomain into admin-shell.io naming scheme. Furthermore, in practical implementations we advise to “filter” out protocol and schema for comparing IRI identifiers. For example, following IDs should be considered equal:

(Answered: 2020-08-19)

Which submodel shall contain the serial number of a device?

Serial number is a submodel element of “Identification” submodel referenced in AAS for an asset with assetKind=Instance, i.e. instance’s AAS.

(Answered: 2020-08-19)

How to refer to semantic concepts of existing standards like VDI 2770 properties or OPC UA companion specifications (e.g. “Serial number” property from OPC UA DI companion spec)?

Map concepts to “admin-shell.io” namespace (see custom identifier best practices). Within the concept description itself use “sourceOfDefinition” or “isCaseOf” to link to “original” concept.

(Answered: 2020-08-24)

Are there any best practices how to choose the idShort of an element?

For choosing an idShort value there are the following recommendations (rules and order can be used for automatically creation of an idShort):

In case a submodel template specification is used as a base, the idShort defined in this submodel template shall be used.

Note: the isShort does not carry any semantic meaning. For speaking names the display name shall be used.

(Updated: 2021-05-17)

I need a speaking name on my dashboard - which attribute value shall I use?

For speaking names (in different languages) the display name (Referable/displayName) shall be used.

If no display name is defined in the language requested by the application, then the display name is selected in the following order if available:

Note: DisplayName was introduced with Part 1, V3.0RC01. Display name is optional.

(Updated: 2021-05-17)

Where shall images (products or icons) of an asset be stored, e.g., for the use in dashboards?

With V3.0RC01 of Part 1 an optional attribute "assetInformation/defaultThumbnail" was introduced. The type of this attribute is "File".

The standardized submodel template "Generic Frame for Technical Data for Industrial Equipment in Manufacturing" (Version 1.1) allows to add as many product images as needed (https://admin-shell.io/ZVEI/TechnicalData/Productimage/1/1). Again, the type of these images is "File".

(Updated: 2021-02-08)

How shall properties be entered which are defined both in ECLASS and in CDD?

Note: This answer is only valid for V2 of the meta-model. We work on re-phrasing it for V3.

If definitions for several product application areas are needed (e.g. ECLASS for factory automation and CDD for process automation), the related properties (e.g. ManufacturerName) shall be entered twice. At each of the properties one of the concept descriptions (ECLASS or CDD) is entered. The name of a property shall be either counted up (e.g. ManufactureName1) or extended by a suffix (e.g. ManufacturerNameCDD).

Alternatively an own concept description may be defined and "isCaseOf" may be used, so that both IRDIs can be entered in the concept description.

(Answered: 2020-09-21)

Is the following IRI-based ID with a query parameter valid “http://vendor.com/suffx?a=abc&b=xyz”?

Yes, this is a valid ID.

(Answered: 2020-09-21)

What is the relationship between text serialization of "Reference" and other serializations like json or xml?

For xml, json or rdf serializations just have a look at https://github.com/admin-shell-io/aas-specs/tree/master/schemas/xml/examples/generated/reference or https://github.com/admin-shell-io/aas-specs/tree/master/schemas/json/examples/generated/Reference or https://github.com/admin-shell-io/aas-specs/tree/master/schemas/rdf/examples/generated/Reference resp.

Now lets have a look at some of the examples given in the IDTA-01001-3-0 Metamodel specification for text serializations:

(Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title

This is identical to the JSON representation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "Submodel",
            "value": "https://example.com/aas/1/1/1234859590"
          }
          {
            "type": "SubmodelElementList",
            "value": "Documents"
          }
          {
            "type": "SubmodelElementCollection",
            "value": "0"
          }
          {
            "type": "MultiLanguageProperty",
            "value": "Title"
          }
        ],
        "type": "ModelReference"
      },

[ExternalRef](GlobalReference)0173-1#02-BAA120#008

is identical to the JSON representation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "GlobalReference",
            "value": "0173-1#02-BAA120#008"
          }
         ],
        "type": "ExternalReference"
      },

[ModelRef](ConceptDescription)0173-1#02-BAA120#008 is identical to the JSON represenation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "ConceptDescription",
            "value": "0173-1#02-BAA120#008"
          }
         ],
        "type": "ModelReference"
      },

The corresponding xml representation would look like this:

<attribute with Type 'Reference'>
   <type>ModelReference</type>
     <keys>
        <key>
          <type>ConceptDescription</type>
          <value>0173-1#02-BAA120#008</value>
        </key>
      <keys>
</attribute with Type 'Reference'>

There is a third way of building paths to model elements. In Part 2 API of the AAS Specification there are so-called "idShort-Paths" defined (see Chapter 12.4 in V3.0 Addressing Resources). For the example

(Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title

we would have the idShort-Path

Documents[0].Title

Using it in an http/REST call needs base64url encoding for identifiers and URL encoding for idShort-Paths leads to GET /submodels/<Base64URL encoded https://example.com/aas/1/1/1234859590>/submodel/submodelElements/<URL encoded Documents[0].Title> i.e. GET /submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMS8xLzEyMzQ4NTk1OTA/submodel/submodelElements/Documents%5B0%5D.Title

(Answered: 2024-02-06)

When are two references considered to match?

For the matching algorithm see chapter on "Matching Strategies": "Matching Algorithm for References" in Part 1 of the Specification of the Asset Administration Shell. Also examples are given.

(Answered: 2024-02-06)

Are semanticId(s) optional or mandatory?

Although semanticIds are optional it is recommended to add a semantic reference (semanticId) whenever possible: without semanticId there is no semantic interoperability. IdShort of elements can be standardized as is done for some elements in submodel templates. However, this is not sufficient. Additionally, a semanticId is needed, for example to include version information or information about variants about the same element.

Sometimes there is no standardized concept description available in ECLASS or IEC CDD. See the answer to this question for how to deal with this case.

In AAS Part 1 V3.0RC01 semanticId(s) are not mandatory for submodels or submodel elements. SemanticId(s) are recommended to be added for submodel instances and submodel elements.

Up to AAS Part 1 V2.0 semanticId(s) were mandatory for submodel elements and were recommended for submodels with kind=Instance. For submodels with kind=Template the semanticId was optional.

(Updated: 2021-02-08)

Can semantic ID(s) be used without defining a concept description within the AAS package?

[update: In V3.0RC01 of part 1 of AAS in Detail the attribue "local" in References was removed]

Yes. Please use the following alternatives:

(Answered: 2021-12-13)

Is it allowed to have both, Submodel Templates and Submodel Instances, in the same AAS?

Submodel Templates guide the creation of Submodel Instances. Although the specification does not restrict an Asset Administration Shell to contain both, Submodels with kind=Template and Submodels with kind=Instance, it is good practice to separate Submodel Templates from Submodel Instances. Typically, the owners of and the life cycle for creating and maintaining Submodel Templates are different from the owners of and from creating and operating Submodel Instances.

(Answered: 2021-01-08)

How should I name a submodel element if there are more than one with the same semanticId?

There are several ways to deal with the topic of naming in the case that there is a set of elements (Referable/idShort), each with the same semanticId (for example in a SubmodelElementCollection with allowDuplicated=True):

Note: It is requested that the idShort of a non-identifiable is unique in its name space (for example in a Submodel or in a SubmodelElementCollection). This is not requested for the display names!

(Answered: 2021-01-11)

How to treat ECLASS Quantity Concept in AAS?

Example why quantities are needed additionally to units to automatically check compatibility of two properties: The unit "Newtonmeter" can be linked to the quantity "torque" but also to the quantity "energy". Only if the quantity is the same a conversion of the property value is possible.

The metamodel of the AAS (status: V3.0RC01) does not explicitly support the concept of quantities. This means, in case properties are not defined in ECLASS or in any other standardized dictionary it is not possible to specify the quantity of this proprietary property. In case the property is defined in ECLASS then the quantity is defined implicitly, because it is defined in ECLASS itself.

Future versions of the AAS might support quantities:

Please be aware: the AAS does not support the concept of alternative units (as does IEC 61360 or ECLASS): it is assumed that the unit specified is also the unit that is used.

In general: The aim of the basic AAS concept is not about defining semantics, it is about referencing concept descriptions. Support of corresponding data specifciations is optional anyway.

(Answered 2021-01-11)

How should array data values within the AAS be represented if array elements have the same semantic ID?

Pre 3.0 version of the metamodel: Use "Blob"-element, e.g., "[1,2,3,4,5]" having a "serialized" JSON-value format (see upcoming time series submodel template). The data types of array's content, e.g. string, float or integer, can be defined using custom semantic ID of the submodel element. (Design decision: take "Blob" instead of String in order not to overload generic UIs with representation of possibly long arrays.)

Since 3.0 verison of the meamodel: Submodel Element List element should be used, cf. "5.3.7.17 Submodel Element List Attributes" of AASiD Part 1 3.0

(Answered 2021-05-31, updated 2023-06-19)

How to use qualifiers?

In this Repository, you can find a qualifier example in the folder "Examples". It contains an AAS (Qualifier_Examples.aasx) with a Submodel called "QualifierExampleSubmodel".

  1. In this Submodel the property "MaxRotationSpeed" has two example qualifiers (ExpressionSemantic=ASSURANCE_1 and PredicateRelation=GREATER_THAN_0). They are extracted from DIN SPEC 92000 and state that the Submodel assures, that the asset's MaxRotationSpeed is greater than 30 1/min.
  2. Besides that, the Submodel contains the Submodelelementcollection "Width_LifeCycle", which contains the Property width three times. Based on IEC 62569-1:2017, the property "width" might need different values during the assets life cycle. In the example, there are three slightly different values for "As Specified", "As Built" and "As Decomissioned" (life cycle qual=SPEC, life cycle qual=BUILT, life cycle qual=DECOM). You may find further information about this concept in the IEC Common Data Dictionary

Further information on qualifiers and the usage in the AASx Package Explorer can be found in the specific screencast on qualifiers

(Answered 2021-05-31)

Is there a comprehensive list of submodel templates available?

There is a list of submodels coming from IDTA (both finalized and under development) available here: https://industrialdigitaltwin.org/en/content-hub/submodels.

(Answered 2022-03-21)

Is it possible to determine submodel kind (i.e., Template or Instance) from a Registry without loading the actual submodel, e.g. via the AAS-repository API?

Currently submodel kind can not be retrieved using Registry-API. This issue will be addressed by standardization working groups. In the meantime, we propose to maintain a dedicated registry for submodel templates within the AAS-infrastructure. Submodel templates can be part of a "singleton-AAS" with a dedicated asset ID used to collect those.

(Answered 2022-03-21)

Is it possible to determine the semanticID of a submodel from an AAS Server or an AAS Repository Server without loading the actual submodel? 

Yes, it is possible if the data provider add the "referredSemanticId" to the reference to the submodel within the AAS. Example:

```json
  "submodels": [
    {
      "keys": [
        {
          "type": "Submodel",
          "value": "urn:another-example03:8ad569a7"
        }
      ],
      "referredSemanticId": {
        "keys": [
          {
            "type": "GlobalReference",
            "value": "https://admin-shell.io/zvei/nameplate/2/0/Nameplate"
          }
        ],
        "type": "ExternalReference"
        },
      "type": "ModelReference"
    }
```

(Answered: 2024-02-06)

Is there a submodel for modeling of kinematics?

Q: Common file formats for this information already exist (e.g. URDF files) - so perhaps the intention is for this information to simply be referenced or added as supplementary files in the AAS? In any case, some guidance on the best practice would be useful.

A: We are not aware of any dedicated kinematic models within AAS. Embedding files within submodels is always possible using "File" submodel elements with dedicated semantic IDs, as it is, for example, done within the MTP submodel proposal.

Furthermore, kinimatics can be included as part of the "simulation handover" submodel, see current state of the submodel definition.

(Answered 2022-06-13)

Is there an example using a Bill of Material (BOM) submodel to create an AAS for a product/machine which comprises several other assets?

An example of modeling is provided in the following submodel template specification. Example submodels are available here. For additional information see also another question.

(Answered 2024-11-18)

How to deal with property values including multiple values?

Q: How to deal with "property values" that include a set of values, e.g. seperated by comma? Examples are colors in RGB, coordinates, etc. Is there a specific format for these property elements? How can one transport that a specific format is required? Could one use the formula qualifier as RegEx to describe the allowed format? What about more complex property values, i.e. structs?

A: Currently multi-value properties are not available in the metamodel. As option SME list can be used.

(Answered 2022-08-12)

How to define concrete semantics for arbitrary submodel elements based on generic semantics?

Q: In different submodels one may use different concrete concepts which are based on a generic concept symantics. If we consider, for example, a generic "position" Submodel Element Collection (SMC) with simple properties for the coordinates with data type double, e.g., X, Y, and Z with a dedicated semantic id. However, during the modeling individual semanticIds referncing to this generic position concept are needed depending on the usage to allow a concrete, context-dependent meaning. Example: A robot has a position SMC for its base and one for its tool center point. Both should be described by individual semanticIds (i.e., concept descriptions). On the other hand, both describe locations, which should be able to be offset against each other in generic program code (e.g., calculate distance of the locations). How is this possible without a common data type "position" for both SMC?

A: We recommend:

Furthermore, consider re-using existent IEC 61360-compatible concept descriptions, e.g., ECLASS "AXIS 1D".

(Answered 2023-12-18)

How to define non-physical/non-SI units for properties in AAS?

Q: Is there a best practice approach to define units for properties which are not a physical or SI unit? For example in an purchase order in which five pallets of a product are ordered, there is a property "OrderQuantity"=5 and the unit would be "pallet". Should the unit in such cases be defined in the IEC 61360, even if SI-based units are recommended to use, or rather in a separate property of type string called, e.g., "OrderQuantityUnit"?

A: The concept of units is independent of whether they are physical or non-physical. It is preferable to define your property with its corresponding value, for example, 'height' with a 'value=5' and to use the DataSpecificationIec61360. The DataSpecificationIec61360 provides additional properties including 'unit' (e.g., "km") and 'unitID' (e.g., 0173-1#05-AAA595#004). The unitID allows to find the definition of the unit. Multiple international catalogs for Units of Measure exist, e.g., ECLASS, IEC CDD, UNECE. The UNECE catalog includes, e.g., "dozen piece", "pallet". An updated version of a DataSpecification for Units of Measure is underway and will be published shortly. This will provide additional attributes for describing units.

We consider creating an alterntive, separate property for the unit, e.g., "height_unit" an antipattern. This modelling approach can be commonly found in solutions that are not based on the IEC 61360. It is also used in some Submodel Templates. While this gives the author more modelling freedom, it has a poorer semantic quality. In the latter approach, the tools require implicit knowledge that the value of Property A is the unit of Property B.

How to define the relationship between asset instance and asset type wrt. corresponding submodels?

For AAS, the relation "derivedFrom" should be used. For assets, since meta-model V3, there is an attribute AssetInformation/assetType that may hold the globalAssetId of the type asset (for Assets with assetKind = Instance).

(Answered 2024-11-15)

Can RDF be used as an interchange format?

Q: RDF in the form of Turtle files is presented in the documentation as one option for presentation of AAS data for semantic purposes. However the "Details of the Asset Administration Shell" document refers to the AAS serializations packaged in an AASX file as "either json or xml". I would be interested in knowing if this is intentional or if RDF/Turtle should be considered equal to json or xml for exchange purposes.

A: To our knowledge, JSON/XML can be "lossless" converted to RDF. We consider RDF to be a suitable format for more enhanced applications, e.g. requiring complex queries. So it is just that the focus is a little bit different when to use which format.

The RDF scheme/OWL files (.ttl files) are maintained in the repository “aas-spec” of the github project admin-shell-io: https://github.com/admin-shell-io/aas-specs/tree/master/schemas/rdf. The mapping rules how to derive the RDF schema from the technology neutral meta model as defined in this specification can be found here: https://github.com/admin-shell-io/aas-specs/tree/master/schemas/json#json-mapping-rules. Example files can be found here: https://github.com/admin-shell-io/aas-specs/tree/master/schemas/rdf/examples.

(Answered 2022-08-15)

Values for externalSubjectId within SpecificAssetId?

Q: What values shall be used for externalSubjectId within SpecificAssetId?

A: Not all specific IDs shall be visible to all users when looking up Asset Administration Shells. For exam-ple, there typically is a manufacturer-part-ID, but several customer-part-IDs and only the customer shall be able to search for the digital twin via this specific asset ID. The term "subject" is taken from ABAC (Attribute Based Access Control). It is assumed that the "subject" can be described by a unique ID.

 {"name": "SerialNumber", "value": "12345678", "externalSubjectId": ""} //discoverable for everyone
{"name": "CustomerPartID", "value": "C1#7234", "externalSubjectId": "BPN_Company1"} //discoverable for Company 1
{"name": "CustomerPartID", "value": "0789_Company2", "externalSubjectId": "BPN_Company2"} //discoverable for Company 2

(Answered 2023-06-18)

How to use ValueIDs?

Q: How should ValueIDs be using within Submodels to model to model ENUMS from IEC 61360-based semantic dictionaries like CDD and ECLASS?

A: In scope of AAS modeling, the concept of ValueIDs should be used to map those ENUMS. Typically enum values have a string representation and an IRDI for unique identification. AAS specs state the following usage guide:

Constraint AASd-007: if both, the value and the valueId are present then the value needs to be identical to the value of the referenced coded value in valueId.

Which can be seen in the example of "IP65" (IEC 61360 english preffered name) as value. Preferred name should be English only - translation can be done by a look-up of the IRDI if needed.

example

We encourage using both the string value and the equivalent ValueID to provide best human and machine-readability. The IRDI of the value list itself should be used in submodel template definitions to restrict the allowed string values.

(Answered 2022-08-15)

Should one use ECLASS application classes to define semantics of a submodel?

No, see the cited document (page 29). New defined elements in ECLASS to define Submodels should be used once available. The only exception is to use application/classification classes in submodels is to denote the category of a product (see ProductClassId property example within the TechnicalData Submodel template).

(Answered 2022-08-15)

How to use different versions of the same submodel (e.g. different versions of the "digital nameplate") which share same IdShort?

A: In the current API specification AAS Part 2 V3.0.3 the unique base64url-encoded Submodel Id is expected for a GET /submodels/{submodelIdentifier} and no longer the Submodel IdShort. This enables distinguishing between the particular submodel instance.

(Answered 2024-11-15)

What are the right attribute values for 'Descriptor/endpoints'?

A: The interface attribute shall contain the interface identifier together with a version tag. The protocolInformation object contains additional information, e.g., the endpoint URL where the implemented interface is located (href). endpointProtocol states which protocol shall be used. It is intended for clients to select the proper socket library without needing to parse the href content.

The endpointProtocolVersion contains the major.minor version of the endpointProtocol entry. For HTTP, versions 1.0, 1.1, or 2.0 are possible entries. In case several versions of the stated protocol can be served, a list of the respective ones can be added in the value array.

Furthermore, the values for the securityAttributes are required by the DIN SPEC 16593-2. However, as long as DIN SPEC 16593-2 definitions are not available in more details, a common usage pattern is not available and dummy values are recommended ("NONE" or null).

Example for a Submodel endpoint:

{ 
  ...
  "endpoints": [
    { 
      "interface": "SUBMODEL-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/submodel"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    }
  ]
}

Example for a Submodel endpoint providing different API versions:

{
  ...
  "endpoints": [
    { 
      "interface": "SUBMODEL-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/submodel"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    },
    { 
      "interface": "SUBMODEL-3.1" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.1/submodel"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    }
  ]
}

The endpoint descriptions for repository services look slightly different. Note that the href entry should not end with the /submodel or /submodels suffix but at the submodel identifier position. This is due to the fact that the endpoint declaration of a submodel descriptor always targets the location of the respective submodel and not the one of the hosting server/repository.

Therefore, the interface entry is critical for the client to construct the correct endpoints for the different API Operations on top of the submodels.

Example for a Submodel provided through a submodel repository:

{ 
  ...
  "endpoints": [
    { 
      "interface": "SUBMODEL-REPOSITORY-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/submodels/submodel-123"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    }
  ]
}

A service implementing a complete profile, e.g. "https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-002" (only READ API Operations), may want to outline the location of the additionally required APIs (Serialization and Description). Each of the endpoints is therefore stated in an own entry in the endpoints array. In particular for the Serialization API, it is good practice to already include all needed parameters - "submodelIds" or additionally "aasIds" for an AAS Repository - to simplify the call for the clients.

Example for a Submodel provided through a submodel repository in conjunction with the Serialization and Description APIs:

{ 
  ...
  "endpoints": [
    { 
      "interface": "SUBMODEL-REPOSITORY-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/submodels/c3VibW9kZWwtMTIz"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    },
    { 
      "interface": "DESCRIPTION-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/description"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: "1.1",
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    },
    { 
      "interface": "SERIALIZE-3.0" ,
      "protocolInformation": { 
          "href": "https://<hostname>/path-to-submodel/api/v3.0/serialization?submodelIds=c3VibW9kZWwtMTIz"
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    }
  ]
}

In case the endpoints are provided in conjunction with other specifications, e.g., in dataspaces, the remaining fields can be used to provide more information to the client. In particular, the subprotocol shall state which combination of AAS with which other specification is used. In case IDS connectors control the access to AAS endpoints, DSP (read like "AAS over the Dataspace Protocol") can be used. The subprotocolBody can for instance provide information on dataspace-specific data asset identifiers as well as authorisation endpoints.

Example for a Submodel endpoint which is offered through a dataspace connector:

{
  ...
  "endpoints": [
    { 
      "interface": "SUBMODEL-3.0",
      "protocolInformation": {
          "href": "https://provider-edc.data.plane/some-submodel/api/v3.0/submodel",
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion: [ "1.1" ],
          "subprotocol": "DSP",
          "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/",
          "subprotocolBodyEncoding": "plain",
          "securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
      }
    }
  ]
}

(Answered 2023-6-02)

What are strategies to match semantic IDs?

Q: What are strategies to match semantic IDs?

A: Please refer to section "4.4 Matching Strategies" of AASiD part 1 v3.0. Also, the consensus of our group is that isCaseOf has no impact on semantic equivalence and can be ignored for automatic matching strategies.

(Answered 2023-06-19)

Asset Administration Shell in Detail Series

Overview over all parts and versions