Update Asset Administration Shells via PATCH REST endpoint

The Asset Administration Shell Digital Twin Registry implements a custom PATCH REST endpoint for Asset Administration Shells that enables partial updates to existing Shells according to the RFC 7396 JSON Merge Patch externallink 20 standard.

Key benefits:

Update only specific fields while leaving others untouched
Reduce payload size compared to full PUT operations
Simplify update operations for complex objects

For more details, see Digital Twin Registry API description: PATCH REST endpoint for Asset Administration Shells externallink 20 .

Supported Asset Administration Shell fields for partial updates

Field update capabilities vary based on field type:

Required simple fields (e.g., strings, integers, enumerations): Can be replaced but not reset to being empty
Optional simple fields: Can be replaced or reset to being empty (use null)
List fields: Can only be updated at the highest level (replace entire list or add/remove specific elements)

All data constraints (length limits, mandatory fields, etc.) remain in effect when using the PATCH endpoint.

Field Name PATCH Supported Description

Field Name	PATCH Supported	Description
id	Yes	Can be replaced but not reset to being empty (required field)
idShort, assetKind, assetType, globalAssetId	Yes	Can be replaced or reset to `null` (optional fields)
description, displayName, specificAssetIds, groups, labels	Yes	Can have entire lists replaced or specific elements added/removed (using `listOperator`)
submodelDescriptors	No	Use dedicated REST endpoints for Submodel management: API description

Yes

Can be replaced but not reset to being empty (required field)

idShort, assetKind, assetType, globalAssetId

Yes

Can be replaced or reset to null (optional fields)

description, displayName, specificAssetIds, groups, labels

Yes

Can have entire lists replaced or specific elements added/removed (using listOperator)

submodelDescriptors

Use dedicated REST endpoints for Submodel management: API description externallink 20

Working with list fields

List operations

When updating list fields, three operations are available, controlled by the listOperator attribute:

replace (default): Replaces the entire list with provided elements
add: Appends new elements to the existing list
remove: Removes specified elements from the list
For the remove operation, you must provide the complete element to be removed.

Only one listOperator value can be used per request.

Note that you cannot modify individual fields within a list element — you must remove and re-add the entire element. See Replace a single list element.

Usage examples

The following section provides practical examples to illustrate the usage of the PATCH endpoint for Asset Administration Shells.

Example setup

Assume this Asset Administration Shell exists in the Digital Twin Registry:

POST https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors
Body:
{
  "id": "myId1",
  "idShort": "myIdShort1",
  "description": [
    {
      "language": "de",
      "text": "Beispielbeschreibung"
    }
  ],
  "globalAssetId": "DDE823EE-254E-464F-948D-1FC7132E335D",
  "assetKind": "Instance",
  "labels": [
    "myLabel1",
    "myLabel2"
  ],
  "specificAssetIds": [
    {
      "name": "vin",
      "value": "12345"
    }
  ]
}
Response: 201 created
ResponseBody: <omitted>

Update of simple fields

Query to send to the Digital Twin Registry:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDE=
Body:
{
  "id": "myId2",
  "idShort": null,
  "globalAssetId": "BA3878F4-6E85-4CF0-AA3B-FC67D2F09738"
}
Response: 204 No Content
ResponseBody: <none>

Result — updated Asset Administration Shell (note the changed path due to ID update):

GET https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body: <none>
Response: 200 OK
ResponseBody:
{
  "description": [
    {
      "language": "de",
      "text": "Beispielbeschreibung"
    }
  ],
  "displayName": [],
  "assetKind": "Instance",
  "globalAssetId": "BA3878F4-6E85-4CF0-AA3B-FC67D2F09738",
  "id": "myId2",
  "specificAssetIds": [
    {
      "supplementalSemanticIds": [],
      "name": "vin",
      "value": "12345"
    }
  ],
  "submodelDescriptors": [],
  "groups": [],
  "labels": [
    "myLabel1",
    "myLabel2"
  ],
  "createdAt": "2025-06-12T12:43:05.311Z"
}

Add elements to lists

