Service Specifications and Profiles

Figure in Clause General defines that a service specification contains at least one API and that an API contains at least one API Operation.

The profiles defined in this clause present complete service specifications and their subsets.

For instance, the profile “RepositoryServiceSpecification/V3.1_SSP-002” contains the API Operation “GetAllSubmodels” but not “PostSubmodelElementByPath”, while the more comprehensive “RepositoryServiceSpecification/V3.1_SSP-001” contains both. Furthermore, profiles also define which of the SerializationModifiers (content, extent, level) or serialization formats (JSON) can be used or whether pagination or asynchronous operations are available.

Table 1. Overview of Service Specifications and the Contained APIs
Contained APIs: Service Specifications: Asset Administration Shell API Submodel API AASX File Server API Asset Administration Shell Registry API Submodel Registry API Asset Administration Shell Repository API Submodel Repository API Concept Description Repository API Asset Administration Shell Basic Discovery API Serialization API Description API

Asset Administration Shell Service Specification

x

s

x

x

Submodel Service Specification

x

x

x

AASX File Server Service Specification

x

x

Asset Administration Shell Registry Serv. Spec.

x

s

x

Submodel Registry Service Specification

x

x

Discovery Service Specification

x

x

Asset Administration Shell Repository Serv. Spec.

s

s

x

s

x

x

Submodel Repository Service Specification

s

x

x

x

ConceptDescription Repository Service Spec.

x

x

x

x: Service Specification contains API at the root

s: Service Specification contains API through superpaths as introduced in Clause 0

Profiles

Service specifications are further refined in profiles, governing which API operations, modifiers, and path combinations are supported. The following clauses describe each service specification and present their predefined profiles. Each profile is unambiguously identified and represented through a normative OpenAPI document. The different OpenAPI profiles of one ServiceSpecification share the same title attribute but with different versions. The version attribute contains both the major and minor version as well as the profile identifier. A profile identifier is defined as:

https://admin-shell.io/aas/API/3/0/<service specification name>/SSP-<profile number>

The name of the service specification ends with "ServiceSpecification".

The supported service specification or profile can be discovered at the /description endpoint. This endpoint will return the related profile string.

Additional profiles might be introduced in future versions of this document.

Note: in the following, only the last part (<name of service specification>/SSP-<profile number>) is used in the text for better readability, e.g. “AssetAdministrationShellServiceSpecification/SSP-001” instead of “https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001”.

Asset Administration Shell Service Specification

Service Specification / Profiles Description

AssetAdministrationShellServiceSpecification/SSP-001

Full feature set

AssetAdministrationShellServiceSpecification/SSP-002

Only read operations; is included in the profile AssetAdministrationShellServiceSpecification/SSP-001.

Asset Administration Shell Service Specification – Full Profile

The Asset Administration Shell service specification with all its features and endpoints is represented through the profile identifier AssetAdministrationShellServiceSpecification/SSP-001:

Name: AAS Full Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

Asset Administration Shell API:
GetAssetAdministrationShell
PutAssetAdministrationShell
GetAllSubmodelReferences
PostSubmodelReference
DeleteSubmodelReference
GetAssetInformation
PutAssetInformation
GetThumbnail
PutThumbnail
DeleteThumbnail

Submodel API as superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath
PutFileByPath
DeleteFileByPath
PutSubmodel
PatchSubmodel
PostSubmodelElement
PostSubmodelElementByPath
PutSubmodelElementByPath
PatchSubmodelElementByPath
DeleteSubmodelElementByPath
InvokeOperationSync
InvokeOperationAsync
GetOperationAsyncStatus
GetOperationAsyncResult

Serialization API:[.underline]#
#GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Asset Administration Shell Service Specification – Read Profile

The Asset Administration Shell Service specification with the minimal feature set is represented through AssetAdministrationShellServiceSpecification/SSP-002:

Name: AAS Read Profile

Profile Identifier:

https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/V3.1_SSP-002

Feature

Appearance

API Operations

