resolve conflicts from PR

#336

documentation/IDTA-01001/antora.yml

@@ -1,5 +1,5 @@
 name: IDTA-01001
-title: Specification Asset Administration Shell - Part 1 Metamodel
+title: DRAFT - Specification Asset Administration Shell - Part 1 Metamodel
 version: 'snapshot'
 start_page: ROOT:index.adoc
 nav:

documentation/IDTA-01001/modules/ROOT/nav.adoc

@@ -9,7 +9,7 @@ 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
 ////
-
+////
 :doctype: book
 :toc: left
 :toc-title: Specification of the Asset Administration Shell. Part 1: Metamodel
@@ -19,18 +19,15 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 :imagesdir: ./images/
 :nofooter:
 :xrefstyle: short
+////
 
-
-include::.pages/IDTA-01001_Constraints.adoc[]
+//= image:../../idta-logo.png[width=100%]
 
 
-= image:../../idta-logo.png[width=100%]
+// include::./includes/index.adoc[]
 
-////
-include::./index.adoc[]
-////
 
-include::../Shared/pages/IDTA-01xxx_TermsDefinitionsAbbreviations.adoc[]
+* xref:./shared/IDTA-01xxx_TermsDefinitionsAbbreviations.adoc[Terms and Definitions]
 
 include::./pages/IDTA-01001_Preamble.adoc[]
 

documentation/IDTA-01001/modules/ROOT/pages/Annex/IDTA-01xxx_BackusNaurForm.adoc

@@ -0,0 +1,68 @@
+////
+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
+
+Illustrations:
+Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH
+////
+
+
+[appendix]
+== Backus-Naur-Form
+
+The Backus-Naur form (BNF) – a meta-syntax notation for context-free grammars – is used to define grammars. For more information see [Wikipedia](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form).
+
+A BNF specification is a set of derivation rules, written as
+
+*<symbol> ::= __expression__*
+
+where:
+
+* <https://en.wikipedia.org/wiki/Symbol[symbol]> is a https://en.wikipedia.org/wiki/Nonterminal[nonterminal] (variable) and the https://en.wikipedia.org/wiki/Expression_(mathematics)[__expression__] consists of one or more sequences of either terminal or nonterminal symbols,
+* ::= means that the symbol on the left must be replaced with the expression on the right,
+* more sequences of symbols are separated by the https://en.wikipedia.org/wiki/Vertical_bar[vertical bar] "|", indicating a https://en.wikipedia.org/wiki/Alternation_(formal_language_theory)[choice], the whole being a possible substitution for the symbol on the left,
+* 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>],
+* 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 to 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.
+
+[.underline]#Example:#
+
+____
+*<contact-address> ::= <name> "e-mail addresses:" <e-mail-Addresses>*
+
+*<e-mail-Addresses> ::= \{<e-mail-Address>}**
+
+*<e-mail-Addresse> ::= <local-part> "@" <domain>*
+
+*<name> ::= characters*
+
+*<local-part> ::= characters conformant to local-part in RFC 5322*
+
+*<domain> ::= characters conformant to domain in RFC 5322*
+____
+
+Valid contact addresses:
+
+____
+*Hugo Me e-mail addresses: Hugo@example.com*
+
+*Hugo e-mail addresses: Hugo.Me@text.de*
+____
+
+Invalid contact addresses:
+____
+
+*Hugo*
+
+*Hugo Hugo@ example.com*
+
+*Hugo@example.com*
+____

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_DataSpecifications.adoc

@@ -10,11 +10,14 @@ Illustrations:
 Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH
 ////
 
-== Data Specification Templates (normative)
+:page-partial:
 
+[[data-specification-templates]]
+= Data Specification Templates (normative)
 
 
-=== Introduction
+
+== Introduction
 
 A data specification template specifies which additional attributes, which are not part of the metamodel, shall be added to an element instance. Typically, data specification templates have a specific scope. For example, templates for concept descriptions differ from templates for operations, etc. More than one data specification template can be defined and used for an element instance. _HasDataSpecification_ defines, which templates are used for an element instance.
 
@@ -25,7 +28,7 @@ image::image56.png[]
 
 The template introduced to describe the concept of a property, a value list, or a value is based on IEC 61360. Figure 55 also shows how concept descriptions and the predefined data specification templates are related to each other.
 
-==== Data Specification Template Attributes
+=== Data Specification Template Attributes
 
 .Data Specification Templates
 image::image57.png[]
@@ -51,11 +54,8 @@ h|ID: 3+| `\https://admin-shell.io/aas/3/1/DataSpecification`
 .2+h|Attribute 3+h| ID
 h|Explanation h|Type h|Card.
 
-.2+e|idShort 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/idShort`
-a| Name of the data specification |xref:page$IDTA-01001.adoc#NameType[NameType] |0..1
-
 .2+e|description 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/description`
