From 1649af8a8e3f638d574aba9bd5407f7ea980ac63 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Mon, 24 Mar 2025 17:16:26 +0100 Subject: [PATCH 01/22] update bilbliography DIN EN IEC 61406-1, now IEC --- .../IDTA-01002-3/modules/ROOT/pages/bibliography.adoc | 8 ++++---- .../IDTA-01002-3/modules/ROOT/pages/changelog.adoc | 1 + .../IDTA-01002-3/modules/ROOT/pages/general.adoc | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/bibliography.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/bibliography.adoc index 843da3fc..431c78be 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/bibliography.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/bibliography.adoc @@ -33,9 +33,9 @@ Internet Engineering Task Force (IETF), 2020. Online. Available: https://tools.ietf.org/html/rfc8820 [#bib6] -[6] DIN SPEC 91406: “Automatic identification of physical objects and information on physical objects in IT systems, particularly IoT systems”. -December 2019. Online. -Available: https://www.beuth.de/de/technische-regel/din-spec-91406/314564057 +[6] DIN EN IEC 61406-1: "Identification Link - Part 1: General requirements (IEC 61406-1:2022)". +December 2023. Online. +Available: https://www.dinmedia.de/en/standard/din-en-iec-61406-1/372053652 [#bib7] [7] Decentralized Identifiers (DIDs) v1.0. Edited by Manu Sporny, Amy Guy, Markus Sabadello, and Drummond Reed. @@ -62,7 +62,7 @@ Formal/2017-12-05. Version 2.5.1. December 2018. Online. -Available: www.omg.org/spec/UML/ +Available: https://www.omg.org/spec/UML/ [#bib11] [11] "RQL: A resource query language for REST". diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc index b65174b4..d4a8a080 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc @@ -41,6 +41,7 @@ Minor Changes: * Clarification on how to handle duplicate query parameters * Replace "servers" clause in OpenAPI files * Add notes for base64url-encoded values and order of "assetIds" query parameters +* update bibliography * xref:http-rest-api/http-rest-api.adoc#modifier-constraints[HTTP Modifier Constraints]: Adding note for metadata and value-only representations of Asset Administration Shells (https://github.com/admin-shell-io/aas-specs-api/issues/268[#268]) === Interface Changes w.r.t. V3.0.3 to V3.1 diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc index 425c73d2..48637813 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc @@ -157,7 +157,7 @@ These identifiers need to be globally unique and understandable by the community Furthermore, the identifiers need to support a versioning scheme for future updates and extensions of the metamodel. The identifiers defined in this document are reused in related resources, for instance REST API operations or in self-descriptions of implementing services. -Internationalized Resource Identifiers (IRIs), Uniform Resource Identifiers (URIs) xref:bibliography.adoc#bib5[[5\]] in particular, and the requirements of DIN SPEC 91406 xref:bibliography.adoc#bib6[[6\]], serve as the basic format. +Internationalized Resource Identifiers (IRIs), Uniform Resource Identifiers (URIs) xref:bibliography.adoc#bib5[[5\]] in particular, and the requirements of DIN EN IEC 61406 xref:bibliography.adoc#bib6[[6\]], serve as the basic format. Further design decisions include ‘https’ as the URI scheme, and the controlled domain name ‘admin-shell.io’ as the chosen authority. Both decisions guarantee the interoperability of the identifiers and their durability, since URIs are generally well-known and proven, while the domain is controlled and served through the Industrial Digital Twin Association (IDTA). All identifiers included in the ‘admin-shell.io’ domain are described in a lightweight catalogue in the form of Markdown documents; they are continuously maintained and updated link:https://github.com/admin-shell-io/id[https://github.com/admin-shell-io/id]. From 8ef1f305e4d4ccc30881bf8f48b7b750c27d7fb9 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Tue, 25 Mar 2025 15:43:24 +0100 Subject: [PATCH 02/22] fix xef to xref --- documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc index 5bbe62e1..4f11d3e2 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc @@ -48,7 +48,8 @@ xref:summary-and-outlook.adoc[] provides a summary and outlook. Annex xref:annex/serialization-modifier-examples.adoc[] contains examples for the serialization modifiers. Annex xref:annex/backus-naur-form.adoc[] defines the grammar language used in the specification. -Annex xref:annex/uml.adoc[] contains information about UML, while Annex xef:annex/uml-templates.adoc[] provides the tables used to specify UML classes etc. as used in this specification. +Annex xref:annex/uml.adoc[] contains information about UML, +while Annex xref:annex/uml-templates.adoc[] provides the tables used to specify UML classes etc. as used in this specification. Annex xref:annex/api-tables-templates.adoc[] explains the templates used to specify operations and interfaces. xref:annex/handling-constraints.adoc[] explains the numbering of constraints used in the specification. From fee49b3f32f182004585c96ee96a52dafb6fd078 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Tue, 25 Mar 2025 15:43:56 +0100 Subject: [PATCH 03/22] add / update copyright header --- .../modules/ROOT/pages/annex/api-tables-templates.adoc | 10 ++++++++++ .../modules/ROOT/pages/annex/backus-naur-form.adoc | 6 ++---- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/api-tables-templates.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/api-tables-templates.adoc index 52927fd9..df53c341 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/api-tables-templates.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/api-tables-templates.adoc @@ -1,3 +1,13 @@ +//// +Copyright (c) 2023 Industrial Digital Twin Association + +This work is licensed under a [Creative Commons Attribution 4.0 International License]( +https://creativecommons.org/licenses/by/4.0/). + +SPDX-License-Identifier: CC-BY-4.0 + +//// + [appendix] == Templates for Specification of APIs and API Operations diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/backus-naur-form.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/backus-naur-form.adoc index 3052b38c..ad544133 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/backus-naur-form.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/backus-naur-form.adoc @@ -6,8 +6,6 @@ https://creativecommons.org/licenses/by/4.0/). SPDX-License-Identifier: CC-BY-4.0 -Illustrations: -Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH //// @@ -32,8 +30,8 @@ where: * symbols that never appear on a left side are https://en.wikipedia.org/wiki/Terminal_symbol[terminals], while symbols that appear on a left side are https://en.wikipedia.org/wiki/Nonterminal_symbol[non-terminals] and are always enclosed between the pair of angle brackets <>, * terminals are enclosed with quotation marks: "text". "" is an empty string, * optional items are enclosed in square brackets: [], or suffixed with an additional (questionmark) symbol, ?, such as ?, -* items existing 0 or more times are enclosed in curly brackets are suffixed with an asterisk (\*) such as  ::= {}*, -* items existing 1 or more times are suffixed with an addition (plus) symbol, \+, such as  ::= {}+, +* items existing 0 or more times are enclosed in curly brackets are suffixed with an asterisk (\*) such as ::= {}*, +* items existing 1 or more times are suffixed with an addition (plus) symbol, \+, such as ::= {}+, * round brackets are used to explicitly define the order of expansion to indicate precedence, example: ( | ) , * text without quotation marks is an informal explanation of what is expected; this text is cursive if grammar is non-recursive and vice versa. From 974b345efdc35ae7acf7a03125b3b33e474bcd16 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 08:33:45 +0100 Subject: [PATCH 04/22] correct formatting --- .../http-rest-api/service-specifications-and-profiles.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc index 6eb3e5e8..12f8346d 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc @@ -477,7 +477,7 @@ h|Name: h|Submodel Registry Full Profile h|Profile Identifier: |`\https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-001` h|Feature h|Appearance |APIs and API Operations a| -__Submodel Registry API: + +__Submodel Registry API:__ + xref:specification/interfaces.adoc#GetAllSubmodelDescriptors[GetAllSubmodelDescriptors] + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] + PostSubmodelDescriptor + From 96363925f42e2a8914898ffb6e2dd765d3d9a5df Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 11:41:47 +0100 Subject: [PATCH 05/22] Querying now already part of version --- .../IDTA-01002-3/modules/ROOT/pages/summary-and-outlook.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/summary-and-outlook.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/summary-and-outlook.adoc index c1592901..a1f4ecdd 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/summary-and-outlook.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/summary-and-outlook.adoc @@ -20,4 +20,4 @@ In this version of the specification, HTTP/REST APIs are defined and mapped to t In subsequent versions of this specification, APIs using other technologies are planned to be supported, e.g. gRPC or MQTT. Additionally, further interfaces, service specifications, and profiles may be defined. -Querying will also be a topic. + From 17cd9a69ea5e12ef7f67f6bcce0f94d948d325b4 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 11:52:10 +0100 Subject: [PATCH 06/22] add overview of constraints --- .../IDTA-01002-3/modules/ROOT/nav.adoc | 2 ++ .../pages/annex/overview-constraints.adoc | 34 +++++++++++++++++++ .../modules/ROOT/pages/changelog.adoc | 3 +- .../modules/ROOT/pages/preamble.adoc | 3 +- 4 files changed, 40 insertions(+), 2 deletions(-) create mode 100644 documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc diff --git a/documentation/IDTA-01002-3/modules/ROOT/nav.adoc b/documentation/IDTA-01002-3/modules/ROOT/nav.adoc index de414ad2..f87b3471 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/nav.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/nav.adoc @@ -83,6 +83,8 @@ Shared .adoc file are used from https://github.com/admin-shell-io/aas-specs ** xref:annex/handling-constraints.adoc[Handling Constraints] +** xref:annex/overview-constraints.adoc[Overview Constraints] + ** xref:annex/uml.adoc[UML] * xref:changelog.adoc[Change Log] diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc new file mode 100644 index 00000000..f2748575 --- /dev/null +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc @@ -0,0 +1,34 @@ +//// +Copyright (c) 2023 Industrial Digital Twin Association + +This work is licensed under a [Creative Commons Attribution 4.0 International License]( +https://creativecommons.org/licenses/by/4.0/). + +SPDX-License-Identifier: CC-BY-4.0 + +//// + + +[appendix] += Overview Constraints (non-normative) +include::../includes/constraints.adoc[] + + +This annex gives an overview of the constraints contained in this document. No additional comments are added, for details please refer to the normative parts of the specification. + +For handling of constraints see xref:annex/handling-constraints.adoc[]. + +[[constraint-AASa-001]] +{aasa001} + +[[constraint-AASd-002]] +{aasa002} + +[[constraint-AASd-003]] +{aasa003} + +[[constraint-AASd-004]] +{aasa004} + +[[constraint-AASd-005]] +{aasa005} \ No newline at end of file diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc index d4a8a080..64b7350a 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc @@ -41,7 +41,8 @@ Minor Changes: * Clarification on how to handle duplicate query parameters * Replace "servers" clause in OpenAPI files * Add notes for base64url-encoded values and order of "assetIds" query parameters -* update bibliography +* update xref:bibliography.adoc[Bibliography] +* add xref:annex/overview-constraints.adoc[overview of constraints] to Annex * xref:http-rest-api/http-rest-api.adoc#modifier-constraints[HTTP Modifier Constraints]: Adding note for metadata and value-only representations of Asset Administration Shells (https://github.com/admin-shell-io/aas-specs-api/issues/268[#268]) === Interface Changes w.r.t. V3.0.3 to V3.1 diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc index 4f11d3e2..1250a8b2 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/preamble.adoc @@ -52,7 +52,8 @@ Annex xref:annex/uml.adoc[] contains information about UML, while Annex xref:annex/uml-templates.adoc[] provides the tables used to specify UML classes etc. as used in this specification. Annex xref:annex/api-tables-templates.adoc[] explains the templates used to specify operations and interfaces. -xref:annex/handling-constraints.adoc[] explains the numbering of constraints used in the specification. +xref:annex/handling-constraints.adoc[] explains the numbering of constraints used in the specification. +xref:annex/overview-constraints.adoc[] gives an (non-normative) overview of all constraints used in the documents. The xref:changelog.adoc[] describes metamodel changes compared to previous versions. From de7814d9f5c63d16bcab0bbbae808bc00ceb552b Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 11:57:05 +0100 Subject: [PATCH 07/22] fix link to figure 1 --- documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc | 4 ++-- .../http-rest-api/service-specifications-and-profiles.adoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc index 48637813..da2955e5 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc @@ -66,7 +66,7 @@ Additionally, it has an identifier to be identifiable within a given context. * *API-Operation-Instance*: instance of an API-Operation-Implementation which has an endpoint to get invoked. .Services, Interfaces & APIs and Operations -[[i40-service-model]] +[[image-i40-service-model]] [plantuml, i40-service-model, svg] .... include::partial$diagrams/i40-service-model.puml[] @@ -123,7 +123,7 @@ Note 1: values remain unchanged with content=metadata. * SEARCHALL: returns a list fo resources based on asset links. ==== -Note 2: these methods are intended for the naming of interfaces as described in <>. +Note 2: these methods are intended for the naming of interfaces as described in <>. They shall not be interpreted as new protocol methods, e.g. on HTTP level. ==== diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc index 12f8346d..e0939c34 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc @@ -15,7 +15,7 @@ include::../includes/constraints.adoc[] [#service-specifications-and-profiles] = Service Specifications and Profiles -xref:general.adoc#i40-service-model[Figure] in Clause xref:general.adoc[] defines that a service specification contains at least one API and that an API contains at least one API Operation. +xref:general.adoc#image-i40-service-model[] in Clause xref:general.adoc[] defines that a service specification contains at least one API and that an API contains at least one API Operation. The profiles defined in this clause present complete service specifications and their subsets. From d44232ec1cfdbc46944b91a1c6a8c602706998fc Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 11:58:14 +0100 Subject: [PATCH 08/22] cursive for consistency --- documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc index d1af9783..3e8327dc 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc @@ -360,7 +360,7 @@ Variant A is the classical graphical representation as defined in xref:bibliogra Variant B is a short form. The name of the class that _Class3_ is inheriting from is depicted in the upper right corner. -Variant C not only shows which class Class3 instances are inheriting from, but also what they are inheriting. +Variant C not only shows which class _Class3_ instances are inheriting from, but also what they are inheriting. This is depicted by the class name it is inheriting from, followed by "::" and then the list of all inherited elements - here attribute _class2_. Typically, the inherited elements are not shown. From ee30e87b6f68309cd966b69eca529308d71f81e0 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 12:06:20 +0100 Subject: [PATCH 09/22] add Header for Enumeration --- documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc index 3e8327dc..1cd229a2 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc @@ -221,6 +221,7 @@ It contains two literal values, "a" and "b". It is a class with stereotype \<>. The literals owned by the enumeration are ordered. +.Enumeration [[image-76-enumeration]] [plantuml, 76-enumeration, svg] .... From a3d31a2659afe83216718690c31396dd74cf777a Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 12:08:52 +0100 Subject: [PATCH 10/22] fix footnote --- documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc index 1cd229a2..52abdfff 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc @@ -23,8 +23,7 @@ The formal specification can be found in xref:bibliography.adoc#bib10[[10\]]. <> shows a class with name "Class1" and an attribute with name "attr" of type _Class2_. Attributes are owned by the class. Some of these attributes may represent the end of binary associations, see also <>. -In this case, the instance of _Class2_ is navigable via the instance of the owning class _Class1_.footnote:[„ -Navigability notation was often used in the past according to an informal convention, whereby non-navigable ends were assumed to be owned by the Association whereas navigable ends were assumed to be owned by the Classifier at the opposite end. +In this case, the instance of _Class2_ is navigable via the instance of the owning class _Class1_.footnote:[Navigability notation was often used in the past according to an informal convention, whereby non-navigable ends were assumed to be owned by the Association whereas navigable ends were assumed to be owned by the Classifier at the opposite end. This convention is now deprecated. Aggregation type, navigability, and end ownership are separate concepts, each with their own explicit notation. Association ends owned by classes are always navigable, while those owned by associations may be navigable or not. From 5e0ccbf5e21c12531c6eac11ecccbc977fe818d9 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 12:46:51 +0100 Subject: [PATCH 11/22] fix {} --- .../modules/ROOT/pages/http-rest-api/http-rest-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 9163c838..39f45c4a 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 @@ -338,8 +338,8 @@ The following constraints apply for the combination of modifiers: * For Content=Value, the requested object shall always be serialized to an unnamed JSON Object or Array. This means that the response object must not have a property with the object’s idShort at the root level. * If Level=Core and Content=Value, only the requested object and the direct children without their value (empty value) will be returned in value serialization. -If a direct child is a SubmodelElementCollection, "": \{} will be returned. -If a direct child is a SubmodelElementList, "": [] will be returned. +If a direct child is a SubmodelElementCollection, "": `{}` will be returned. +If a direct child is a SubmodelElementList, "": `[]` will be returned. * The combination of Content=Metadata and Extent=WithBLOBValue is not allowed. * If parameter Content is set to "Metadata" then Level shall not be used. A server shall respond with a ClientErrorBadRequest in this case. From 017c3ecd3eb579e2485553fc2deb5974f4c752f1 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 12:50:53 +0100 Subject: [PATCH 12/22] add xref to modifiers + add subheader for modifiers --- .../ROOT/pages/http-rest-api/http-rest-api.adoc | 2 +- .../interfaces-operation-parameters.adoc | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) 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 39f45c4a..7892e1fe 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 @@ -329,7 +329,7 @@ Additional classes needed for payload of the HTTP/REST API specification can be == Modifier Constraints -To use link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/mappings/mappings.html#_format_metadata_metadata_serialization[metadata objects] as described in xref:bibliography.adoc#bib1[[1]]., modifiers are implemented as HTTP query parameters or path suffixes. +To use link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/mappings/mappings.html#_format_metadata_metadata_serialization[metadata objects] as described in xref:bibliography.adoc#bib1[[1]]., xref:specifiction/interfaces-operation-parameters.adoc[modifiers] are implemented as HTTP query parameters or path suffixes. For example, a request for a specific submodel may look like: + GET /submodel/$value?level=deep&extent=withBlobValue diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc index b45dea64..13db3ea0 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc @@ -21,7 +21,7 @@ This clause specifies the parameters for API operations. [#SerializationModifier] == SerializationModifiers in Operations -*Definition* +=== Definition For GET operations, a SerializationModifier indicates the requester’s expected or desired response content. For PUT and PATCH operations, a SerializationModifier indicates the input content. @@ -32,8 +32,8 @@ When combined, these enumerations influence the input or response content of the Note: values remain unchanged with content=metadata. ==== -[arabic] -. *Enumeration: Level* + +=== Enumeration: Level The first enumeration _Level_ indicates the depth of the structure of the response or input content. @@ -53,8 +53,8 @@ By this, a client can iterate the hierarchy step by step. Note: level parameters are mapped to the query parameter "?level" in the HTTP/REST APIs, see also xref:http-rest-api/http-rest-api.adoc#modifier-constraints[Modifier Constraints]. ==== -[arabic,start=2] -. *Enumeration: Content* + +=== Enumeration: Content The second enumeration _Content_ indicates the kind of serialization of the response or input content. @@ -85,8 +85,8 @@ e|Path a|Returns the idShort of the requested element and a list of _idShort_ pa Note: level parameters are mapped to path suffixes "/$" in the HTTP/REST APIs, see also xref:http-rest-api/http-rest-api.adoc#modifier-constraints[Modifier Constraints]. ==== -[arabic,start=3] -. *Enumeration: Extent* + +=== Enumeration: Extent The third enumeration _Extent_ indicates to which extent the response or input content is being serialized. At this stage, the listed values could also be represented as binary values on BLOB-elements. From f81b2e76b859794acd53e1beab966ffab3772be2 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 12:52:45 +0100 Subject: [PATCH 13/22] typo --- .../modules/ROOT/pages/http-rest-api/http-rest-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 7892e1fe..14777692 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 @@ -329,7 +329,7 @@ Additional classes needed for payload of the HTTP/REST API specification can be == Modifier Constraints -To use link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/mappings/mappings.html#_format_metadata_metadata_serialization[metadata objects] as described in xref:bibliography.adoc#bib1[[1]]., xref:specifiction/interfaces-operation-parameters.adoc[modifiers] are implemented as HTTP query parameters or path suffixes. +To use link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/mappings/mappings.html#_format_metadata_metadata_serialization[metadata objects] as described in xref:bibliography.adoc#bib1[[1]], xref:specifiction/interfaces-operation-parameters.adoc[modifiers] are implemented as HTTP query parameters or path suffixes. For example, a request for a specific submodel may look like: + GET /submodel/$value?level=deep&extent=withBlobValue From b61914cd8d61bd74bc12ae38a0dd28cf3deb2864 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 13:53:20 +0100 Subject: [PATCH 14/22] add xref and link --- .../modules/ROOT/pages/http-rest-api/http-rest-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 14777692..21fff096 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 @@ -823,7 +823,7 @@ This class is not part of the metamodel. h|Inherits from 3+|-- h|Attribute h|Explanation h|Type h|Card. -e|packageId a|File server specific package id |ShortIdType |1 -e|aasId a|Asset Administration Shell unique identifier |Identifier |0..* +e|packageId a|File server specific package id |xref:specification/interfaces-payload.adoc#ShortIdType[ShortIdType] |1 +e|aasId a|Asset Administration Shell unique identifier |link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/spec-metamodel/datatypes.html#Identifier[Identifier] |0..* |=== From a636ee364a4fd69e998406816d37e0f1080eae8a Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 13:57:38 +0100 Subject: [PATCH 15/22] remove empty note at the bottom --- .../modules/ROOT/partials/diagrams/i40-service-model.puml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/i40-service-model.puml b/documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/i40-service-model.puml index 09095335..b74f85b9 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/i40-service-model.puml +++ b/documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/i40-service-model.puml @@ -49,7 +49,6 @@ service_impl <|. service_instance: <> api_impl <|. api_instance: <> api_op_impl <|. op_instance: <> -api_op .[hidden]. Note -api_op_impl .[hidden]. Note + @enduml From 91286805419ff9d3725671e2271c70b574165445 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 13:58:07 +0100 Subject: [PATCH 16/22] Content and Metadata start with capital letter --- .../ROOT/pages/annex/serialization-modifier-examples.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/serialization-modifier-examples.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/serialization-modifier-examples.adoc index 07039b1e..9f0966d0 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/serialization-modifier-examples.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/serialization-modifier-examples.adoc @@ -24,7 +24,7 @@ A SubmodelElementList with five elements cannot be patched with a SubmodelElemen A SubmodelElementList with five elements can be patched with a SubmodelElementList with less than five elements since all required elements starting from index 0 already exist. ==== -Note: values remain unchanged with content=metadata. +Note: values remain unchanged with Content=Metadata. ==== === Examples for GET Operations From 0989e414f1636402f586928b2c195ee0ffc1a905 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 14:45:32 +0100 Subject: [PATCH 17/22] formatting --- .../interfaces-operation-parameters.adoc | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc index 13db3ea0..cb909d32 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces-operation-parameters.adoc @@ -73,7 +73,7 @@ For Content equal to Path see Clause link:https://admin-shell-io.github.io/aas-s .Content Parameters [%autowidth,width="100%",cols="35%,65%",options="header",] |=== -|*Value* h|Explanation +h|Value h|Explanation e|Normal (Default) a|The standard serialization of the model element or child elements is applied. e|Metadata a|Only metadata of an element or child elements is returned; the value is not . e|Value a|Only the raw value of the model element or child elements is returned; it is commonly referred to as _ValueOnly_-serialization. @@ -117,17 +117,16 @@ POST operations do not use SerializationModifiers. .Applicability of SerializationModifiers [%autowidth,width="100%",cols="37%,13%,28%,22%",options="header",] |=== -|*Resource Name* |*Level Modifier* |*Content Modifier* |*Extent Modifier* +h|Resource Name h|Level Modifier h|Content Modifier h|Extent Modifier |Asset Administration Shell |No |Normal/ Reference |No |Submodel Reference |No |No |No -|Submodel |Deep/Core |Normal/ + -Metadata/Value/Reference/Path a| +|Submodel |Deep/Core |Normal/ Metadata/ Value/ Reference/ Path a| WithoutBLOBValue/ WithBLOBValue 4+|*SubmodelElements* -|SubmodelElementCollection |Deep/Core |Normal/ Metadata/ Value/ Reference/Path a| +|SubmodelElementCollection |Deep/Core |Normal/ Metadata/ Value/ Reference/ Path a| WithoutBLOBValue/ WithBLOBValue @@ -142,8 +141,7 @@ WithoutBLOBValue/ WithBLOBValue -|BasicEventElement |No |Normal/ + -Metadata/Value/Reference |No +|BasicEventElement |No |Normal/ Metadata/ Value/ Reference |No |Capability |No |Normal/Reference |No |Operation |No |Normal/Reference |No 4+|*DataElements* @@ -158,7 +156,7 @@ WithoutBLOBValue/ WithBLOBValue -|File |No |Normal/ Metadata/Value/Reference |No +|File |No |Normal/ Metadata/ Value/ Reference |No |=== ==== From 42e926983f305d840f442b955962ced7a0a7acdf Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 14:52:12 +0100 Subject: [PATCH 18/22] substitute " + formatting --- .../pages/http-rest-api/http-rest-api.adoc | 90 ++++++++++--------- 1 file changed, 49 insertions(+), 41 deletions(-) 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 21fff096..ce095de7 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 @@ -52,6 +52,7 @@ https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.1 This clause gives an overview of the HTTP/REST API and describes general design decisions. +[[design-decisions]] == Design Decisions The following design decisions and constraints hold for the HTTP/REST API: @@ -60,13 +61,13 @@ The following design decisions and constraints hold for the HTTP/REST API: This leads to the constraint that one operation can only provide one type of a resulting payload. * This document assumes version 1.1 of HTTP. * An endpoint of the HTTP/REST API shall always use HTTPS (Port 443) with an up-to-date level of encryption. -* The SerializationModifier “content” changes the type the of payload for inputs or results. -To ensure type-safe APIs, this parameter is mapped to the path suffixes “/$value”, “/$metadata”, “/$reference”, and “/$path”. “content=Normal” is mapped to the path without any “/$” suffix. -* Generic SerializationModifiers changing the size of payload for input or result have been mapped to corresponding query parameters, e.g. ”?level=” or “?extent=”. -* Query parameters are also used when the type of a resulting payload is a list of objects and the type remains the same, while the query parameter filters the content of the list, e.g. GetAllSubmodels with optional query parameters “?semanticId=” or “?idShort=”. +* The SerializationModifier "content" changes the type the of payload for inputs or results. +To ensure type-safe APIs, this parameter is mapped to the path suffixes "/$value", "/$metadata", "/$reference", and "/$path". "content=Normal" is mapped to the path without any "/$" suffix. +* Generic SerializationModifiers changing the size of payload for input or result have been mapped to corresponding query parameters, e.g. "?level=" or "?extent=". +* Query parameters are also used when the type of a resulting payload is a list of objects and the type remains the same, while the query parameter filters the content of the list, e.g. GetAllSubmodels with optional query parameters "?semanticId=" or "?idShort=". * Complete objects are provided as requested payloads, e.g. a complete submodel. -This corresponds to the generic SerializationModifier content=”Normal”. -Reduced objects can be requested by the path suffix “/$”. +This corresponds to the generic SerializationModifier content="Normal". +Reduced objects can be requested by the path suffix "/$". // Previously pointing to Clause 12.5 See xref:bibliography.adoc#bib1[[1]] for further details. Exceptions to this rule are API Operations requiring pagination and error cases. @@ -74,9 +75,9 @@ Exceptions to this rule are API Operations requiring pagination and error cases. Using ?extent=WithBLOBValue includes blobs for submodel elements of kind BLOB. * Submodels define a hierarchical structure. Certain operations use an idShortPath to access deeper parts in the hierarchy. -To easily support this in the REST API, “.” or “[index]” is used as a delimiter in the idShortPaths. +To easily support this in the REST API, "." or "[index]" is used as a delimiter in the idShortPaths. Please see <>. -Since an idShortPath could include square brackets like “[index]”, the idShortPath must be URL-encoded. +Since an idShortPath could include square brackets like "[index]", the idShortPath must be URL-encoded. * Identifiers of Identifiables are base64url-encoded to be passed to the HTTP/REST API (see https://www.base64url.com/). These may be identifiers for Asset Administration Shells, Submodels, or Concept Descriptions. + Identifiers may also be passed as base64url-encoded query parameters, e.g. for semanticId or assetId. @@ -91,22 +92,22 @@ Note: Encoding JSON objects may lead to different encoded strings, depending e.g ==== * When base64url or base64-encoding is mentioned in connection with string values (e.g. Identifiers), the UTF-8 decoded byte array representation of that string is used for the base64url or base64-encoding. -* When retrieving AssetAdministrationShells (/shells, /lookup/shells), a query parameter “?assetids=” can be specified. +* When retrieving AssetAdministrationShells (/shells, /lookup/shells), a query parameter "?assetids=" can be specified. Such assetId may be a globalAssetId or specificAssetId. The corresponding key-value-pair is first serialized to JSON and then base64url-encoded. -The resulting encoded string is the value of “?assetids=”. +The resulting encoded string is the value of "?assetids=". ==== Note: In case more than one globalAssetId or specificAssetId is provided, their order shall not affect the result. ==== -* In some operations, references are part of the query parameters e.g. “?semanticId=”. +* In some operations, references are part of the query parameters e.g. "?semanticId=". The corresponding reference is first serialized to JSON and then base64url-encoded. -The resulting encoded string is the value of “?semanticId=”. -* Even though the metamodel of the AAS distinguishes between the attributes “semanticId” and “supplementalSemanticId”, the query parameter “?semanticId” targets both. +The resulting encoded string is the value of "?semanticId=". +* Even though the metamodel of the AAS distinguishes between the attributes "semanticId" and "supplementalSemanticId", the query parameter "?semanticId" targets both. * This encoding (serialize to JSON + base64url) is also used for SpecificAssetIds, i.e. for GetAllAssetAdministrationShellIdsByAssetLink (/lookup/shells). -For the example “[\{"name": "globalAssetId","value": "http://example.company/myAsset"},\{"name": "myOwnInternalAssetId","value": "12345ABC"}]”, the resulting base64url-encoded value of the query parameter is + -“?assetIds=W3sibmFtZSI6ICJnbG9iYWxBc3NldElkIiwidmFsdWUiOiAiaHR0cDovL2V4YW1wbGUuY29tcGFueS9teUFzc2V0In0seyJuYW1lIjogIm15T3duSW50ZXJuYWxBc3NldElkIiwidmFsdWUiOiAiMTIzNDVBQkMifV0”. + +For the example "[\{"name": "globalAssetId","value": "http://example.company/myAsset"},\{"name": "myOwnInternalAssetId","value": "12345ABC"}]", the resulting base64url-encoded value of the query parameter is + +"?assetIds=W3sibmFtZSI6ICJnbG9iYWxBc3NldElkIiwidmFsdWUiOiAiaHR0cDovL2V4YW1wbGUuY29tcGFueS9teUFzc2V0In0seyJuYW1lIjogIm15T3duSW50ZXJuYWxBc3NldElkIiwidmFsdWUiOiAiMTIzNDVBQkMifV0". + If several key-value-pairs are included, all must be part of the key-value-pairs on the server. * Comparisons of idShort are made case-sensitive in the HTTP/REST API to avoid repeating toupper()/tolower() conversions. @@ -115,21 +116,28 @@ Note: this is conformant to the change made in Part 1 V3.0 xref:bibliography.ado ==== * GetAll…-API Operations will retrieve a list of objects as the resulting payload, e.g. GetAllSubmodelElements. -* The splitting of big result sets into smaller pieces, commonly referred to as “pagination”, is executed using the cursor query parameter. +* The splitting of big result sets into smaller pieces, commonly referred to as "pagination", is executed using the cursor query parameter. Therefore, result objects for GetAll…-API Operations and others requiring pagination return their content inside a Result structure. See <> for further explanations. + * In general, only GET, POST, PUT, PATCH and DELETE are used. POST is used to create new objects and to invoke operations. + [[superpaths]] -* Some interfaces may be combined in a so-called “superpaths”, e.g. the Asset Administration Shell Repository Interface may be combined with the AAS Interface and the Submodel Interface. -This results in a complete path like “/shells/\{aas-identifier}/submodels/\{submodel-identifier}/*”. +* Some interfaces may be combined in a so-called "superpaths", e.g. the Asset Administration Shell Repository Interface may be combined with the AAS Interface and the Submodel Interface. +This results in a complete path like "/shells/\{aas-identifier}/submodels/\{submodel-identifier}/*". This is especially useful when all data is hosted in the same repository. Superpaths are defined as part of the service specifications and profiles. -* The attribute AssetAdministrationShell/submodels (array of References) maps to the path segment “/submodel-refs” to distinguish it from the superpath segment “/submodels” (array of Submodels). -* Each interface includes a “/description” operation for self-discovery to provide detailed information about the interface. -A server supporting the HTTP/REST API may also provide a server global “/description” to provide the information about all available profiles on that server. + +* The attribute AssetAdministrationShell/submodels (array of References) maps to the path segment "/submodel-refs" to distinguish it from the superpath segment "/submodels" (array of Submodels). + +* Each interface includes a "/description" operation for self-discovery to provide detailed information about the interface. +A server supporting the HTTP/REST API may also provide a server global "/description" to provide the information about all available profiles on that server. + * The AAS Query Language is serialised as a JSON Object. -* The recursive nature of the reference class (Reference/referredSemanticId points to Reference again) cannot be represented in SwaggerHub due to a bug in the SwaggerUI code. Therefore, the additional class “ReferenceParent" has been added. “ReferenceParent" shall not be used in productive operations and is only a placeholder for “Reference”. When implementing generated code originating from the SwaggerHub schemas, please delete “ReferenceParent” and add its attributes to “Reference”. + +* The recursive nature of the reference class (Reference/referredSemanticId points to Reference again) cannot be represented in SwaggerHub due to a bug in the SwaggerUI code. Therefore, the additional class "ReferenceParent" has been added. "ReferenceParent" shall not be used in productive operations and is only a placeholder for "Reference". When implementing generated code originating from the SwaggerHub schemas, please delete "ReferenceParent" and add its attributes to "Reference". + * This document does not make any statement about the expected behavior when query parameters with cardinality 1 (e.g. level, extent, etc.) are present more than once in a URL, e.g., "/...?level=deep&level=core". It is up to the implementation how to handle such cases. It is strongly discouraged to make such calls as the result might not be deterministic. [#api-versioning] @@ -158,7 +166,7 @@ image::aas-api-versioning-url-scheme.svg[width=481,height=110] As different solutions also provide different advantages and disadvantages, URL-based versioning is recommended for the AAS API. Among other advantages, implementation complexity on clients as well as servers is rather low and different versions can be easily accessed through browsers without the need for specific development tools or extensions. -Upcoming implementations of AAS related servers may implement the version prefix “api/v/” to provide information of the specific major version regarding AAS Part 2 version, where denotes the implemented major version, e.g. “api/v3/” (see <>). +Upcoming implementations of AAS related servers may implement the version prefix "api/v/" to provide information of the specific major version regarding AAS Part 2 version, where denotes the implemented major version, e.g. "api/v3/" (see <>). As minor releases of one major version must not contain any breaking changes, the declaration of the minor version can be omitted. Nevertheless, AAS servers may decide to use different paths depending on their context, see <>. The fragment before the functional endpoint is not necessarily the version information itself, it may also be a tenant ID or any other information the server decides to use. A client shall not assume that the pattern from <> is supported by all servers. @@ -167,9 +175,9 @@ Nevertheless, AAS servers may decide to use different paths depending on their c [[aas-api-versioning-url-scheme2]] image::aas-api-versioning-url-scheme2.png[width=481,height=110] -Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. +Finally, it is recommended to include an additional "/description" endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles. -The “/description” will be extended with additional information in later versions. +The "/description" will be extended with additional information in later versions. ==== Note: The profile identifiers provided at the "/description" endpoint (see Clause xref:specification/interfaces-payload.adoc#service-description[]) contain both the major and minor version declaration. @@ -191,9 +199,9 @@ Technically, the idShortPath is a string and the idShorts are separated by a dot image::se-hierarchy.png[image24,width=642,height=367] The example hierarchy in <> shows a Submodel with a hierarchical structure of SubmodelElements. -The submodel can be addressed by its global identifier “https://admin-shell.io/sampleSM”. +The submodel can be addressed by its global identifier "https://admin-shell.io/sampleSM". The other elements in the figure do not have a global identifier; they are, however, uniquely identifiable and addressable by the submodel identifier and the idShortPath. -The idShortPath in this example pointing to the Property p1 is “sme1.sme2[0].p1”. +The idShortPath in this example pointing to the Property p1 is "sme1.sme2[0].p1". The hierarchy is built on parent-child relations between the elements. There are four elements which can aggregate SubmodelElements and create deeper hierarchical structures. The elements are Submodel, SubmodelElementCollection, SubmodelElementList, and Entity. @@ -224,7 +232,7 @@ IdshortPaths are URL-encoded to also allow square brackets. ==== ==== -Note 2: in the example above, “aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ” is the base64url-encoding of “https://admin-shell.io/sampleSM”, “sme1.sme2%5B0%5D.p1” is the URL-encoding of “sme1.sme2[0].p1”, and “sme1.sme2%5B0%5D” is the URL-encoding of “sme1.sme2[0]”. +Note 2: in the example above, "aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ" is the base64url-encoding of "https://admin-shell.io/sampleSM", "sme1.sme2%5B0%5D.p1" is the URL-encoding of "sme1.sme2[0].p1", and "sme1.sme2%5B0%5D" is the URL-encoding of "sme1.sme2[0]". ==== [#pagination] @@ -233,7 +241,7 @@ Note 2: in the example above, “aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ” i Pagination is a commonly used pattern to break down potentially long result lists into smaller pieces for a better control of the network and computational load on both the server and the client side. For instance, the OData protocol xref:bibliography.adoc#bib8[[8\]] provides guidelines for parameters and behavior on the client and server side. In addition, the proposals of the RFC 8977 footnote:[see Chapter 2.4 of RFC 8977] present a best practice for web APIs. -In the scope of the AAS HTTP/REST API, the query parameter “cursor” controls, which part of a longer result set is returned. +In the scope of the AAS HTTP/REST API, the query parameter "cursor" controls, which part of a longer result set is returned. The AAS client may define the maximum page size of the result list through the limit parameter. The server is allowed to return less elements than requested. @@ -242,7 +250,7 @@ If the limit parameter is not specified, the server may decide the number of ele Pagination is currently only defined for the HTTP/REST API. Other APIs might introduce different patterns to control the response content. -Pagination is controlled by the client via the query parameters “cursor” and “limit”. +Pagination is controlled by the client via the query parameters "cursor" and "limit". They can be combined with all other query parameters as defined in this document and listed in the following table: .Parameters for Pagination @@ -268,7 +276,7 @@ Note 1: this constraint prohibits that an empty cursor value is sent by the clie ==== Note 2: if the client sends a request without a cursor query parameter, the server must interpret it as if the client wants to retrieve the results from the very beginning. -A client may send the query parameter “limit" without any cursor. +A client may send the query parameter "limit" without any cursor. In that case, the server must return at max the specified number of result items from the beginning. ==== @@ -660,9 +668,9 @@ Note: Same endpoint as for the Asset Administration Shell Registry Interface bul |=== [#async-invocation-of-se-operation] -== Asynchronous Invocation of the SubmodelElement “Operation” +== Asynchronous Invocation of the SubmodelElement "Operation" -The invocation of the SubmodelElement “Operation” is the only call that can appear either synchronously or asynchronously in the current version of the specification. +The invocation of the SubmodelElement "Operation" is the only call that can appear either synchronously or asynchronously in the current version of the specification. The expected behavior is therefore explained in detail. .Sequence for asynchronous invocations of the SubmodelElement 'Operation' @@ -676,21 +684,21 @@ The client informs the server whether it is interested in a synchronous (asynchr In case of a synchronous interaction, the communication channel is kept open until the server has processed the request and responds with an OperationResult object, or a timeout or other kind of error occurs. In the asynchronous pattern, the server immediately responds with an Accepted (status code: 202) message containing the link to an endpoint where the client can fetch status information about his request (see <>). -This status endpoint is also located at the same SubmodelElement “Operation”, followed by the path segments "/operation-status/\{handleId}”. +This status endpoint is also located at the same SubmodelElement "Operation", followed by the path segments "/operation-status/\{handleId}". In case the request is incorrect and the server already recognizes it, the server responds directly with the according status code, e.g. 400. If the server can only recognize the error during later processing and not at the time it receives the request, it responds with an Accepted (202) message at first. Hence, a received Accepted message does not guarantee the client that its request is valid in every case. -If the server has not finished processing the request, the status endpoint responds with an BaseOperationResult object with the attribute “executionState” set to “Running”. +If the server has not finished processing the request, the status endpoint responds with an BaseOperationResult object with the attribute "executionState" set to "Running". As soon as the processing is finished, the status endpoints deliver a Found (HTTP status code 302) response with the location of the result in the Location response header. -The result is, similar to the status information, provided at the same SubmodelElement “Operation”, followed by the path segments "/operation-result/\{handleId}”. +The result is, similar to the status information, provided at the same SubmodelElement "Operation", followed by the path segments "/operation-result/\{handleId}". -In case incorrect inputs have been provided by the client but the server was only able to recognize this during processing, or if the server perceived any other error during processing, the server must still provide the OperationResult object with status code 200 and set the attribute “executionState” to “Failed”. +In case incorrect inputs have been provided by the client but the server was only able to recognize this during processing, or if the server perceived any other error during processing, the server must still provide the OperationResult object with status code 200 and set the attribute "executionState" to "Failed". ==== -Note: the invocation of the SubmodelElement “Operation” may also be conducted in the “ValueOnly” content. -In this case, the “/$value” path segment is added to the previously mentioned endpoints. +Note: the invocation of the SubmodelElement "Operation" may also be conducted in the "ValueOnly" content. +In this case, the "/$value" path segment is added to the previously mentioned endpoints. ==== == Bulk Operations @@ -710,11 +718,11 @@ The pattern for these operations follows the one introduced in <>). -As long as the request is processed, the status endpoint responds with “OK” with an optional information for the client when it shall ask again ("Retry-After"). +As long as the request is processed, the status endpoint responds with "OK" with an optional information for the client when it shall ask again ("Retry-After"). As soon as the server was able to process the request, the status endpoint provides a redirect to the location of the result. The result endpoint may either signal the client a success of the operation without any additional content, or an error together with a detailed error message in the body. A server may remove information about the result of a bulk request after a certain amount of time. From 17958373780bdc24a831b4da7d5af8a0a50576b5 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 14:55:18 +0100 Subject: [PATCH 19/22] add link to pagination chapter --- .../service-specifications-and-profiles.adoc | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc index e0939c34..5c1db823 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc @@ -136,7 +136,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1.0_SSP-001 @@ -175,7 +175,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1.0_SSP-002[https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1.0_SSP-002] @@ -235,7 +235,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.1.0_SSP-001 @@ -271,7 +271,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.1.0_SSP-002[https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.1.0_SSP-002] @@ -302,7 +302,7 @@ Content: Normal, Value Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.1.0_SSP-003[https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.1.0_SSP-003] @@ -339,7 +339,7 @@ JSON for descriptions and error messages AASX for packages -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.1.0_SSP-001 @@ -382,7 +382,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.0_SSP-001 @@ -408,7 +408,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.0_SSP-002 @@ -431,7 +431,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination | Not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] | Not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.0_SSP-003 @@ -453,7 +453,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |SerializationModifier |not applicable |SerializationFormat |JSON -|Pagination | Not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] | Not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.0_SSP-004 @@ -489,7 +489,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification/V3.1.0_SSP-001 @@ -511,7 +511,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification/V3.1.0_SSP-002 @@ -534,7 +534,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Not Supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Not Supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification/V3.1.0_SSP-003 @@ -556,7 +556,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |SerializationModifier |not applicable |SerializationFormat |JSON -|Pagination |Not Supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Not Supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification/V3.1.0_SSP-004 @@ -590,7 +590,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.1.0_SSP-001 @@ -613,7 +613,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.1.0_SSP-002 @@ -702,7 +702,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1.0_SSP-001 @@ -753,7 +753,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1.0_SSP-002 @@ -774,7 +774,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |SerializationModifier a| not applicable |SerializationFormat |JSON -|Pagination |not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1.0_SSP-003 @@ -842,7 +842,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.0_SSP-001 @@ -881,7 +881,7 @@ Content: Normal, Metadata, Value, Reference, Path Extent: WithBLOBValue, WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.0_SSP-002 @@ -947,7 +947,7 @@ Content: Normal, Metadata Extent: WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.0_SSP-003 @@ -995,7 +995,7 @@ Content: Normal, Metadata Extent: WithoutBLOBValue |SerializationFormat |JSON -|Pagination |supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.0_SSP-004 @@ -1017,7 +1017,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |SerializationModifier a| not applicable |SerializationFormat |JSON -|Pagination |not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.0_SSP-005 @@ -1057,7 +1057,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON -|Pagination |Supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/ConceptDescriptionRepositoryServiceSpecification/V3.1.0_SSP-001 @@ -1078,7 +1078,7 @@ xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] |SerializationModifier |not applicable |SerializationFormat |JSON -|Pagination |not supported +|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== See: https://app.swaggerhub.com/apis/Plattform_i40/ConceptDescriptionRepositoryServiceSpecification/V3.1.0_SSP-002 From f8cf51468e294f987eec256e409e6f86cbb8fd50 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 14:57:18 +0100 Subject: [PATCH 20/22] add link to chapter serialization modifier --- .../service-specifications-and-profiles.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc index 5c1db823..7e9cfcbd 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc @@ -20,7 +20,7 @@ xref:general.adoc#image-i40-service-model[] in Clause xref:general.adoc[] define The profiles defined in this clause present complete service specifications and their subsets. For instance, the profile “RepositoryServiceSpecification/V3.1_SSP-002” contains the API Operation “GetAllSubmodels” but not “PostSubmodelElementByPath”, while the more comprehensive “RepositoryServiceSpecification/V3.1_SSP-001” contains both. -Furthermore, profiles also define which of the SerializationModifiers (content, extent, level) or serialization formats (JSON) can be used or whether pagination or asynchronous operations are available. +Furthermore, profiles also define which of the SerializationModifiers (Content, Extent, Level) or serialization formats (JSON) can be used or whether pagination or asynchronous operations are available. .Overview of Service Specifications and the Contained APIs @@ -451,7 +451,7 @@ xref:specification/interfaces.adoc#QueryAssetAdministrationShellDescriptors[Quer _Description API:_ + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] -|SerializationModifier |not applicable +|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON |xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] | Not supported |=== @@ -554,7 +554,7 @@ xref:specification/interfaces.adoc#QuerySubmodelDescriptors[QuerySubmodelDescrip __Description API:__ + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] -|SerializationModifier |not applicable +|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON |xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |Not Supported |=== @@ -772,7 +772,7 @@ QueryAssetAdministrationShells _Description API:_ + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] -|SerializationModifier a| not applicable +|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] a| not applicable |SerializationFormat |JSON |xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== @@ -1015,7 +1015,7 @@ QuerySubmodels _Description API:_ + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] -|SerializationModifier a| not applicable +|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] a| not applicable |SerializationFormat |JSON |xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== @@ -1076,7 +1076,7 @@ QueryConceptDescriptions _Description API:_ + xref:specification/interfaces.adoc#GetSelfDescription[GetDescription] -|SerializationModifier |not applicable +|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable |SerializationFormat |JSON |xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported |=== From c53432ea9e6c5cd9be1096fd3a4a1d52a58b3a67 Mon Sep 17 00:00:00 2001 From: Birgit Boss Date: Wed, 26 Mar 2025 17:31:35 +0100 Subject: [PATCH 21/22] removal of chapter "Security" --- .../IDTA-01002-3/modules/ROOT/nav.adoc | 2 - .../modules/ROOT/pages/changelog.adoc | 9 ++-- .../ROOT/pages/http-rest-api/security.adoc | 49 ------------------- 3 files changed, 5 insertions(+), 55 deletions(-) delete mode 100644 documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/security.adoc diff --git a/documentation/IDTA-01002-3/modules/ROOT/nav.adoc b/documentation/IDTA-01002-3/modules/ROOT/nav.adoc index f87b3471..739b8479 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/nav.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/nav.adoc @@ -65,8 +65,6 @@ Shared .adoc file are used from https://github.com/admin-shell-io/aas-specs ** xref:http-rest-api/interactions.adoc[Interactions] -** xref:http-rest-api/security.adoc[Security] - ** xref:http-rest-api/api-code-generation.adoc[API Code Generation] * xref:summary-and-outlook.adoc[Summary and Outlook] diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc index 64b7350a..5bc7d841 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc @@ -38,12 +38,13 @@ Major Changes: Minor Changes: -* Clarification on how to handle duplicate query parameters -* Replace "servers" clause in OpenAPI files -* Add notes for base64url-encoded values and order of "assetIds" query parameters +* clarification on how to handle duplicate query parameters +* removal of Clause "Security" because Part 4 Security now covers security aspects +* replace "servers" clause in OpenAPI files +* add notes for base64url-encoded values and order of "assetIds" query parameters * update xref:bibliography.adoc[Bibliography] * add xref:annex/overview-constraints.adoc[overview of constraints] to Annex -* xref:http-rest-api/http-rest-api.adoc#modifier-constraints[HTTP Modifier Constraints]: Adding note for metadata and value-only representations of Asset Administration Shells (https://github.com/admin-shell-io/aas-specs-api/issues/268[#268]) +* xref:http-rest-api/http-rest-api.adoc#modifier-constraints[HTTP Modifier Constraints]: adding note for metadata and value-only representations of Asset Administration Shells (https://github.com/admin-shell-io/aas-specs-api/issues/268[#268]) === Interface Changes w.r.t. V3.0.3 to V3.1 diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/security.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/security.adoc deleted file mode 100644 index 0f21a2f3..00000000 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/security.adoc +++ /dev/null @@ -1,49 +0,0 @@ -//// -Copyright (c) 2023 Industrial Digital Twin Association - -This work is licensed under a [Creative Commons Attribution 4.0 International License]( -https://creativecommons.org/licenses/by/4.0/). - -SPDX-License-Identifier: CC-BY-4.0 - -//// - - -= Security - -In this clause security aspects relevant for the API are discussed. -See Part 4 for more information on Security. - -Authentication is mandatory. -Depending on the ecosystem the AAS uses, different authentication mechanisms might be in place. -This clause explains one exemplary authentication mechanisms, which has been developed by the security working group (AG3) of Plattform Industrie 4.0. -Other authentication services (e.g. Username/Password, DID=Decentralized Identifiers, Verifiable Credentials, EDC=Eclipse Data Space Connector, or IDS=International Data Spaces) may also be used to receive an access token for authorization. - -The following paragraphs describe the most important steps for token-based authentication of the HTTP/REST APIs. -For more details, see “Secure Downloadservice” (https://www.plattform-i40.de/PI40/Redaktion/EN/Downloads/Publikation/secure_downloadservice.html). <> gives an overview. - -.The private_key_certchain_jwt Method [...download service] -[[private_key_certchain_jwt-method]] -image::private_key_certchain_jwt-method.png[width=608,height=356] - -A client application uses a client certificate to create a certificate chain. -The certificate chain can be checked on the authentication server by the corresponding Root CA certificate, which is signed by a certification authority (CA). -The client application sends the certificate chain to the authentication server as token request by a JSON Web Token (JWT). -The JWT is signed by the client’s private key corresponding to the client certificate (JWT = Data + Signature). - -If the authentication is approved, the client application receives an access token from the authentication server (not shown in <>). - -Such an access token contains attributes from the client certificate (e.g. username, email address) which will be sent as HTTP header bearer token to the AAS server application. -The latter will check, whether the access token has been signed by a trusted authentication server and will make the authorization according to the AAS security metamodel. - -A running demo is explained in “Secure Downloadservice”. -A corresponding server can be seen on https://v3security.admin-shell-io.com/ with a related security AAS at the bottom. - -The AAS security metamodel does not deal with authentication; it assumes that the user is already authenticated. -The example security AAS is only created for demonstration purposes and is not standardized. -Since the version of the AASX Package Explorer used does not yet support the AAS security metamodel, the required information in subsequent steps like the access permission rules for AAS are modelled as a submodel. - -The different security and authentication steps are explained in the video https://admin-shell-io.com/screencasts/security/Industrie_40_Security_with_AASX_Server.mp4. - - - From cf2e0a8ab63f7b76ba892a091013bfb985844d21 Mon Sep 17 00:00:00 2001 From: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com> Date: Wed, 26 Mar 2025 18:28:13 +0100 Subject: [PATCH 22/22] close footnote --- documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc index 52abdfff..cdbe4545 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/annex/uml.adoc @@ -23,7 +23,7 @@ The formal specification can be found in xref:bibliography.adoc#bib10[[10\]]. <> shows a class with name "Class1" and an attribute with name "attr" of type _Class2_. Attributes are owned by the class. Some of these attributes may represent the end of binary associations, see also <>. -In this case, the instance of _Class2_ is navigable via the instance of the owning class _Class1_.footnote:[Navigability notation was often used in the past according to an informal convention, whereby non-navigable ends were assumed to be owned by the Association whereas navigable ends were assumed to be owned by the Classifier at the opposite end. +In this case, the instance of _Class2_ is navigable via the instance of the owning class _Class1_.footnote:[Navigability notation was often used in the past according to an informal convention, whereby non-navigable ends were assumed to be owned by the Association whereas navigable ends were assumed to be owned by the Classifier at the opposite end.] This convention is now deprecated. Aggregation type, navigability, and end ownership are separate concepts, each with their own explicit notation. Association ends owned by classes are always navigable, while those owned by associations may be navigable or not.