Data Types for Payload

General

For metamodel elements like AssetAdministrationShell, Submodel, Identifier, etc. that are specified in Part 1 [1], please refer to the specification in Bibliography. The AAS package format and the AAS Package type are defined in Part 5 [3]. This clause only defines additional classes that are needed for communication with the API.

Metamodel Specification Details

The following type definitions are used to describe specific metamodel elements like Asset Administration Shells and submodels regarding their network and deployment configuration. They use certain attributes copied from the model element itself to describe it – hence the name Descriptor.

Descriptor

Class Name

Descriptor

Explanation

The self-describing information of a network resource. This class is not part of the metamodel.

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/Descriptor/3/0

Attribute

Explanation

Type

Card.

description

Description or comments on the element

The description can be provided in several languages

MultiLanguageNameType

0..1

displayName

Display name; can be provided in several languages

MultiLanguageNameType

0..1

extension

An extension of the element

Extension

0..*

AssetAdministrationShellDescriptor

Class Name

AssetAdministrationShellDescriptor

Explanation

Descriptor of an Asset Administration Shell

Inherits from

Descriptor

semanticId

https://admin-shell.io/aas/API/DataTypes/AssetAdministrationShellDescriptor/3/1

Attribute

Explanation

Type

Card.

administration

Administrative information of the Asset Administration Shell

AdministrativeInformation

0..1

assetKind

Denotes whether the asset of the described Asset Administration Shell is of kind “Type” or “Instance”

AssetKind

0..1

assetType

The type of the asset described by the Asset Administration Shell of this Descriptor. See AssetInformation/assetType for further information.

Identifier

0..1

endpoint

Endpoint of the network resource

Endpoint

0..*

globalAssetId

Global reference to the asset the AAS is representing

Identifier

0..1

idShort

Short name of the Asset Administration Shell

NameType

0..1

id

Globally unique identification of the Asset Administration Shell

Identifier

1

specificAssetId

Specific asset identifier

SpecificAssetId

0..*

submodelDescriptor

Descriptor of a submodel of the Asset Administration Shell

SubmodelDescriptor

0..*

Note: the cardinality restriction for AssetAdministrationShellDescriptor/endpoint (optional: 0..*) allows a provider to skip the declaration of the location of an AssetAdministrationShell and directly point to the endpoints of the contained Submodels through the path AssetAdministrationShellDescriptor/submodelDescriptor→ SubmodelDescriptor/endpoint. A client, therefore, might decide to skip the lookup on the AssetAdministrationShell. Nevertheless, in case the information contained in the AssetAdministrationShellDescriptor deviates from the related AssetAdministrationShell, or attributes are missing, the AssetAdministrationShell is always the source of truth.

SubmodelDescriptor

Class Name

SubmodelDescriptor

Explanation

A descriptor of a submodel

Inherits from

Descriptor

semanticId

https://admin-shell.io/aas/API/DataTypes/SubmodelDescriptor/3/1

Attribute

Explanation

Type

Card.

administration

Administrative information of the Submodel

AdministrativeInformation

0..1

endpoint

Endpoint of the network resource

Endpoint

1..*

idShort

Short name of the Submodel

NameType

0..1

id

Globally unique identification of the Submodel

Identifier

1

semanticId

Identifier of the semantic definition of the Submodel

Reference

0..1

supplementalSemanticId

Identifier of a supplemental semantic definition of the element called supplemental semantic ID of the element

Reference

0..*

Endpoint

Class Name

Endpoint

Explanation

The endpoint description of a network resource. This class is not part of the metamodel.

Inherits from

-

semanticId

https://admin-shell.io/aas/API/DataTypes/Endpoint/3/0

Attribute

Explanation

Type

Card.

protocolInformation

Protocol information of the network resource endpoint

ProtocolInformation

1

interface

Name of the offered interface at the endpoint

NameType

1

The following names will be used for the interfaces:

Interface interface-shortName

Asset Administration Shell Interface

AAS

Submodel Interface

SUBMODEL

Serialization Interface

SERIALIZE

AASX File Server Interface

AASX-FILE

Asset Administration Shell Registry Interface

AAS-REGISTRY

Submodel Registry Interface

SUBMODEL-REGISTRY

Asset Administration Shell Repository Interface

AAS-REPOSITORY

Submodel Repository Interface

SUBMODEL-REPOSITORY

Concept Description Repository Interface

CD-REPOSITORY

Asset Administration Shell Basic Discovery Interface

