Asset Administration Shell Registry Service Specification Profile SSP-001 Version 3.0 (V3.0.1_SSP-001)

Download OpenAPI specification:Download

Attribution 1

Title: CX-0002 DIGITAL TWINS IN CATENA-X Version 2.0

Publisher: Catena-X Automotive Network e.V.

Attribution 2

Title: Asset Administration Shell Registry Service Specification Profile SSP-001 Version 3.0

Publisher: Industrial Digital Twin Association e.V.

Source: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0.1_SSP-001

License: CC BY 4.0

Asset Administration Shell Registry

Returns all Asset Administration Shell Descriptors

path Parameters

tenantId

required

string <uuid>

Unique identifier of the owning tenant.

query Parameters

limit	integer >= 1 The maximum number of elements in the response array
cursor	string A server-generated identifier retrieved from pagingMetadata that specifies from which position the result listing should continue
assetKind	string (AssetKind) Enum: "Instance" "NotApplicable" "Type" The Asset's kind (Instance or Type)
assetType	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001... The Asset's type (UTF8-BASE64-URL-encoded)

header Parameters

Edc-Bpn

required

string

The external subject id (bpn) indicates which tenant is allowed to see the specificAssetId and find a Shell.

Responses

Response samples

200
400
403
500
default

Content type

application/json

{"paging_metadata": {"cursor": "wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=#"
},
"result": ["{ \"id\": \"https://example.org/aas/motor\" }"
]
}

Creates a new Asset Administration Shell Descriptor, i.e. registers an AAS

path Parameters

tenantId

required

string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Asset Administration Shell Descriptor object

	Array of objects (LangStringTextType) <= 50 items unique
	Array of objects (LangStringNameType) <= 50 items unique
assetKind	string (AssetKind) Enum: "Instance" "NotApplicable" "Type"
assetType	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
globalAssetId	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
idShort	string [ 1 .. 128 ] characters The idShort is unique.
id required	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
	Array of objects (SpecificAssetId) <= 50 items unique
	Array of objects (SubmodelDescriptor) <= 50 items unique
	Array of objects or null (ShellGroupIdDto) <= 50 items unique Shell Groups
labels	Array of strings or null <= 10 items unique Labels of the Shell

Responses

Request samples

Payload

Content type

application/json

"{ \"id\": \"https://example.org/aas/motor\" }"

Response samples

Content type

application/json

"{ \"id\": \"https://example.org/aas/motor\" }"

Returns a specific Asset Administration Shell Descriptor

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)

header Parameters

Edc-Bpn

required

string

The external subject id (bpn) indicates which tenant is allowed to see the specificAssetId and find a Shell.

Responses

Response samples

Content type

application/json

"{ \"id\": \"https://example.org/aas/motor\" }"

Updates an existing Asset Administration Shell Descriptor

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)

Request Body schema: application/json
required

Asset Administration Shell Descriptor object

	Array of objects (LangStringTextType) <= 50 items unique
	Array of objects (LangStringNameType) <= 50 items unique
assetKind	string (AssetKind) Enum: "Instance" "NotApplicable" "Type"
assetType	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
globalAssetId	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
idShort	string [ 1 .. 128 ] characters The idShort is unique.
id required	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
	Array of objects (SpecificAssetId) <= 50 items unique
	Array of objects (SubmodelDescriptor) <= 50 items unique
	Array of objects or null (ShellGroupIdDto) <= 50 items unique Shell Groups
labels	Array of strings or null <= 10 items unique Labels of the Shell

Responses

Request samples

Payload

Content type

application/json

"{ \"id\": \"https://example.org/aas/motor\" }"

Response samples

400
403
404
500
default

Content type

application/json

{"messages": [{"code": "string",
"correlationId": "string",
"messageType": "Undefined",
"text": "string",
"timestamp": "string"
}
]
}

Deletes an Asset Administration Shell Descriptor, i.e. de-registers an AAS

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)

Responses

Response samples

400
404
500
default

Content type

application/json

{"messages": [{"code": "string",
"correlationId": "string",
"messageType": "Undefined",
"text": "string",
"timestamp": "string"
}
]
}

Returns all Submodel Descriptors

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)

query Parameters

limit	integer >= 1 The maximum number of elements in the response array
cursor	string A server-generated identifier retrieved from pagingMetadata that specifies from which position the result listing should continue

header Parameters

Edc-Bpn

required

string

The external subject id (bpn) indicates which tenant is allowed to see the specificAssetId and find a Shell.

Responses

Response samples

Content type

application/json