-a|Description of how and in which context the data specification template is applicable; can be provided in several languages. |xref:page$IDTA-01001.adoc#MultiLanguageTextType[MultiLanguageTextType] |0..1
+a|Description of how and in which context the data specification template is applicable; can be provided in several languages. |xref:page$IDTA-01001_Metamodel.adoc#MultiLanguageTextType[MultiLanguageTextType] |0..1
 
 .2+e|administration 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/administration`
 a|
@@ -66,18 +66,18 @@ Administrative information of an identifiable element
 Note: some of the administrative information like the version number might need to be part of the identification.
 ====
 
-|xref:page$IDTA-01001.adoc#AdministrativeInformation[AdministrativeInformation] |0..1
+|xref:page$IDTA-01001_Metamodel.adoc#AdministrativeInformation[AdministrativeInformation] |0..1
 
 .2+e|id 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/id`
 a|
 The globally unique identification of the data specification
 
 
 ====
-Note: This identifier is used as value for xref:page$IDTA-01001.adoc#HasDataSpecification[HasDataSpecification/dataSpecification]
+Note: This identifier is used as value for xref:page$IDTA-01001_Metamodel.adoc#HasDataSpecification[HasDataSpecification/dataSpecification]
 ====
 
-|xref:page$IDTA-01001.adoc#Identifier[Identifier] |1
+|xref:page$IDTA-01001_Metamodel.adoc#Identifier[Identifier] |1
 
 .2+e|dataSpecificationContent 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/dataSpecificationContent`
 a|The content of the template without meta data

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_General.adoc

@@ -11,19 +11,22 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 ////
 
 
-
+////
 :toc: left
 :toclevels: 4
 :toc-title: Specification of the Asset Administration Shell. Part 1: Metamodel
 :sectlinks:
 :sectnums:
 :nofooter:
+////
 
+:page-partial:
 
 include::IDTA-01001_Constraints.adoc[]
 
 
-
+[[part1-general]]
+= General
 
 == Introduction
 

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_GrammarSemanticIdsMetamodel.adoc

@@ -1,5 +1,7 @@
+:page-partial:
 
-==  Semantic Identifiers for Metamodel and Data Specifications
+[[semantic-ids-for-metamodel]]
+=  Semantic Identifiers for Metamodel and Data Specifications
 
 
 
@@ -11,14 +13,12 @@ The following grammar is used to create valid identifiers:
 
 [listing]
 ....
-<Namespace> ::= <AAS Namespace> | <Data Specification Namespace>
+<Namespace> ::= <AAS Namespace> | <ID of Data Specification>
 
 <Namespace Qualifier> ::= <AAS Namespace Qualifier> | <Data Specification Qualifier>
 
 <AAS Namespace> ::= <Shell-Namespace> "/aas/" <Version>
 
-<Data Specification Namespace> ::= <Shell-Namespace> "/DataSpecificationTemplates/" <idShort of Data Specification> <Version>
-
 <Shell-Namespace> ::= "https://admin-shell.io/"
 
 <Version> ::= {<Digit>}+ "/" {<Digit>}+ [ "/" {<Character>}+ ]
@@ -32,11 +32,18 @@ For AAS a predefined namespace qualifier is defined. For data specifications thi
 
 [listing]
 ....
-<AAS Namespace Qualifier> ::= "AAS:"
+<ID of Data Specification> ::= defined per Data Specification
 
 <Data Specification Qualifier> ::= defined per Data Specification
+
+<AAS Namespace Qualifier> ::= "AAS:"
 ....
 
+====
+Note: The Data Specification ID should include versioning information. Data Specifications defined by the IDTA typically start with the <AAS namespace> as well. 
+Additionally, a sub-namespace is defined following the rules of the  https://github.com/admin-shell-io/id?tab=readme-ov-file#identifier-scheme-and-description[Identification Scheme of the Asset Administration Shell].
+====
+
 A concrete unique identifier is defined as follows:
 
 [listing]

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_Mappings.adoc

@@ -10,6 +10,10 @@ Illustrations:
 Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH
 ////
 
+:page-partial:
+
+[[part1-mappings]]
+= Mappings
 
 == Data Format for Sharing Data (normative)
 
@@ -66,17 +70,14 @@ Besides technical formats like JSON and XML also different content formats are a
 
 Blobs require the following encoding: base64 string.
 
-
-===  Serialization of Values of Type "Reference"
-
-include::IDTA-01001_GrammarSerializationReference.adoc[]
+include::./includes/IDTA-01001_GrammarSerializationReference.adoc[leveloffset=0]
 
 
-include::./IDTA-01001_MetaDataObjects.adoc[]
+include::./includes/IDTA-01001_MetaDataObjects.adoc[leveloffset=0]
 
-include::IDTA-01001_ValueOnly.adoc[]
+include::./includes/IDTA-01001_ValueOnly.adoc[leveloffset=0]
 
-include::IDTA-01001_idShortPath.adoc[]
+include::./includes/IDTA-01001_idShortPath.adoc[leveloffset=0]
 
 === Format "Reference"
 

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001.adoc → documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_Metamodel.adoc

@@ -11,24 +11,26 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 ////
 
 
-
+////
 :toc: left
 :toclevels: 4
 :toc-title: Specification of the Asset Administration Shell. Part 1: Metamodel
 :sectlinks:
 :sectnums:
 :nofooter:
+////
 
+:page-partial:
 
-include::IDTA-01001_Constraints.adoc[]
+include::./includes/IDTA-01001_Constraints.adoc[]
 
 
 
 
 
-== The Information Metamodel of the Asset Administration Shell (normative)
+= The Information Metamodel of the Asset Administration Shell (normative)
 
-=== Introduction
+== Introduction
 
 This clause specifies the information metamodel of the Asset Administration Shell.
 
@@ -42,7 +44,7 @@ Note: an xmi representation of the UML model can be found in the repository "aas
 ====
 
 
-=== Overview Metamodel of the Asset Administration Shell
+== Overview Metamodel of the Asset Administration Shell
 
 This clause gives an overview of the main classes of the Asset Administration Shell (AAS) metamodel.
 
@@ -103,9 +105,9 @@ image::image12.png[]
 .Metamodel Package Overview
 image::image13.png[]
 
-=== Metamodel Specification Details: Designators
+== Metamodel Specification Details: Designators
 
-==== General
+=== General
 
 This clause specifies the classes of the metamodel in detail. An overview is provided in Clause 5.2. Annex E explains UML modelling together with the specifics used in this specification. Annex D depicts the templates used to describe the classes and relationships. Annex G shows some of the diagrams together with all their inherited attributes to give a complete overview.
 
@@ -115,9 +117,9 @@ The concept of referencing and how a reference is represented in the UML diagram
 
 Constraints that are no invariants of classes are specified in Clause 5.3.11.3.
 
-==== Common Attributes
+=== Common Attributes
 
-===== General
+==== General
 
 This clause specifies the abstract classes that represent commonly used attributes and terminology, together with the classes and data types exclusively used in these classes. They are represented in alphabetical order.
 
@@ -520,7 +522,7 @@ h|ID: 3+| `\https://admin-shell.io/aas/3/1/Qualifier`
 .2+h|Attribute 3+h| ID
 h|Explanation h|Type h|Card.
 