AAS-DISCOVERY

The value for the interface attribute is “{interface-shortName}-{interface-version}”.

The interface-version of this specification is “3.0”, e.g. the entry for the Asset Administration Shell Interface is “AAS-3.0”.

See the following example for a descriptor with several endpoints:

{
  "endpoints": [
    {
      "protocolInformation": {
        "endpointAddress": "https://localhost:1234",
        "endpointProtocolVersion": "1.1"
      },
      "interface": "AAS-3.0"
    },
    {
      "protocolInformation": {
        "endpointAddress": "opc.tcp://localhost:4840"
      },
      "interface": "AAS-3.0"
    },
    {
      "protocolInformation": {
        "endpointAddress": "https://localhost:5678",
        "endpointProtocolVersion": "1.1",
        "subprotocol": "OPC UA Basic SOAP",
        "subprotocolBody": "ns=2;s=MyAAS",
        "subprotocolBodyEncoding": "application/soap+xml"
      },
      "interface": "AAS-3.0"
    }
  ]
}

ProtocolInformation

Class Name

ProtocolInformation

Explanation

The protocol information of a network resource endpoint will be defined in DIN SPEC 16593-2. After the release of DIN SPEC 16593-2, any required updates will be made. This class is not part of the metamodel.

The information in this table is a 1:1 copy from DIN SPEC 16593-2. Required changes need to be made by the related DIN working group.

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/ProtocolInformation/3/0

Attribute

Explanation

Type

Card.

href

The endpoint address as a URL

LocatorType

1

endpointProtocol

Either scheme of endpointAddress or scheme + further information. Scheme denotes the highest level of doubtless transmission.

SchemeType

0..1

endpointProtocolVersion

Array of strings, each entry represents one supported version at this very endpoint, the entry shall be formatted according to the regulations of the protocol specified in the href

LabelType

0..*

subprotocol

Allows for referencing sub-protocols that may be used in the context of that endpoint e.g. “OPC Basic SOAP” or UA Binary

ShortIdType

0..1

subprotocolBody

If the sub-protocol field is present, a subprotocolBody might be given to hold extra information, e.g. node and namespace in an OPC UA server

TextType

0..1

subprotocolBodyEncoding

If subprotocolBody is present, the encoding might be explicitly defined, otherwise it shall default to subprotocols encoding scheme

LabelType

0..1

securityAttributes

Array of securityAttribute objects, each attribute has 3 properties:

{

type = Enum security type or standard:

  • ‘NONE’,

  • 'RFC_TLSA' - TLSA according to rfc6698

  • 'W3C_DID' - W3C DID document ,

key = security attribute key according to standard definitions of the security type,

value = security attribute value e.g. DANE TLSA Ressource Record

}

The securityAttribute objects are treated as possible alternatives (logical “or”)

SecurityAttributeObject

1..*

Class Name

SecurityAttributeObject

Explanation

Security attributes as defined by DIN SPEC 16593-2. After the release of DIN SPEC 16593-2, any required updates will be made. This class is not part of the metamodel.

The information in this table is derived from DIN SPEC 16593-2. Required changes need to be made by the related DIN working group.

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/SecurityAttributeObject/3/0

Attribute

Explanation

Type

Card.

type

Enum security type or standard

SecurityTypeEnum

1

key

Security attribute key according to standard definitions of the security type

string

1

value

Security attribute value e.g. DANE TLSA Ressource Record

string

1

Enumeration

SecurityTypeEnum

Explanation

The security types as defined by DIN SPEC 16593-2. After the release of DIN SPEC 16593-2, any required updates will be made. This class is not part of the metamodel.

The information in this table is derived from DIN SPEC 16593-2. Required changes need to be made by the related DIN working group.

semanticId

https://admin-shell.io/aas/API/DataTypes/SecurityTypeEnum/3/0

Literal

ID

Explanation

NONE

https://admin-shell.io/aas/API/DataTypes/SecurityTypeEnum/NONE/3/0

No predefined security type available

RFC_TLSA

https://admin-shell.io/aas/API/DataTypes/SecurityTypeEnum/RFC_TLSA/3/0

TLSA according to RFC 6698

W3C_DID

https://admin-shell.io/aas/API/DataTypes/SecurityTypeEnum/W3C_DID/3/0

Decentralized Identifiers according to the W3C Recommendation [7]

ServiceDescription

Class Name

ServiceDescription

Explanation

