diff --git a/AssetAdministrationShellRepositoryServiceSpecification/V3.0_SSP-001.yaml b/AssetAdministrationShellRepositoryServiceSpecification/V3.0_SSP-001.yaml index c3304f70..e151de38 100644 --- a/AssetAdministrationShellRepositoryServiceSpecification/V3.0_SSP-001.yaml +++ b/AssetAdministrationShellRepositoryServiceSpecification/V3.0_SSP-001.yaml @@ -11,7 +11,7 @@ info: license: name: CC BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ - version: V3.0.2_SSP-001 + version: V3.1.0_SSP-001 x-profile-identifier: https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-001 servers: - url: '{protocol}://{host_name}:{port}/api/{version_prefix}' @@ -564,8 +564,9 @@ paths: - Asset Administration Shell Repository API summary: Updates the Submodel operationId: PatchSubmodel_AasRepository + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -660,7 +661,7 @@ paths: summary: Updates the metadata attributes of the Submodel operationId: PatchSubmodelById-Metadata_AasRepository x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/0 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -731,10 +732,10 @@ paths: patch: tags: - Asset Administration Shell Repository API - summary: Updates teh values of the Submodel + summary: Updates the values of the Submodel operationId: PatchSubmodelById-ValueOnly_AasRepository x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/0 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -1166,8 +1167,9 @@ paths: - Asset Administration Shell Repository API summary: Updates an existing submodel element value at a specified path within submodel elements hierarchy operationId: PatchSubmodelElementValueByPath_AasRepository + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/1 parameters: - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' requestBody: diff --git a/AssetAdministrationShellServiceSpecification/V3.0_SSP-001.yaml b/AssetAdministrationShellServiceSpecification/V3.0_SSP-001.yaml index 8b692dc2..198bbaa4 100644 --- a/AssetAdministrationShellServiceSpecification/V3.0_SSP-001.yaml +++ b/AssetAdministrationShellServiceSpecification/V3.0_SSP-001.yaml @@ -419,8 +419,9 @@ paths: - Asset Administration Shell API summary: Updates the Submodel operationId: PatchSubmodel + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -1023,8 +1024,9 @@ paths: - Asset Administration Shell API summary: Updates an existing submodel element value at a specified path within submodel elements hierarchy operationId: PatchSubmodelElementValueByPath + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/1 parameters: - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' requestBody: diff --git a/Entire-API-Collection/V3.0.yaml b/Entire-API-Collection/V3.0.yaml index 0681ecd7..e21b19d8 100644 --- a/Entire-API-Collection/V3.0.yaml +++ b/Entire-API-Collection/V3.0.yaml @@ -376,8 +376,9 @@ paths: - Asset Administration Shell API summary: Updates the Submodel operationId: PatchSubmodel_AAS + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PutSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -1553,8 +1554,9 @@ paths: - Submodel API summary: Updates the Submodel operationId: PatchSubmodel + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -2068,8 +2070,9 @@ paths: - Submodel API summary: Updates an existing SubmodelElement operationId: PatchSubmodelElementByPath + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -3191,8 +3194,9 @@ paths: - Asset Administration Shell Repository API summary: Updates the Submodel operationId: PatchSubmodel_AasRepository + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -3288,7 +3292,7 @@ paths: summary: Updates the metadata attributes of the Submodel operationId: PatchSubmodelById-Metadata_AasRepository x-semanticIds: - - https://admin-shell.io/aas/API/PutSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/0 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -4667,8 +4671,9 @@ paths: - Submodel Repository API summary: Updates an existing Submodel operationId: PatchSubmodelById + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -5274,8 +5279,9 @@ paths: - Submodel Repository API summary: Updates an existing SubmodelElement operationId: PatchSubmodelElementByPath_SubmodelRepo + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -5368,8 +5374,9 @@ paths: - Submodel Repository API summary: Updates the metadata attributes an existing SubmodelElement operationId: PatchSubmodelElementByPath-Metadata_SubmodelRepo + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/1 requestBody: description: Metadata attributes of the SubmodelElement content: diff --git a/SubmodelRepositoryServiceSpecification/V3.0_SSP-001.yaml b/SubmodelRepositoryServiceSpecification/V3.0_SSP-001.yaml index b272be93..27cfa249 100644 --- a/SubmodelRepositoryServiceSpecification/V3.0_SSP-001.yaml +++ b/SubmodelRepositoryServiceSpecification/V3.0_SSP-001.yaml @@ -11,7 +11,7 @@ info: license: name: CC BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ - version: V3.0.2_SSP-001 + version: V3.1.0_SSP-001 x-profile-identifier: https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-001 servers: - url: '{protocol}://{host_name}:{port}/api/{version_prefix}' @@ -319,8 +319,9 @@ paths: - Submodel Repository API summary: Updates an existing Submodel operationId: PatchSubmodelById + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: - name: level in: query @@ -921,8 +922,9 @@ paths: - Submodel Repository API summary: Updates an existing SubmodelElement operationId: PatchSubmodelElementByPath_SubmodelRepo + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: - name: level in: query diff --git a/SubmodelRepositoryServiceSpecification/V3.0_SSP-003.yaml b/SubmodelRepositoryServiceSpecification/V3.0_SSP-003.yaml index 572a3e91..55ffb9c2 100644 --- a/SubmodelRepositoryServiceSpecification/V3.0_SSP-003.yaml +++ b/SubmodelRepositoryServiceSpecification/V3.0_SSP-003.yaml @@ -11,7 +11,7 @@ info: license: name: CC BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ - version: V3.0.2_SSP-003 + version: V3.1.0_SSP-003 x-profile-identifier: https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-003 servers: - url: '{protocol}://{host_name}:{port}/api/{version_prefix}' @@ -243,8 +243,9 @@ paths: - Submodel Repository API summary: Updates an existing Submodel operationId: PatchSubmodelById + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: - name: level in: query @@ -602,8 +603,9 @@ paths: - Submodel Repository API summary: Updates an existing SubmodelElement operationId: PatchSubmodelElementByPath_SubmodelRepo + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 # https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/1 ? parameters: - name: level in: query diff --git a/SubmodelServiceSpecification/V3.0_SSP-001.yaml b/SubmodelServiceSpecification/V3.0_SSP-001.yaml index 6013af2e..8f6c631f 100644 --- a/SubmodelServiceSpecification/V3.0_SSP-001.yaml +++ b/SubmodelServiceSpecification/V3.0_SSP-001.yaml @@ -11,8 +11,8 @@ info: license: name: CC BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ - version: V3.0.2_SSP-001 - x-profile-identifier: https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001 + version: V3.1.0_SSP-001 + x-profile-identifier: https://admin-shell.io/aas/API/3/1/SubmodelServiceSpecification/SSP-001 servers: - url: '{protocol}://{host_name}:{port}/api/{version_prefix}' variables: @@ -108,8 +108,9 @@ paths: - Submodel API summary: Updates the Submodel operationId: PatchSubmodel + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodel/3/0 + - https://admin-shell.io/aas/API/PatchSubmodel/3/1 parameters: #- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.2#/components/parameters/Level' - name: level @@ -651,8 +652,9 @@ paths: - Submodel API summary: Updates an existing SubmodelElement operationId: PatchSubmodelElementByPath + deprecated: true x-semanticIds: - - https://admin-shell.io/aas/API/PatchSubmodelById/3/0 + - https://admin-shell.io/aas/API/PatchSubmodelById/3/1 parameters: - name: level in: query diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc index 0bf1d7e0..3adeba60 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc @@ -58,6 +58,9 @@ add DeleteBulkSubmodelDescriptorsById ||PostBulkSubmodelDescriptors |new | ||PutBulkSubmodelDescriptorsById|new | ||DeleteBulkSubmodelDescriptorsById|new | +| PatchSubmodel | Deprecate PATCH for non-metadata and non-value-only paths | change | | +| PatchSubmodelById | Deprecate PATCH for non-metadata and non-value-only paths | change | | +| PatchSubmodelElementByPath | Deprecate PATCH for non-metadata and non-value-only paths | change | | |=== === Profile Changes w.r.t. V3.0.2 to V3.1 diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc index d5b6ab20..50db8172 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc @@ -373,7 +373,19 @@ path-suffix= $metadata/$value/$reference/$path or no suffix for normal ?extent=WithoutBLOBValue/WithBLOBValue |PutSubmodel |PUT |/submodel | -|PatchSubmodel |PATCH |/submodel |path-suffix=$metadata/$value or no path for normal +|PatchSubmodel |PATCH |/submodel |path-suffix=/$metadata or /$value + +For /$metadata: + +The serialised submodel in the request body must not contain any SubmodelElements. + +The server must overwrite all metadata-relevant Submodel fields with the received fields. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). + +For /$value: + +The server must overwrite all ValueOnly-relevant Submodel fields with the received values. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. + +==== +Note: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 +==== + |GetAllSubmodelElements |GET |/submodel/submodel-elements a| ?level=deep/core @@ -422,27 +434,28 @@ URL-encoded IdShortPath |PatchSubmodelElementByPath |PATCH |/submodel/submodel-elements/\{idShortPath} a| use separated idShort path of this element -path-suffix=$metadata/$value or no suffix for normal +path-suffix=/$metadata or /$value URL-encoded IdShortPath +For /$metadata: + +The serialised SubmodelElement in the request body must not contain any values. + +The server must overwrite all metadata-relevant SubmodelElement fields with the received fields. This means in particular that previously used fields of the SubmodelElement instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). + +For /$value: + +The server must overwrite all ValueOnly-relevant SubmodelElement fields with the received values. This means in particular that previously used fields of the SubmodelElement instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. ==== -Note: values remain unchanged with content=metadata +Note 1: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 ==== +==== +Note 2: See Clause 11.4.2 for values. +==== -|PatchSubmodelElementValueByPath |PATCH |/submodel/submodel-elements/\{idShortPath}/$value a| -use separated idShort path of this element; see Clause 11.4.2 for values - -path-suffix=$value - -URL-encoded IdShortPath - -|DeleteSubmodelElementByPath |DELETE |/submodel/submodel-elements/\{idShortPath} a| -use separated idshort path of this element - -URL-encoded IdShortPath +==== +Note 3: values remain unchanged with content=metadata +==== |InvokeOperationSync |POST |/submodel/submodel-elements/\{idShortPath}/invoke a| path-suffix=$value or no suffix for normal @@ -521,7 +534,19 @@ base64url-encoded identifier |PostSubmodel |POST |/submodels | |PutSubmodelById |PUT |/submodels/\{submodelIdentifier} |base64url-encoded identifier -|PatchSubmodelById |PATCH |/submodels/\{submodelIdentifier} |path-suffix=$metadata/$value or no suffix for normal +|PatchSubmodelById |PATCH |/submodels/\{submodelIdentifier} |path-suffix=/$metadata or /$value + +For /$metadata: + +The serialised submodel in the request body must not contain any SubmodelElements. + +The server must overwrite all metadata-relevant Submodel fields with the received fields. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). + +For /$value: + +The server must overwrite all ValueOnly-relevant Submodel fields with the received values. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. + +==== +Note: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 +==== + |DeleteSubmodelById |DELETE |/submodels/\{submodelIdentifier} |base64url-encoded identifier |SubmodelInterface |* |/submodels/\{submodelIdentifier}/* |superpath as defined in service specification or profile | | diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc index af5ca347..06247471 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc @@ -233,7 +233,7 @@ e|GetFileByPath a|Returns a specific file from the Submodel at a specified path e|PutFileByPath a|Replaces the file of an existing submodel element at a specified path within the submodel element hierarchy e|DeleteFileByPath a|Deletes the file of an existing submodel element at a specified path within the submodel element hierarchy e|PutSubmodel a|Replaces the Submodel -e|PatchSubmodel a|Updates the Submodel +e|PatchSubmodel a|Updates the Submodel. e|PostSubmodelElement a|Creates a new submodel element as a child of the submodel. The idShort of the new submodel element must be set in the payload. e|PostSubmodelElementByPath a|Creates a new submodel element at a specified path within the submodel elements hierarchy. The idShort of the new submodel element must be set in the payload. e|PutSubmodelElementByPath a|Replaces an existing submodel element at a specified path within the submodel element hierarchy @@ -374,7 +374,7 @@ h|Name h|Description h|Mand. h|Type h|Card. |=== h|Operation Name 4+e|[[PatchSubmodel]]PatchSubmodel h|Explanation 4+a|Updates the Submodel -h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodel/3/0 +h|semanticId 4+|`https://admin-shell.io/aas/API/PatchSubmodel/3/1 h|Name h|Description h|Mand. h|Type h|Card. 5+h|Input Parameter @@ -383,7 +383,7 @@ Defines the format of the input ==== -Note: values remain unchanged with content=metadata. +Note 1: values remain unchanged with content=metadata. ==== @@ -480,7 +480,7 @@ h|Name h|Description h|Mand. h|Type h|Card. |=== h|Operation Name 4+e|[[PatchSubmodelElementByPath]]PatchSubmodelElementByPath h|Explanation 4+a|Updates an existing submodel element at a specified path within the submodel element hierarchy -h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/0` +h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelElementByPath/3/1` h|Name h|Description h|Mand. h|Type h|Card. 5+h|Input Parameter @@ -528,7 +528,7 @@ h|Name h|Description h|Mand. h|Type h|Card. |=== h|Operation Name 4+e|[[PatchSubmodelElementValueByPath]]PatchSubmodelElementValueByPath h|Explanation 4+a|Sets the value of the submodel element at a specified path according to the ValueOnly-serialization as defined in clause 11.4.1 -h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelElementValueByPath/3/0` +h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelElementValueByPath/3/1` h|Name h|Description h|Mand. h|Type h|Card. 5+h|Input Parameter @@ -1463,7 +1463,7 @@ h|Name h|Description h|Mand. h|Type h|Card. |=== h|Operation Name 4+e|PatchSubmodelById h|Explanation 4+a|Updates an existing Submodel -h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelById/3/0` +h|semanticId 4+|`\https://admin-shell.io/aas/API/PatchSubmodelById/3/1` h|Name h|Description h|Mand. h|Type h|Card. 5+h|Input Parameter