{"paging_metadata": {"cursor": "wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=#"
},
"result": ["{ \"id\": \"https://admin-shell.io/zvei/nameplate/1/0/Nameplate\", \"endpoints\": [ { \"href\": { \"href\": \"https://localhost:1234/api/v3.0/submodel\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"] }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"opc.tcp://localhost:4840\" }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"https://localhost:5678\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"], \"subprotocol\": \"OPC UA Basic SOAP\", \"subprotocolBody\": \"ns=2;s=MyAAS\", \"subprotocolBodyEncoding\": \"application/soap+xml\" }, \"interface\": \"AAS-3.0\" } ] }"
]
}

Creates a new Submodel Descriptor, i.e. registers a submodel

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)

Request Body schema: application/json
required

Submodel Descriptor object

required	Array of objects (Endpoint) [ 1 .. 10000 ] items unique
idShort	string [ 1 .. 128 ] characters The idShort is not unique overall. All Submodel idShort in one Shell are unique.
id required	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
	object (Reference)
	Array of objects (Reference) <= 50 items unique
	Array of objects (LangStringTextType) <= 50 items unique
	Array of objects (LangStringNameType) <= 50 items unique

Responses

Request samples

Payload

Content type

application/json

"{ \"id\": \"https://admin-shell.io/zvei/nameplate/1/0/Nameplate\", \"endpoints\": [ { \"href\": { \"href\": \"https://localhost:1234/api/v3.0/submodel\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"] }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"opc.tcp://localhost:4840\" }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"https://localhost:5678\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"], \"subprotocol\": \"OPC UA Basic SOAP\", \"subprotocolBody\": \"ns=2;s=MyAAS\", \"subprotocolBodyEncoding\": \"application/soap+xml\" }, \"interface\": \"AAS-3.0\" } ] }"

Response samples

Content type

application/json

"{ \"id\": \"https://admin-shell.io/zvei/nameplate/1/0/Nameplate\", \"endpoints\": [ { \"href\": { \"href\": \"https://localhost:1234/api/v3.0/submodel\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"] }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"opc.tcp://localhost:4840\" }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"https://localhost:5678\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"], \"subprotocol\": \"OPC UA Basic SOAP\", \"subprotocolBody\": \"ns=2;s=MyAAS\", \"subprotocolBodyEncoding\": \"application/soap+xml\" }, \"interface\": \"AAS-3.0\" } ] }"

Returns a specific Submodel Descriptor

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)
submodelIdentifier required	string <byte> The Submodel’s unique id (UTF8-BASE64-URL-encoded)

header Parameters

Edc-Bpn

required

string

The external subject id (bpn) indicates which tenant is allowed to see the specificAssetId and find a Shell.

Responses

Response samples

Content type

application/json

"{ \"id\": \"https://admin-shell.io/zvei/nameplate/1/0/Nameplate\", \"endpoints\": [ { \"href\": { \"href\": \"https://localhost:1234/api/v3.0/submodel\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"] }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"opc.tcp://localhost:4840\" }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"https://localhost:5678\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"], \"subprotocol\": \"OPC UA Basic SOAP\", \"subprotocolBody\": \"ns=2;s=MyAAS\", \"subprotocolBodyEncoding\": \"application/soap+xml\" }, \"interface\": \"AAS-3.0\" } ] }"

Updates an existing Submodel Descriptor

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)
submodelIdentifier required	string <byte> The Submodel’s unique id (UTF8-BASE64-URL-encoded)

Request Body schema: application/json
required

Submodel Descriptor object

required	Array of objects (Endpoint) [ 1 .. 10000 ] items unique
idShort	string [ 1 .. 128 ] characters The idShort is not unique overall. All Submodel idShort in one Shell are unique.
id required	string [ 1 .. 2000 ] characters ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\x{0001...
	object (Reference)
	Array of objects (Reference) <= 50 items unique
	Array of objects (LangStringTextType) <= 50 items unique
	Array of objects (LangStringNameType) <= 50 items unique

Responses

Request samples

Payload

Content type

application/json

"{ \"id\": \"https://admin-shell.io/zvei/nameplate/1/0/Nameplate\", \"endpoints\": [ { \"href\": { \"href\": \"https://localhost:1234/api/v3.0/submodel\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"] }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"opc.tcp://localhost:4840\" }, \"interface\": \"AAS-3.0\" }, { \"protocolInformation\": { \"href\": \"https://localhost:5678\", \"endpointProtocol\": \"HTTP\", \"endpointProtocolVersion\": [\"1.1\"], \"subprotocol\": \"OPC UA Basic SOAP\", \"subprotocolBody\": \"ns=2;s=MyAAS\", \"subprotocolBodyEncoding\": \"application/soap+xml\" }, \"interface\": \"AAS-3.0\" } ] }"

