Change Notes General * Means not backward compatible (*) means not backward compatible but just renaming Note: Changes in Metamodel (IDTA-01001) will not be listed here, although they have an impact on the payload of many operations. Changes w.r.t. V3.0.2 to V3.1 Major Changes: Bulk Operations and Profiles for Bulk Operations (#3) deprecated: operation GetAllAssetAdministrationShellIdsByAssetLink new: operation SearchAllAssetAdministrationShellIdsByAssetLink (as substitute for GetAllAssetAdministrationShellIdsByAssetLink) (#19) new Profile for Discovery Service: Read Only SSP-002 (#201) updated: Terms and Definitions adopted to IEC 63278-1:2023 (before IEC 63278-1 Draft July 2022 was the basis), also abbreviations partly adopted; changed definitions (#365): changed: interface changed: service Individual versioning of datatype IDs, operations, interfaces etc. (#247) Data type Identifier: change length from 2000 to 2048 characters (#306) Transfer of chapters on formats Metadata, Paths and Value-Only from Part 2 API to Part 1 Metamodel (#214) Transfer from .docx to asciidoc (.adoc) and maintenance in github Interface Changes w.r.t. V3.0.2 to V3.1 BWC Interface Change Kind of Change Comment AAS Basic Discovery Changed deprecate GetAllAssetAdministrationShellIdsByAssetLink add SearchAllAssetAdministrationShellIdsByAssetLink AAS Registry Changed add CreateBulkAssetAdministrationShellDescriptors add PutBulkAssetAdministrationShellDescriptorsById add DeleteBulkAssetAdministrationShellDescriptorsById GetAllAssetAdministrationShellDescriptors Changed Changed the parameters assetKind and assetType from mandatory to optional. OpenAPI remains unchanged. (#298) Submodel Registry Changed add PostBulkSubmodelDescriptors, add PutBulkSubmodelDescriptorsById, add DeleteBulkSubmodelDescriptorsById Operation Changes w.r.t. V3.0.2 to V3.1 Operation Change Old Operation Change New Kind of Change Comment GetAllAssetAdministrationShellIdsByAssetLink deprecated substituted by SearchAllAssetAdministrationShellIdsByAssetLink SearchAllAssetAdministrationShellIdsByAssetLink new substitute for GetAllAssetAdministrationShellIdsByAssetLink PostBulkSubmodelDescriptors new PutBulkSubmodelDescriptorsById new DeleteBulkSubmodelDescriptorsById new Profile Changes w.r.t. V3.0.2 to V3.1 Profile Change Old Profile Change New Kind of Change Comment Asset Administration Shell Registry Profile – Bulk Profile new Submodel Registry Profile – Bulk Profile new Discovery Profile – Full Profile update GetAllAssetAdministrationShellIdsByAssetLink set to deprecated, added new API-operation SearchAllAssetAdministrationShellIdsByAssetLink Discovery Profile – Read Profile new Class Changes w.r.t. V3.0.2 to V3.1 Table 1. Changes in Data Types for Payload Nc V3.1 Change w.r.t. V3.0 Comment AssetAdministrationShellDescriptor/assetType data type: change length from 2000 to 2048 characters AssetAdministrationShellDescriptor/globalAssetId data type: change length from 2000 to 2048 characters AssetAdministrationShellDescriptor/id data type: change length from 2000 to 2048 characters SubmodelDescriptor/id data type: change length from 2000 to 2048 characters PackageDescription/aasIds data type: change length from 2000 to 2048 characters ProtocolInformation/href data type: change length from 2000 to 2048 characters Table 2. New Data Types for Payload New Elements V3.1 vs V3.0 Comment AssetLink new class for discovery operation(s) AssetLink/name AssetLink/value Changes w.r.t. V3.0.1 to V3.0.2 Major: Remove “format: byte” from OpenAPI files, as this annotation enforces base64 encodings while base64url is actually required. Remove the QueryParameter “level” from all requests ending with /$metadata in the OpenAPI files. Change the values for the ServiceDescription class from enum to a list of strings in the OpenAPI definition for the Part 2 classes. Clause 11.4.2 and 11.4.3: Change the ValueOnly attribute “annotation” to “annotations” and its value from an array to ValueOnly for the AnnotatedRelationshipElementValue class in the examples and schema to match the “AnnotatedRelationshipElement/annotations” attribute. Furthermore, “AnnotatedRelationshipElementValue/annotations” is optional now. Clause 11.4.2: Add serialisation rule for empty "FileValue/value" and "BlobValue/value". Clause 11.4.3: "FileValue/value" and "BlobValue/value" are optional but non-empty attributes. Clause 11.4.3: "EntityValue/statements" made optional. Clause 11.4.3: Fix maxLength for "FileValue/value" from 200 to 2000 characters. Clause 12.2: Remove the design decision for the ReferenceParent class, also removing it from the OpenAPI file. Clause 12.3: Relax the requirements for API paths and version declaration. (Editorial) Clause 12.8: Added constraint on the return object for ValueOnly requests and that the Level modifier is undefined for Metadata requests. Adopt the V3.0.1 bugfix changes of the AAS Metamodel in the OpenAPI files and references. Minor: (Editorial) Fix links to SwaggerHub in Clause 4.6 and Clause 12 (Editorial) Clause 8.2.2: Correct the Note that explains the usage of “globalAssetId” for the “assetIds” parameter. (Editorial) ServiceSpecificationProfileEnum: Corrected explanations for Submodel Repository and Registry profile entries (Editorial) Clause 11.4.2: Add “Submodel” to the list of possible ValueOnly objects and add more details how SubmodelElementLists have to be serialized. (Editorial) Clause 11.4.4: Added sentence explaining where the idShortPath has to start. (Editorial) Clause 12.2: Correct example for GetAllAssetAdministrationShellIdsByAssetLink (Editorial) Correct Note 1 in Clause 12.4: “[…] IdshortPaths are base64url-encoded …” to “[…] IdshortPaths are url-encoded …” (Editorial) Clause 12.13: Corrected the list of constraints. (Editorial) Annex C.2: Adjusted and extended the examples for GETs on Metadata, Path, and Value (Editorial) Annex C.3: Adjusted the examples for PATCH on Value Interface Changes w.r.t. V3.0.2 to V3.1 BWC Interface Change Kind of Change Comment GetOperationAsnycStatus Changed Replace payload type ‘OperationResult’ with ‘BaseOperationResult’ that OpenAPI descriptions already contained ‘BaseOperationResult’ from V3.0 on. ServiceSpecificationProfileEnum Remove Removed profiles https://admin-shell.io/aas/API/3/0/RepositoryServiceSpecification/SSP-001 and https://admin-shell.io/aas/API/3/0/RepositoryServiceSpecification/SSP-002. Both profiles were not included in the V3.0.1 ServiceDescription class in the OpenAPI definition and only left-overs from previous drafts. PutAssetAdministrationShell Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutSubmodel Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PatchSubmodel Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutSubmodelElementByPath Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PatchSubmodelElementByPath Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutAssetAdministrationShellDescriptorById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutSubmodelDescriptorById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutAssetAdministrationShellById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutSubmodelById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PatchSubmodelById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” PutConceptDescriptionById Change Output parameter “payload” changed from “mandatory=yes” to “mandatory=no” Operation Changes w.r.t. V3.0.1 to V3.0.2 Operation Change Old Operation Change New Kind of Change Comment GetSubmodelElementByPath-Metadata had ‘level’ and/or ‘cursor’ parameters in OpenAPI ‘level’ and/or ‘cursor’ parameters have been removed GetSubmodelElementByPath-Metadata Remove Neither ‘level’ nor ‘cursor’ could influence the behavior of the operation, therefore, removing them has no effect on any implementation. CreateSubmodelReference New comment in Table 15 clarifies the content of the Location header of the response. Change GetSelfDescription output type “ServiceDescription” contains enum for "profiles" GetSelfDescription output type “ServiceDescription” contains list of strings for “profiles” Change Custom profiles can be added with the new structure. String attributes of Part 2 classes are restricted to the regex pattern "^[\\x09\\x0A\\x0D\\x20-\\uD7FF\\uE000-\\uFFFD\\U00010000-\\U0010FFFF]*$" String attributes of Part 2 classes are restricted to the regex pattern "^([\\t\\n\\r -\ud7ff\ue000-\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$" Change The new pattern has been introduced for the JSON schema and the Part 1 OpenAPI domain already. This change synchronizes the pattern for both Part 1 and Part 2 classes. GetSubmodelElementByPath had single PathItem as the response object in some OpenAPI files GetSubmodelElementByPath returns an array of PathItems Change PathItem regex did not allow SubmodelElementLists PathItem regex does allow SubmodelElementLists Change Changes w.r.t. V3.0 to V3.0.1 Major: Added Location header for POSTs that create a new resource, according to RFC 9110 Section 15.3.2 Correcting definitions of SerialisationModifiers and Pagination parameters in the OpenAPI files. Cleaning of incorrectly located API Operations from the OpenAPI files. Removing several outdated/inconsistently named OpenAPI files from the GitHub Release. Fixing the values of the ServiceDescription/profiles enum in the OpenAPI Domain. Changes w.r.t. V1.0RC03 to V3.0 Major Changes: Introduction of service specifications and profiles Introduction of pagination for "GetAll*" API operations in http/REST Distinction between replace and update for operations SerializationModifier Content as path: $metadata, $value, $reference, $path Introduction of length constraints for string attributes Interface Changes w.r.t. V1.0RC03 to V3.0 BWC Interface Change Kind of Change Comment Submodel New PatchSubmodel and PatchSubmodelElementByPath (PUT to completely replace and PATCH to update content) Asset Administration Shell, Submodel, AASX File Server, AAS Repository, Submodel Repository, CD Repository, AAS Registry, Submodel Registry, AAS Basic Discovery Changed Add Pagination: GetAllAssetAdministrationShells GetAllAssetAdministrationShellsByAssetId GetAllAssetAdministrationShellsByIdShort GetAllSubmodelReferences GetAllSubmodels GetAllSubmodelsBySemanticId GetAllSubmodelsByIdShort GetAllSubmodelElements GetSubmodelElementByPath GetAllConceptDescriptions GetAllConceptDescriptionsByIdShort GetAllConceptDescriptionsByIsCaseOf GetAllConceptDescriptionsByDataSpecificationReference GetAllAssetAdministrationShellDescriptors GetAllSubmodelDescriptors GetAllAssetAdministrationShellIdsByAssetLink GetAllAASXPackageIds Submodel Changed SerializationModifier Content as path: $metadata, $value, $reference, $path Asset Administration Shell New GetThumbnail, PutThumbnail Submodel Repository New PatchSubmodelForId was missing Registry New Add extensions to descriptor AssetAdministrationShellDescriptor New Add the attributes assetKind and assetType SubmodelDescriptor New Add supplementalSemanticId * Changed Rename GetDescriptor to GetDescription * Changed API versioning with major + minor * New Profiles * Changed Clarify service specifications and APIs CD Registry Changed Renaming parameter ‘cdIdentifier’ in GetConceptDescriptionById to ‘id’. Parameter has not been changed in the HTTP API. Operation Changes w.r.t. V1.0RC03 to V3.0 Operation Change Old Operation Change New Kind of Change Comment GetDescriptor GetDescription Changed Rename, get profiles Changes w.r.t. V1.0RC02 to V1.0RC03 Interface Changes w.r.t. V1.0RC02 to V1.0RC03 BWC Interface Change Kind of Change Comment * Discovery Changed IdentifierKeyValuePair to SpecificAssetId * Submodel Changed SubmodelElementStruct remains as SubmodelElementCollection * Submodel Changed ModelReference and GlobalReference are combined back to Reference * Submodel Changed Rename trimmed to metadata Submodel New Add GetFileByPath Submodel New Add PutFileByPath * Submodel Changed InvokeOperationAsync Registry Changed Endpoint * Registry Changed Remove /registry from REST path * All New API Versioning adds a prefix to all interfaces Operation Changes w.r.t. V1.0RC02 to V1.0RC03 Operation Change Old Operation Change New Kind of Change Comment Changed inputArgument and inoutputArgument are OperationVariable GetAllAssetAdministrationShellsByAssetLink Changed IdentifierKeyValuePair to SpecificAssetId GetAllAssetLinksById Changed IdentifierKeyValuePair to SpecificAssetId PostAllAssetLinksById Changed IdentifierKeyValuePair to SpecificAssetId Changes w.r.t. V1.0RC01 to V1.0RC02 Interface Changes w.r.t. V1.0RC01 to V1.0RC02 BWC Interface Change Kind of Change Comment * Asset Administration Shell Changed Renamed: RemoveSubmodelReference to DeleteSubmodelReference Removed: PutSubmodelReference, PatchAssetAdministrationShell New: GetAssetInformation PutAssetInformation GetAllSubmodelReferences PostSubmodelReference * Submodel Changed Removed: GetAllSubmodelElementsByParentPathAndSemanticId, GetAllSubmodelElementsBySemanticId New: PutSubmodel, PostSubmodelElement, PostSubmodelElementByPath * Asset Administration Shell Serialization Changed Renamed: GetSerializationByIds to GenerateSerializationByIds Removed: GetAASX AASX File Server New New interface (*) Asset Administration Shell Registry Changed Renamed: PutAssetAdministrationShellDescriptor to PutAssetAdministrationShellDescriptorById New: PostAssetAdministrationShellDescriptor (*) Submodel Registry Changed Renamed: PutSubmodelDescriptor to PutSubmodelDescriptorById New: PostSubmodelDescriptor (*) Asset Administration Shell Repository Changed Renamed: GetAllAssetAdministrationShellsById to GetAssetAdministrationShellById, PutAssetAdministrationShell to PutAssetAdministrationShellById New: PostAssetAdministrationShell (*) Submodel Repository Changed Renamed: PutSubmodel to PutSubmodelById New: PostSubmodel (*) Asset Administration Shell Basic Discovery Changed Removed: GetAllAssetAdministrationShellIdsByAssetId, PutAssetId New: GetAllAssetAdministrationShellIdsByAssetLink, GetAllAssetLinksById, PutAllAssetLinksById, DeleteAllAssetLinksById (*) Submodel Discovery Basic Removed (*) Concept Description Repository Changed Renamed: GetAllConceptDescriptionsWithDataSpecificationReference to GetAllConceptDescriptionsByDataSpecificationReference, PutConceptDescription to PutConceptDescriptionById New: PostConceptDescription Operation Changes w.r.t. V1.0RC01 to V1.0RC02 Operation Change Old Operation Change New Kind of Change Comment PatchAssetAdministrationShell Removed PutSubmodelReference Removed Substituted by PostSubmodelReference PostSubmodelReference New For PutSubmodelReference RemoveSubmodelReference DeleteSubmodelReference Changed GetAllSubmodelReferences New PostSubmodelReference New GetAssetInformation New PutAssetInformation New PutSubmodel New PostSubmodelElement New PostSubmodelElementByPath New GetAllSubmodelElementsByParentPathAndSemanticId Removed GetAllSubmodelElementsBySemanticId Removed GetAASX Removed GetSerializationByIds GenerateSerializationByIds Renamed GetAllAASXPackageIds New GetAASXByPackageId New PostAASXPackage New PutAASXByPackageId New DeleteAASXByPackageId New PutAssetAdministrationShellDescriptor PutAssetAdministrationShellDescriptorById Changed Naming pattern byId PostAssetAdministrationDescriptor New PutSubmodelDescriptor PutSubmodelDescriptorById Changed Naming pattern byId PostSubmodelDescriptor New GetAllAssetAdministrationShellsById GetAssetAdministrationShellById Changed Naming pattern resource singular PostAssetAdministrationShell New PutAssetAdministrationShell PutAssetAdministrationShellById Changed Naming pattern byId PutSubmodel PutSubmodelById Changed Naming pattern byId PostSubmodel New GetAllAssetAdministrationShellIdsByAssetId Removed substituted by GetAllAssetAdministrationShellIdsByAssetLink and GetAllAssetLinksById PutAssetId Removed Substituted by PutAllAssetLinksById and DeleteAllAssetLinksById GetAllAssetAdministrationShellIdsByAssetLink New Before: GetAllAssetAdministrationShellIdsByAssetId GetAllAssetLinksById New PutAllAssetLinksById New DeleteAllAssetLinksById New GetAllSubmodelIdsBySemanticId Removed GetAllConceptDescriptionsWithDataSpecificationReference GetAllConceptDescriptionsByDataSpecificationReference Renamed Renaming With pattern By PutConceptDescription PutConceptDescriptionById Changed Naming pattern byId PostConceptDescription New