Inconsistencies with PUT requests in superpaths

[mjacoby]

What is the issue?

According to the specification there are the following API calls ralted to PUT a submodel:

• Submodel Interface PutSubmodel "Replaces the Submodel" , optionally returning the Submodel (cardinality=1, mandatory=false)
• SubmodelRepository Interface PutSubmodelById "Creates a new or replaces an existing Submodel", optionally returning the Submodel (cardinality=1, mandatory=false)

For AAS it follows the same pattern

• AssetAdministrationShell Interface PutAssetAdministrationShell "Replaces the Asset Administration Shell", optionally returning the AssetAdministrationShell (cardinality=1, mandatory=false)
• AssetAdministrationShellRepository Interface PutAssetAdministrationShellById "Creates or replaces an existing Asset Administration Shell", optionally returning the AssetAdministrationShell (cardinality=1, mandatory=false)

In the OpenAPI documentation for the complete API are following mappings of these operations:

• PUT /submodel returns 204 No Content
• PUT /submodels/{submodelIdentifier} returns 201 Created with the submodel as body or 204 No Content

For AAS it follows mostly the same pattern but there are some minor differences

• PUT /aas returns 201 Created without the submodel as body or 204 No Content
• PUT /shells/{aasIdentifier} returns 201 Created with the AAS as body or 204 No Content

Why is this wrong?

The OpenAPI definition is inconsistent in two ways

1. The two submodel calls behave differently although they are, to my understanding, essentially the same call, at least in the SubmodelRepository interface because there no longer is a seperate /submodel call because of superpaths.
2. Inconsistent mapping to REST - same definition in spec is mapped differently to REST API (inconsistent return codes and payloads).

How should it be fixed?

Make all calls support update and create and return 201 with body or 204.

• I have signed the required Developer Certificate of Origin (DCO) already.

[sebbader-sap]

Discussed today (23.4.2026) in the task force: The 201 response code for PutAssetAdministrationShell is definitely wrong, we agree to remove it completely and only keep the 204.

Note: This is affecting the AssetAdministrationShellService and the EntireAPI files but not the PutAssetAdministrationShellById operations.