The self-describing information of an API Implementation. It enables servers to present their capabilities to the clients, in particular which profiles they implement. At least one defined profile is required. Additional, proprietary attributes might be included. Nevertheless, the server must not expect that a regular client understands them.

This class is not part of the metamodel.

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/ServiceDescription/3/0

Attribute

Explanation

Type

Card.

profiles

List of implemented server specification profiles.

ServiceSpecificationProfileEnum

1..*

Enumeration

ServiceSpecificationProfileEnum

Explanation

The identifiers of the standardized service specification profiles. See also clause 12.12 for further details.

semanticId

https://admin-shell.io/aas/API/DataTypes/ServiceSpecificationProfileEnum/3/0

hh

Literal

Explanation

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001

Indicates that the server implemented all features of the Asset Administration Shell Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002

Indicates that the server implemented all features of the Asset Administration Shell Service Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001

Indicates that the server implemented all features of the Submodel Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-002

Indicates that the server implemented all features of the Submodel Service Specification Value Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003

Indicates that the server implemented all features of the Submodel Service Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AasxFileServerServiceSpecification/SSP-001

Indicates that the server implemented all details of the AASX File Server Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-001

Indicates that the server implemented all details of the Asset Administration Shell Registry Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002

Indicates that the server implemented all details of the Asset Administration Shell Registry Service Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-003

Indicates that the server implemented all details of the Asset Administration Shell Registry Service Specification Bulk Profile in version 3.1.

https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-001

Indicates that the server implemented all details of the Submodel Registry Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002

Indicates that the server implemented all details of the Submodel Registry Service Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/1/SubmodelRegistryServiceSpecification/SSP-003

Indicates that the server implemented all details of the Submodel Registry Service Specification Bulk Profile in version 3.1.

https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001

Indicates that the server implemented all details of the Discovery Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-001

Indicates that the server implemented all details of the Asset Administration Shell Repository Service Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002

Indicates that the server implemented all details of the Asset Administration Shell Repository Service Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-001

Indicates that the server implemented all details of the Submodel Service Repository Specification Full Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-002

Indicates that the server implemented all details of the Submodel Service Repository Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-003

Indicates that the server implemented all details of the Submodel Service Repository Specification Read Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-004

Indicates that the server implemented all details of the Submodel Service Repository Specification Template Profile in version 3.0.

https://admin-shell.io/aas/API/3/0/ConceptDescriptionServiceSpecification/SSP-001

Indicates that the server implemented all details of the Concept Description Service Specification Read Template Profile in version 3.0.

An example ServiceDescription object might look like the following, indicating that the server supports two profiles at the same time (see Clause 12.12.3 for further details on service specifications and profiles):

{
  "profiles": [
    "https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001",
    "https://admin-shell.io/aas/API/3/0/RegistryServiceSpecification/SSP-002"
  ]
}

Simple Data Types

All simple data types from Part 1 [1] apply also to the specifications described in this document. Additional data types are defined in Table 2.

Table 1. Simple Data Types used for API-specific Classes
Primitive Definition Value Examples

NonNegativeInteger

The nonNegativeInteger datatype as defined by XML Schema Part 2 in version 1.0 [1]

0

42

Primitive Data Types

All primitive data types from Part 1 apply also to the specifications described in this document. All constraints and spelling patterns apply as well. In addition, the following data types are defined.

Table 2. Primitive Data Types used for the API-specific Classes
Primitive Definition Value Examples

CodeType

string with max 32 and min 1 characters

“409”

“Bad_UserAccessDenied”

ShortIdType

same as NameType (string with max 128 and min 1 characters)

Note: ShortIdType is not the data type of idShort attributes but for IDs which shall be shorter than the identifier type.

“02063059-b81c-482b-97d1-d29cbe382ef6”

“my-random-id”

LocatorType

string with max 2048 and min 1 characters

“https://example.org/”

“https://provider-edc.data.plane/v3.0/shells/aas-1/submodels/submodel-1/submodel”

TextType

string with max 2048 and min 1 characters

“asset:prop:id=123;idsEndpoint=http://edc.control.plane/”

SchemeType

same as NameType (string with max 128 and min 1 characters)

“HTTP”

Status Code, Error Handling & Result Messages

This clause deals with the error and result handling of an operation’s execution in a technology-independent manner.

The first clause covers generic status codes that are returned on each request, independent of the operation’s success or failure. The subsequent clause describes the result object that is returned in case of failure.

Generic Status Codes

Successful operations return one of the success status codes and their respective payload. Unsuccessful operations return one of the failure status codes and a result object as defined in Clause 0.