Asset Administration Shell API:
GetAssetAdministrationShell
GetAllSubmodelReferences
GetAssetInformation
GetThumbnail

Submodel API as superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Service Specification

Service Specification / Profiles Description

SubmodelServiceSpecification/SSP-001

Full feature set

SubmodelServiceSpecification/SSP-002

Only reads operations; is included in the profile SubmodelServiceSpecification/SSP-001.

SubmodelServiceSpecification/SSP-003

Limitation on the basic capabilities plus the option to execute synchronous operations and to read the submodel in the ValueOnly-serialization format to reduce required bandwidth; is included in the profile SubmodelServiceSpecification/SSP-001.

Submodel Service Specification – Full Profile

The submodel service specification with all its features and endpoints is represented through SubmodelServiceSpecification/SSP-001:

Name: Submodel Full Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

Submodel API:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath
PutFileByPath
DeleteFileByPath
PutSubmodel
PatchSubmodel
PostSubmodelElement
PostSubmodelElementByPath
PutSubmodelElementByPath
PatchSubmodelElementByPath
DeleteSubmodelElementByPath
InvokeOperationSync
InvokeOperationAsync
GetOperationAsyncStatus
GetOperationAsyncResult

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Service Specification – Read Profile

The submodel service specification with its minimal feature set is represented through SubmodelServiceSpecification/SSP-002:

Name: Submodel Read Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

Submodel API:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Service Specification – Value Profile

The submodel service specification with a reduced feature set is represented through SubmodelServiceSpecification/SSP-003:

Name: Submodel Value Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

Description API:
GetDescription

SerializationModifier

Level: Deep

Content: Normal, Value

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

not supported

AASX File Server Service Specification

Service Specification / Profiles Description

AasxFileServerServiceSpecification/SSP-001

The full feature set of the AASX File Server Service Specification

AASX File Server Service Specification – Full Profile

Name: AASX File Server Full Profile

Profile Identifier

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

Feature

Appearance

APIs and API Operations

SerializationModifier

not applicable

SerializationFormat

JSON for descriptions and error messages

AASX for packages

Pagination

supported

Asset Administration Shell Registry Service Specification

Service Specification / Profiles Description

AssetAdministrationShellRegistryServiceSpecification/SSP-001

Full profile

AssetAdministrationShellRegistryServiceSpecification/SSP-002

Only reads operations; is included in the profile AssetAdministrationShellRegistryServiceSpecification/SSP-001.

AssetAdministrationShellRegistryServiceSpecification/SSP-003

Bulk write and delete operations.

Asset Administration Shell Registry Service Specification – Full Profile

Name: Asset Administration Shell Registry Full Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Supported

Asset Administration Shell Registry Service Specification – Read Profile

Name: AAS Registry Read Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

supported

Asset Administration Shell Registry Service Specification – Bulk Profile

Name: AAS Registry Bulk Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Not supported

Submodel Registry Service Specification

Service Specification / Profiles Description

SubmodelRegistryServiceSpecification/SSP-001

Full profile

SubmodelRegistryServiceSpecification/SSP-002

Only reads operations; is included in the profile SubmodelRegistryServiceSpecification/SSP-001.

SubmodelRegistryServiceSpecification/SSP-003

Bulk write and delete operations.

Submodel Registry Service Specification – Full Profile

Name: Submodel Registry Full Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

__Submodel Registry API:
GetAllSubmodelDescriptors
GetDescription
PostSubmodelDescriptor
PutSubmodelDescriptorById
DeleteSubmodelDescriptorById

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

supported

Submodel Registry Profile – Read Profile

Name: Submodel Registry Read Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Supported

Submodel Registry Profile – Bulk Profile

Name: Submodel Registry Bulk Profile

Profile Identifier:

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

Feature

Appearance

APIs and API Operations

Submodel Registry API:
PostBulkSubmodelDescriptors
PutBulkSubmodelDescriptorsById
DeleteBulkSubmodelDescriptorsById

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Not Supported