-.2+e|kind \<<Experimental>> 
+.2+e|kind \<<Experimental>> 3+| `\https://admin-shell.io/aas/3/1/Qualifier/kind` 
 a|
 The qualifier kind describes the kind of qualifier that is applied to the element.
 

documentation/IDTA-01001/modules/ROOT/pages/IDTA-01001_Preamble.adoc

@@ -10,10 +10,10 @@ Illustrations:
 Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH
 ////
 
+[[part-preamble]]
+= Preamble
 
-== Preamble
-
-=== Editorial Notes
+== Editorial Notes
 
 This document (version 3.1) was produced by the Work Stream "Specification of the Asset Administration Shell" of the Working Group "Open Technology" of the https://industrialdigitaltwin.org/[Industrial Digital Twin Association (IDTA)]. It is the first version published as html document and maintained completely open source.
 
@@ -33,12 +33,12 @@ The first version of this document was produced September 2017 to July 2018 by a
 
 For better readability the abbreviation "I4.0" is consistently used for "Industrie 4.0" in compound terms. The term "Industrie 4.0" continues to be used when standing on its own.
 
-include::../../Shared/pages/IDTA-01xxx_Versioning.adoc[]
+include::./shared/IDTA-01xxx_Versioning.adoc[]
 
-include::../../Shared/pages/IDTA-01xxx_Conformance.adoc[]
+include::./shared/IDTA-01xxx_Conformance.adoc[]
 
 
-===  Scope of this Document
+==  Scope of this Document
 
 The aim of this document is to define the structure of the Administration Shell to enable the meaningful exchange of information about assets and I4.0 components between partners in a value creation network.
 
@@ -51,7 +51,7 @@ This document focuses on:
 
 This document presumes some familiarity with the concept of the Asset Administration Shell. Some of the concepts are described in Annex A for convenience sake. The concepts are being standardized as IEC standard IEC 63278 series link:#bib44[[44\]]. The main stakeholders addressed in this document are architects and software developers aiming to implement a digital twin using the Asset Administration Shell in an interoperable way. Additionally, the content can also be used as input for discussions with international standardization organizations and further initiatives. Please consult the continuously updated reading guide link:#bib38[[38\]] for an overview of documents on the Asset Administration Shell. The reading guide gives advice on which documents should be read depending on the role of the reader.
 
-===  Structure of the Document
+==  Structure of the Document
 
 All clauses that are normative have "(normative)" as a suffix in the heading of the clause.
 
@@ -77,7 +77,7 @@ Annex H describes metamodel changes compared to previous versions. Annex F provi
 
 The bibliography can be found in Annex I.
 
-===  Working Principles
+== Working Principles
 
 The work is based on the following principle: keep it simple but do not simplify if it affects interoperability.