Response samples

400
403
404
500
default

Content type

application/json

{"messages": [{"code": "string",
"correlationId": "string",
"messageType": "Undefined",
"text": "string",
"timestamp": "string"
}
]
}

Deletes a Submodel Descriptor, i.e. de-registers a submodel

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
aasIdentifier required	string <byte> The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)
submodelIdentifier required	string <byte> The Submodel’s unique id (UTF8-BASE64-URL-encoded)

Responses

Response samples

400
404
500
default

Content type

application/json

{"messages": [{"code": "string",
"correlationId": "string",
"messageType": "Undefined",
"text": "string",
"timestamp": "string"
}
]
}

Shell Group

List Shell Groups with cursor pagination

By default the page size is limited to 500 items. The maximum page size is limited to 500 items.

path Parameters

tenantId

required

string <uuid>

Unique identifier of the owning tenant.

query Parameters

cursor	string Default: "0" A server-generated identifier retrieved from pagingMetadata that specifies from which position the result listing should continue.
limit	integer <int32> [ 0 .. 500 ] Default: 500 the size of the requested page. Defaults to `500` if omitted. Maximum allowed value is `500`.

Responses

Response samples

Content type

application/json

{"paging_metadata": {"cursor": "wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=#"
},
"result": ["{ \"id\": \"1\", \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"
]
}

Create a new Shell Group

path Parameters

tenantId

required

string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Shell Group object

name required	string <= 128 characters Human-readable and unique name of the Asset Administration Shell Descriptor Group
description	string or null <= 4000 characters Detailed description of the Asset Administration Shell Descriptor Group

Responses

Request samples

Payload

Content type

application/json

"{  \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Response samples

Content type

application/json

"{ \"id\": \"1\", \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Get Shell Group ID

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
groupIdentifier required	integer <int64> The Shell Group’s unique ID

Responses

Response samples

Content type

application/json

"{ \"id\": \"1\", \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Replace existing Shell Group

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
groupIdentifier required	integer <int64> The Asset Administration Shell’s unique ID

Request Body schema: application/json
required

Shell Group object

name required	string <= 128 characters Human-readable and unique name of the Asset Administration Shell Descriptor Group
description	string or null <= 4000 characters Detailed description of the Asset Administration Shell Descriptor Group

Responses

Request samples

Payload

Content type

application/json

"{ \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Response samples

Content type

application/json

"{ \"id\": \"1\", \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Partially update Shell Group

Performs a partial update on a Shell Group.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
groupIdentifier required	integer <int64> The Asset Administration Shell’s unique ID

Request Body schema: application/json
required

Shell Group object

name	string or null <= 128 characters Human-readable and unique name of the Asset Administration Shell Descriptor Group
description	string or null <= 4000 characters Detailed description of the Asset Administration Shell Descriptor Group

Responses

Request samples

Payload

Content type

application/json

"{ \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Response samples

Content type

application/json

"{ \"id\": \"1\", \"name\": \"Basic Shell Group\",\"description\": \"This group contains all the Shells that have basic Submodels.\"  }"

Delete Shell Group

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
groupIdentifier required	integer <int64> The Shell Group’s unique ID

Responses

Response samples

400
404
500
default

Content type

application/json

{"messages": [{"code": "string",
"correlationId": "string",
"messageType": "Undefined",
"text": "string",
"timestamp": "string"
}
]
}

Asset Administration Shell Registry Service Specification Profile SSP-001 Version 3.0 (V3.0.1_SSP-001)

Asset Administration Shell Registry

Returns all Asset Administration Shell Descriptors

path Parameters

query Parameters

header Parameters

Responses

Response samples

Creates a new Asset Administration Shell Descriptor, i.e. registers an AAS

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Returns a specific Asset Administration Shell Descriptor

path Parameters

header Parameters

Responses

Response samples

Updates an existing Asset Administration Shell Descriptor

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deletes an Asset Administration Shell Descriptor, i.e. de-registers an AAS

path Parameters

Responses

Response samples

Returns all Submodel Descriptors

path Parameters

query Parameters

header Parameters

Responses

Response samples

Creates a new Submodel Descriptor, i.e. registers a submodel

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Returns a specific Submodel Descriptor

path Parameters

header Parameters

Responses

Response samples

Updates an existing Submodel Descriptor

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deletes a Submodel Descriptor, i.e. de-registers a submodel

path Parameters

Responses

Response samples

Shell Group

List Shell Groups with cursor pagination

path Parameters

query Parameters

Responses

Response samples

Create a new Shell Group

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Shell Group ID

path Parameters

Responses

Response samples

Replace existing Shell Group

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Partially update Shell Group

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required