Discovery Service Specification

Service Specification / Profiles Description

DiscoveryServiceSpecification/SSP-001

Full feature set

DiscoveryServiceSpecification/SSP-002

only read operations; does not contain the deprecated read operation from DiscoveryServiceSpecification/SSP-001

Discovery Service Specification – Full Profile

Name: Discovery Service Full Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

AAS Basic Discovery API:
GetAllAssetAdministrationShellIdsByAssetLink (<<deprecated>>)
SearchAllAssetAdministrationShellIdsByAssetLink
GetAllAssetLinksById
PostAllAssetLinksById
DeleteAllAssetLinksById

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Not supported

Discovery Service Specification – Read Profile

Name: Discovery Service Full Profile

Profile Identifier:

https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-002

Feature

Appearance

API and API Operations

AAS Basic Discovery API:
SearchAllAssetAdministrationShellIdsByAssetLink
GetAllAssetLinksById

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Not supported

Asset Administration Shell Repository Service Specification

Service Specification / Profiles Description

AssetAdministrationShellRepository
ServiceSpecification/SSP-001

Full feature set

AssetAdministrationShellRepository
ServiceSpecification/SSP-002

Only read operations; is included in the profile AssetAdministrationShellRepositoryServiceSpecification/SSP-001

Asset Administration Shell Repository Service Specification – Full Profile

Name: AAS Repository Full Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

AAS Repository API:
GetAllAssetAdministrationShells
GetAssetAdministrationShellById
GetAllAssetAdministrationShellsByAssetId
GetAllAssetAdministrationShellsByIdShort
PostAssetAdministrationShell
PutAssetAdministrationShellById
DeleteAssetAdministrationShellById

AAS API by superpath:
GetAssetAdministrationShell
PutAssetAdministrationShell
GetAllSubmodelReferences
PostSubmodelReference
DeleteSubmodelReference
GetAssetInformation
PutAssetInformation
GetThumbnail
PutThumbnail
DeleteThumbnail

Submodel Repository API by superpath:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort
PostSubmodel
PutSubmodelById
DeleteSubmodelById

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath
PutFileByPath
DeleteFileByPath
PutSubmodel
PatchSubmodel
PostSubmodelElement
PostSubmodelElementByPath
PutSubmodelElementByPath
PatchSubmodelElementByPath
DeleteSubmodelElementByPath
InvokeOperationSync
InvokeOperationAsync
GetOperationAsyncStatus
GetOperationAsyncResult

AAS Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Asset Administration Shell Repository Service Specification – Read Profile

Name: AAS Repository Read Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

AAS Repository API:
GetAllAssetAdministrationShells
GetAssetAdministrationShellById
GetAllAssetAdministrationShellsByAssetId
GetAllAssetAdministrationShellsByIdShort

AAS API by superpath:
GetAssetAdministrationShell
GetAllSubmodelReferences
GetAssetInformation
GetThumbnail

Submodel Repository API by superpath:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Repository Service Specification

Service Specification / Profiles Description

SubmodelRepositoryServiceSpecification/SSP-001

Full feature set

SubmodelRepositoryServiceSpecification/SSP-002

Only read operations; is included in the profile SubmodelRepositoryServiceSpecification/SSP-001

SubmodelRepositoryServiceSpecification/SSP-003

Profile for a Submodel Repository which only contains Submodels with kind=Template; is not included in the profile SubmodelRepositoryServiceSpecification/SSP-001 or the profile SubmodelRepositoryServiceSpecification/SSP-002

SubmodelRepositoryServiceSpecification/SSP-004

Only read operations for a Submodel Repository which only contains Submodels with kind=Template; is included in the profile SubmodelRepositoryServiceSpecification/SSP-003 but not in the profile SubmodelRepositoryServiceSpecification/SSP-001 or the profile SubmodelRepositoryService Specification/SSP-002

Submodel Repository - Full Profile

Name: Submodel Repository Full Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