Table 4 shows generic status codes returned to the requester. Additionally, the table indicates whether a specific status code comes with a result object in the returned payload.

Table 3. Status Codes
Generic Status Code Meaning Has Result Object

Success

Success

No

SuccessCreated

Successful creation of a new resource

No

SuccessAccepted

The reception of the request was successful

No

SuccessNoContent

Success with explicitly no content in the payload

No

ClientErrorBadRequest

Bad or malformed request

Yes

ClientNotAuthorized

Wrong or missing authorization credentials

Yes

ClientForbidden

Authorization has been refused

Yes

ClientMethodNotAllowed

Operation request is not allowed

Yes

ClientErrorResourceNotFound

Resource not found

Yes

ClientResourceConflict

Conflict-creating resource (resource already exists)

Yes

ServerInternalError

Unexpected error

Yes

ServerErrorBadGateway

Bad gateway

Yes

General Result Object

In case of a failed operation execution, a result object shall be returned containing more information about the reasons why the operation failed to execute.

Class Name

Result

Explanation

The result object

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/Result/3/0

Attribute

Explanation

Type

Card.

message

Additional message containing information for the requester

Message

0..*

Class Name

Message

Explanation

A message containing more information for the requester about a certain happening in the backend

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/Message/3/0

Attribute

Explanation

Type

Card.

messageType

The message type

MessageTypeEnum

1

text

The message text

string

1

code

Technology-dependent status or error code

CodeType

0..1

correlationId

Identifier to relate several result messages throughout several systems

ShortIdType

0..1

timestamp

Timestamp of the message

dateTime

0..1

Enumeration

MessageTypeEnum

Explanation

The message type

semanticId

https://admin-shell.io/aas/API/DataTypes/MessageTypeEnum/3/0

Literal

Explanation

Info

Used to inform the user about a certain fact

Warning

Used for warnings; warnings may lead to errors in the subsequent execution

Error

Used for handling errors

Exception

Used in case of an internal and/or unhandled exception

Operation Objects

The following type definitions are used to call and handle the requests and responses while performing synchronous or asynchronous operation invocation.

OperationRequest

Class Name

OperationRequest

Explanation

The operation request object

Inherits from

 — 

semanticId*

https://admin-shell.io/aas/API/DataTypes/OperationRequest/3/0

Attribute

Explanation

Type

Card.

inputArguments

Input argument

OperationVariable

0..*

inoutputArguments

InOutput argument

OperationVariable

0..*

clientTimeoutDuration

Duration indicating when the client expects the server to have finished execution of the invoked operation

duration

0..1

BaseOperationResult

Class Name

BaseOperationResult

Explanation

The object containing the intermediate state of an operation

Inherits from

Result

semanticId

https://admin-shell.io/aas/API/DataTypes/BaseOperationResult/3/0

Attribute

Explanation

Type

Card.

executionState

Execution state

ExecutionState

1

success

Flag indicating whether the business operation behind the operation was successful (true) or not (false)

boolean

0..1

OperationResult

Class Name

OperationResult

Explanation

The operation’s invocation result object

Inherits from

BaseOperationResult

semanticId

https://admin-shell.io/aas/API/DataTypes/OperationResult/3/0

Attribute

Explanation

Type

Card.

outputArguments

Output argument

OperationVariable

0..*

inoutputArguments

InOutput argument

OperationVariable

0..*

Enumeration ExecutionState

Enumeration

ExecutionState

Explanation

The operation’s invocation result state

semanticId

https://admin-shell.io/aas/API/DataTypes/ExecutionState/3/0

Literal

Explanation

Initiated

The operation is ready to be executed (initial state)

Running

The operation is running

Completed

The operation is completed

Canceled

The operation was cancelled externally

Failed

The operation failed

Timeout

The operation has timed out due to given client or server timeout

OperationHandle

Class Name

OperationHandle

Explanation

The returned handle of an operation’s asynchronous invocation used to request the current state of the operation’s execution

Inherits from

 — 

semanticId

https://admin-shell.io/aas/API/DataTypes/OperationHandle/3/0

Attribute

Explanation

Type

Card.

handleId

Handle ID

ShortIdType

1

File Content

The “File Content” type of the operations mentioned above is seen as “arbitrary binary data” according to RFC 2046 and is as such defined as byte-array in UTF8-encoding. If a content type is required, “application/octet-stream” must be used as defined in RFC 2046.