Skip to content

removal of chapter Security + editorial changes #428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
Mar 26, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions documentation/IDTA-01002-3/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -83,6 +81,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]
Expand Down
Original file line number Diff line number Diff line change
@@ -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

Check warning on line 7 in documentation/IDTA-01002-3/modules/ROOT/pages/annex/api-tables-templates.adoc

View workflow job for this annotation

GitHub Actions / qodana

Typo

Typo: In word 'SPDX'

////

[appendix]
== Templates for Specification of APIs and API Operations

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
////


Expand All @@ -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: [<item-x>], or suffixed with an additional (questionmark) symbol, ?, such as <optional-symbol>?,
* items existing 0 or more times are enclosed in curly brackets are suffixed with an asterisk (\*) such as <word> ::= <letter> {<letter>}*,
* items existing 1 or more times are suffixed with an addition (plus) symbol, \+, such as <word> ::= {<letter>}+,
* items existing 0 or more times are enclosed in curly brackets are suffixed with an asterisk (\*) such as <word>::= <letter> {<letter>}*,
* items existing 1 or more times are suffixed with an addition (plus) symbol, \+, such as <word>::= {<letter>}+,
* round brackets are used to explicitly define the order of expansion to indicate precedence, example: ( <symbol1> | <symbol2> ) <symbol3>,
* text without quotation marks is an informal explanation of what is expected; this text is cursive if grammar is non-recursive and vice versa.

Expand Down
Original file line number Diff line number Diff line change
@@ -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

Check warning on line 7 in documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc

View workflow job for this annotation

GitHub Actions / qodana

Typo

Typo: In word 'SPDX'

////


[appendix]
= Overview Constraints (non-normative)

Check warning on line 13 in documentation/IDTA-01002-3/modules/ROOT/pages/annex/overview-constraints.adoc

View workflow job for this annotation

GitHub Actions / qodana

Description exists inspection for Antora page

Description attribute is missing
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}
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,7 @@ The formal specification can be found in xref:bibliography.adoc#bib10[[10\]].
<<image-64-class>> 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 <<image-70-navigable-attribute-notation-for-associations>>.
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.
Expand Down Expand Up @@ -221,6 +220,7 @@ It contains two literal values, "a" and "b".
It is a class with stereotype \<<enumeration>>.
The literals owned by the enumeration are ordered.

.Enumeration
[[image-76-enumeration]]
[plantuml, 76-enumeration, svg]
....
Expand Down Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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".
Expand Down
11 changes: 7 additions & 4 deletions documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +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
* 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])
* 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])

=== Interface Changes w.r.t. V3.0.3 to V3.1

Expand Down
6 changes: 3 additions & 3 deletions documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

== Services, Interfaces and Interface Operations

This document uses the Industrie 4.0 Service Model illustrated in <<i40-service-model>> for a uniform understanding and naming.

Check failure on line 17 in documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc

View workflow job for this annotation

GitHub Actions / qodana

Link Resolve inspection

Anchor doesn't resolve
It basically distinguishes between associated concepts on several levels (from left to right):

* technology-neutral level: concepts that are independent of selected technologies;
Expand Down Expand Up @@ -66,7 +66,7 @@
* *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[]
Expand Down Expand Up @@ -123,7 +123,7 @@
* SEARCHALL: returns a list fo resources based on asset links.

====
Note 2: these methods are intended for the naming of interfaces as described in <<i40-service-model>>.
Note 2: these methods are intended for the naming of interfaces as described in <<image-i40-service-model>>.
They shall not be interpreted as new protocol methods, e.g. on HTTP level.
====

Expand Down Expand Up @@ -157,7 +157,7 @@
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].
Expand Down
Loading