Submodel Repository API:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort
PostSubmodel
PutSubmodelById
PatchSubmodelById
DeleteSubmodelById

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath
PutFileByPath
DeleteFileByPath
PutSubmodel
PatchSubmodel
PostSubmodelElement
PostSubmodelElementByPath
PutSubmodelElementByPath
PatchSubmodelElementByPath
DeleteSubmodelElementByPath
InvokeOperationSync
InvokeOperationAsync
GetOperationAsyncStatus
GetOperationAsyncResult

AAS Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Repository – Read Profile

Name: Submodel Repository Read Profile

Profile Identifier

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

Feature

Appearance

API and API Operations

Submodel Repository API:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata, Value, Reference, Path

Extent: WithBLOBValue, WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Repository - Template Profile

The Submodel Repository service specification that only provides and manages Submodel Templates is represented through the profile identifier SubmodelRepositoryServiceSpecification/SSP-003.

Constraint AASa-003: A service implementing the SubmodelServiceSpecification/SSP-003 must not accept or provide any Submodel with the attribute “kind=Instance”.

Note 1: due to Constraint AASa-003, SubmodelServiceSpecification/SSP-003 can not be combined with SubmodelServiceSpecification/SSP-001 or SubmodelServiceSpecification/SSP-002 as SubmodelService

Specification/SSP-001 or SubmodelServiceSpecification/SSP-002-compliant services may contain Submodel instances but SubmodelServiceSpecification/SSP-003 not.

Note 2: future versions may introduce a Submodel Repository Instance Profile.

Name: Submodel Repository Template Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

Submodel Repository API:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort
PostSubmodel
PutSubmodelById
PatchSubmodelById
DeleteSubmodelById

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath
PutFileByPath
DeleteFileByPath
PutSubmodel
PatchSubmodel
PostSubmodelElement
PostSubmodelElementByPath
PutSubmodelElementByPath
PatchSubmodelElementByPath
DeleteSubmodelElementByPath

AAS Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata

Extent: WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Submodel Repository - Template Read Profile

The Submodel Repository service specification that only provides Submodel Templates is represented through the profile identifier SubmodelRepositoryServiceSpecification/SSP-004.

Constraint AASa-004: A service implementing the SubmodelServiceSpecification/SSP-004 must not accept or provide any Submodel with the attribute “kind=Instance”.

Note: due to Constraint AASa-004, SubmodelServiceSpecification/SSP-004 can not be combined with SubmodelServiceSpecification/SSP-001 or SubmodelServiceSpecification/SSP-002 as SubmodelService

Specification/SSP-001 or SubmodelServiceSpecification/SSP-002-compliant services may contain Submodel instances but SubmodelServiceSpecification/SSP-004 not.

Name: Submodel Repository Template Read Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

Submodel Repository API:
GetAllSubmodels
GetSubmodelById
GetAllSubmodelsBySemanticId
GetAllSubmodelsByIdShort

Submodel API by superpath:
GetSubmodel
GetAllSubmodelElements
GetSubmodelElementByPath
GetFileByPath

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

Level: Core, Deep

Content: Normal, Metadata

Extent: WithoutBLOBValue

SerializationFormat

JSON

Pagination

supported

Concept Description Repository Service Specification

Service Specification / Profiles Description

ConceptDescriptionRepositoryServiceSpecification/SSP-001

Full feature set

Concept Description Repository Service Specification – Full Profile

Name: Concept Description Repository Full Profile

Profile Identifier:

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

Feature

Appearance

API and API Operations

ConceptDescription Repository API
GetAllConceptDescriptions
GetConceptDescriptionById
GetAllConceptDescriptionsByIdShort
GetAllConceptDescriptionsByIsCaseOf
GetAllConceptDescriptionsByDataSpecificationReference
PostConceptDescription
PutConceptDescriptionById
DeleteConceptDescriptionById

Serialization API:
GenerateSerializationByIds

Description API:
GetDescription

SerializationModifier

not applicable

SerializationFormat

JSON

Pagination

Supported