Query to send to the Digital Twin Registry:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body:
{
  "groups": [
    1
  ],
  "labels": [
    "myLabel3"
  ],
  "listOperator": "add"
}
Response: 204 No Content
ResponseBody: <none>

Result — updated Asset Administration Shell:

GET https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body: <none>
Response: 200 OK
ResponseBody:
{
  "description": [
    {
      "language": "de",
      "text": "Beispielbeschreibung"
    }
  ],
  "displayName": [],
  "assetKind": "Instance",
  "globalAssetId": "BA3878F4-6E85-4CF0-AA3B-FC67D2F09738",
  "id": "myId2",
  "specificAssetIds": [
    {
      "supplementalSemanticIds": [],
      "name": "vin",
      "value": "12345"
    }
  ],
  "submodelDescriptors": [],
  "groups": [
    {
      "id": 1
    }
  ],
  "labels": [
    "myLabel1",
    "myLabel2",
    "myLabel3"
  ],
  "createdAt": "2025-06-12T13:01:31.854Z"
}

Remove elements from lists

Query to send to the Digital Twin Registry:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body:
{
  "specificAssetIds": [
    {
      "name": "vin",
      "value": "12345"
    }
  ],
  "labels": [
    "myLabel1"
  ],
  "listOperator": "remove"
}
Response: 204 No Content
ResponseBody: <none>

Result — updated Asset Administration Shell:

GET https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body: <none>
Response: 200 OK
ResponseBody:
{
  "description": [
    {
      "language": "de",
      "text": "Beispielbeschreibung"
    }
  ],
  "displayName": [],
  "assetKind": "Instance",
  "globalAssetId": "BA3878F4-6E85-4CF0-AA3B-FC67D2F09738",
  "id": "myId2",
  "specificAssetIds": [],
  "submodelDescriptors": [],
  "groups": [
    {
      "id": 1
    }
  ],
  "labels": [
    "myLabel2",
    "myLabel3"
  ],
  "createdAt": "2025-06-12T13:10:12.159Z"
}

Replace entire lists

Query to send to the Digital Twin Registry:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body:
{
  "description": [],
  "labels": [
    "myLabel99"
  ],
  "listOperator": "replace"
}
Response: 204 No Content
ResponseBody: <none>

Result — updated Asset Administration Shell:

GET https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body: <none>
Response: 200 OK
ResponseBody:
{
  "description": [],
  "displayName": [],
  "assetKind": "Instance",
  "globalAssetId": "BA3878F4-6E85-4CF0-AA3B-FC67D2F09738",
  "id": "myId2",
  "specificAssetIds": [],
  "submodelDescriptors": [],
  "groups": [
    {
      "id": 1
    }
  ],
  "labels": [
    "myLabel99"
  ],
  "createdAt": "2025-06-12T13:12:38.418Z"
}

Replace a single list element

To modify individual fields within a list element, you must first remove and the re-add the entire element.

Consider this Asset Administration Shell as an example:

{
  "id": "myShell",
  "specificAssetIds": [
    {
      "name": "myId1",
      "value": "myId1Value",
      "externalSubjectId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "myReference"
          }
        ]
      }
    },
    {
      "name": "myId2",
      "value": "myId2Value"
    }
  ]
}

To change the type of externalSubjectId from ExternalReference to ModelReference, first remove the entire element, then add the updated element.

First, remove the entire element:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body:
{
  "specificAssetIds": [
    {
      "name": "myId1",
      "value": "myId1Value",
      "externalSubjectId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "myReference"
          }
        ]
      }
    }
  ],
  "listOperator": "remove"
}
Response: 204 No Content
ResponseBody: <none>

Then, add the updated element:

PATCH https://registry.bosch-semantic-stack.com/aas-api/v3/{tenantId}/shell-descriptors/bXlJZDI=
Body:
{
  "specificAssetIds": [
    {
      "name": "myId1",
      "value": "myId1Value",
      "externalSubjectId": {
        "type": "ModelReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "myReference"
          }
        ]
      }
    }
  ],
  "listOperator": "add"
}
Response: 204 No Content
ResponseBody: <none>