From 98a9aea6fb3adbd0f94cd202e215d9474b8ed3c6 Mon Sep 17 00:00:00 2001 From: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> Date: Thu, 2 Jan 2025 15:13:27 +0100 Subject: [PATCH] editorial changes (#361) * added xref correct GetDescription to GetSelfDescription renamed id to ID Clause 4.5 substitutet with ref. to AASd-116 * add more xref: * remove deprecated reference to Plattform I4.0 corrected some links do not reference Glossary Plattform I4.0 directly only via Terms and Definitions * added puml to partials, directly link puml, not .png --- .../modules/ROOT/pages/general.adoc | 19 +- .../ROOT/pages/specification/interfaces.adoc | 233 +++++++++--------- .../diagrams/query-language-overview.puml | 124 ++++++++++ 3 files changed, 254 insertions(+), 122 deletions(-) create mode 100644 documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/query-language-overview.puml diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc index f92b8f49..0c6b28ef 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/general.adoc @@ -27,7 +27,7 @@ However, to avoid terminological and conceptual misunderstandings, the whole Ind The technology-neutral level comprises the following concepts: -* *Service*: a service describes a demarcated scope of functionality (including its informational and non-functional aspects), which is offered by an entity or organization via https://www.plattform-i40.de/PI40/Redaktion/EN/Glossary/I/interface_glossary.html[interfaces]. +* *Service*: a service describes a demarcated scope of functionality (including its informational and non-functional aspects), which is offered by an entity or organization via interfaces. * *Interface*: this is the most important concept as it is understood to be the unit of reusability across services and the unit of standardization when mapped to application programming interfaces (API) in the technology-specific level. One interface may be mapped to several APIs depending on the technology and architectural style used, e.g. HTTP/REST or OPC UA, whereby these API mappings also need to be standardized for the sake of interoperability. * *Interface-Operation*: interface operations define interaction patterns via the specified interface. @@ -155,8 +155,8 @@ The identifiers defined in this document are reused in related resources, for in 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. 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 Plattform Industrie 4.0. -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 [https://github.com/admin-shell-io/id]. +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]. The catalogue itself is structured in several sub-namespaces specified by the first path parameter. All URIs of this document reflect entities of the core metamodel, which are contained in the sub-namespace identified with the ‘/aas/API’ path. @@ -279,7 +279,8 @@ The separate interfaces of the HTTP/REST API allow many ways to support differen For an AAS repository, the combination [.gray]#“Asset Administration Shell Repository Interface”#, [.red]#“Asset Administration Shell Interface”#, [.blue]#“Submodel Interface”#, “Serialization Interface”, and “Self-Description Interface” is proposed. -This will result in the following HTTP/REST paths as described in a combined OpenAPI file (https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1_SSP-001)[For easier reading only the standard paths are shown in the following: $metadata, $value, $reference and $path parameter paths are additionally contained in the OpenAPI file.]: +This will result in the following HTTP/REST paths as described in a combined OpenAPI file link:https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1_SSP-001[AssetAdministrationShellRepositoryServiceSpecification/V3.1_SSP-001].footnote[ +For easier reading only the standard paths are shown in the following: $metadata, $value, $reference and $path parameter paths are additionally contained in the OpenAPI file.]: [.gray]#/shells# + [.gray]#/shells/\{aas-identifier}# + @@ -300,7 +301,8 @@ This will result in the following HTTP/REST paths as described in a combined Ope If the repository also supports AASX Packages, it shall be extended by additionally supporting a “AASX File Server” Profile [Related OpenAPI file: https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.1_SSP-001]. -The example of a device or container containing one AAS with its related submodels will result in the following HTTP/REST paths as described in the related OpenAPI file (https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1_SSP-001)^2^: +The example of a device or container containing one AAS with its related submodels will result in the following HTTP/REST paths as described in the related OpenAPI file (https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1_SSP-001)footnote[Related OpenAPI file: link:https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.0_SSP-001[AasxFileServerServiceSpecification/V3.0_SSP-001] +]: [.red]#/aas# + [.red]#/aas/asset-information# + @@ -342,10 +344,11 @@ TechnicalData has its major variable part on the bottom and a small fixed struct HandoverDocumentation consists basically of a list of document information according VDI 2770 (DocumentedEntity{00}). It is expected, that this will be changed to SubmodelElementList like other V3 Submodels. An example is to search for Documents of a certain ClassId (semanticId = 0173-1#02-ABH996#001, ClassId = "03-01", i.e. Commissioning) in a certain language (semanticId = 0173-1#02-AAN468#006, e.g. Value = "nl"). - .Main elements of the AAS Query Language -image::../images/plantuml/query-language-overview.png[] - +[plantuml, 29-relationship-element, svg] +.... +include::partial$diagrams/query-language-overview.puml[] +.... === Limitations diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc index 23e0747e..989e60c8 100644 --- a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc +++ b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc @@ -16,7 +16,7 @@ include::../includes/special-parameters.adoc[] === General -These interfaces make it possible to access the elements of Asset Administration Shells or Submodels. +The Asset Administration Shell and Submodel interface make it possible to access the elements of Asset Administration Shells or Submodels. The AASX File Server Interface enables management of AASX packages on a server. A list of available packages can be retrieved. @@ -30,20 +30,21 @@ The server documentation shall contain a description of when and how AASX packag ==== Asset Administration Shell Interface +The Asset Administration Shell interface enables the access of the elements of a single Asset Administration Shell. [%autowidth,width="100%",options=header] |=== -2+h|Interface: _Asset Administration Shell_ +2+h|Interface: [[interface-AssetAdministrationShell]]_Asset Administration Shell_ h|Operation Name h|Description -e|GetAssetAdministrationShell a|Returns the Asset Administration Shell -e|PutAssetAdministrationShell a|Replaces the current Asset Administration Shell -e|GetAllSubmodelReferences a|Returns all Submodel References -e|PostSubmodelReference a|Creates a Submodel Reference at the Asset Administration Shell -e|DeleteSubmodelReference a|Deletes a specific Submodel Reference from the Asset Administration Shell -e|GetAssetInformation a|Returns the Asset Information -e|PutAssetInformation a|Replaces the Asset Information -e|GetThumbnail a|Returns the thumbnail file -e|PutThumbnail a|Replaces the thumbnail file -e|DeleteThumbnail a|Deletes the thumbnail +e|xref:GetAssetAdministrationShell[GetAssetAdministrationShell] a|Returns the Asset Administration Shell +e|xref:PutAssetAdministrationShell[PutAssetAdministrationShell] a|Replaces the current Asset Administration Shell +e|xref:GetAllSubmodelReferences[GetAllSubmodelReferences] a|Returns all Submodel References +e|xref:PostSubmodelReference[PostSubmodelReference] a|Creates a Submodel Reference at the Asset Administration Shell +e|xref:DeleteSubmodelReference[DeleteSubmodelReference] a|Deletes a specific Submodel Reference from the Asset Administration Shell +e|xref:GetAssetInformation[GetAssetInformation] a|Returns the Asset Information +e|xref:PutAssetInformation[PutAssetInformation] a|Replaces the Asset Information +e|xref:GetThumbnail[GetThumbnail] a|Returns the thumbnail file +e|xref:PutThumbnail[PutThumbnail] a|Replaces the thumbnail file +e|xref:DeleteThumbnail[DeleteThumbnail] a|Deletes the thumbnail |=== ==== Operation GetAssetAdministrationShell @@ -129,7 +130,7 @@ h|semanticId 4+|`\https://admin-shell.io/aas/API/DeleteSubmodelReference/3/0` h|Name h| Description h|Mand. h|Type h|Card. 5+h|Input Parameter -e|submodelId | The unique id of the Submodel for the reference to be deleted |yes |link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/spec-metamodel/datatypes.html#Identifier[Identifier] |1 +e|submodelId | The unique ID of the Submodel for the reference to be deleted |yes |link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/spec-metamodel/datatypes.html#Identifier[Identifier] |1 5+h|Output Parameter e|statusCode | Status code |yes |xref:specification/interfaces-payload.adoc#StatusCode[StatusCode] |1 |=== @@ -223,7 +224,7 @@ e|statusCode a|Status code |yes |xref:specification/interfaces-payload.adoc#Stat [%autowidth,width="100%",cols="42%,58%",options="header",] |=== -2+|Interface: [[Submodel]]Submodel +2+h|Interface: [[interface-Submodel]]_Submodel_ h|Operation Name h|Description e|GetSubmodel a|Returns the Submodel @@ -802,11 +803,12 @@ h|Name h|Description h|Mand. h|Type h|Card. === General -These interfaces allow to register and unregister descriptors of administration shells or submodels. -The descriptors contain the information needed to access the interfaces (as described in <>) of the corresponding element. +Registration interfaces allow to register and unregister descriptors of administration shells or submodels. +The descriptors contain the information needed to access the interfaces (as described in <>) of the corresponding element. This required information includes the endpoint in the dedicated environment. -Lookup interfaces provide access to the registered descriptors by identifiers (Asset Administration Shell and Submodel ID). +Lookup interfaces provide access to the registered descriptors by identifiers (Asset Administration Shell and Submodel ID). + These identifiers may be discovered through the interfaces described in <>. === Asset Administration Shell Registry Interface and Operations @@ -815,17 +817,18 @@ These identifiers may be discovered through the interfaces described in < SelectField +Query --> Condition + +' to better arrange the SelectField +SelectField -r[hidden]- Placeholder1 +Placeholder1 -r[hidden]- Condition +hide Placeholder1 + +' to better arrange the elements +Placeholder2 -l[hidden]- Condition +hide Placeholder2 + +enum SelectField { + id +} + + + abstract class Condition <>{ + } + + enum LogicalOperation { + $and + $or + $not + ' nested + } + + class LogicalExpression { + +operation: LogicalOperation[1] + +operands: Condition[1..*] + } + + class MatchExpression { + +$match: Condition[1..*] + } + + abstract class Operation <> { + + } + + enum ComparisonOperation { + $eq + $ne + $gt + $ge + $lt + $le + } + Operation <|-- ComparisonOperation + + enum StringOperation { + $contains + $starts-with + $ends-with + $regex + } + Operation <|-- StringOperation + + class Comparison { + +operation: Operation[1] + +operands: Operand[2] + } + + enum CastingOperation { + $strCast + $numCast + $hexCast + $boolCast + $dateTimeCast + $timeCast + } + + abstract class Operand <> { + + } + + enum FieldIdentifier { + $strModel + } + + enum Value { + $strVal + $numVal + $hexVal + $dateTimeVal + $timeVal + $dayOfWeek + $dayOfMonth + $month + $year + } + + LogicalExpression -u-|> Condition + LogicalExpression --> Condition + LogicalExpression --> LogicalOperation + Comparison -u-|> Condition + Condition <|-- MatchExpression + Condition <-- MatchExpression + Comparison --> Operation + Comparison --> Operand + Operand <|-- CastingOperation + Operand <|--Value + Operand <|-- FieldIdentifier + +'for better arrangements of the classes below Condition +LogicalExpression .r[hidden]. Comparison +'Comparison .r[hidden]. MatchExpression + +'Operation .r[hidden]. Operand + + + +@enduml \ No newline at end of file