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: 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): 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. 1. https://www.w3.org/TR/xmlschema-2/