admin-shell-io · juileetikekar · May 27, 2025 · Nov 16, 2023 · Nov 16, 2023 · Feb 1, 2024
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Create a bug report to help us improve.
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Where**
+Indicate the location of the bug (e.g., in which document, section and paragraph you found the bug).
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/workflows/check-changed-files.yml b/.github/workflows/check-changed-files.yml
@@ -0,0 +1,36 @@
+name: Check-changed-files
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  actions: read
+
+jobs:
+  qodana:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch Sources
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: ${{ github.event.pull_request.commits }}
+
+      - name: Get two more commits so Qodana we can identify the changes
+        if: github.event_name == 'pull_request'
+        run: git fetch --deepen=2
+
+      - name: Run Qodana inspection
+        uses: JetBrains/qodana-action@v2024.3.4
+        with:
+          upload-result: true
+          args: >
+            --baseline,doc/qodana-baseline.sarif.json,
+            --config,.qodana/qodana.yaml
+
+      # This step uploads the SARIF file to GitHub so that the code scanning feature can use it.
+      # https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github#example-workflow-that-runs-the-eslint-analysis-tool
+      - name: Upload SARIF report to GitHub
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ${{ runner.temp }}/qodana/results/qodana.sarif.json
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,5 @@
+################################################################################
+# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
+################################################################################
+
+/.vs
diff --git a/.qodana/asciidoc-inspection.xml b/.qodana/asciidoc-inspection.xml
@@ -0,0 +1,29 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0" is_locked="true">
+    <!-- GrazieInspection normally has a TYPO preference -->
+    <inspection_tool class="GrazieInspection" enabled="true" level="WARNING" enabled_by_default="true"/>
+    <inspection_tool class="AsciiDocAnchorWithoutId" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocAttributeContinuation" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocBlockMacroShouldBeInlineMacro" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocDescriptionExists" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocDescriptionLength" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocHeadingStyle" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocHorizontalRule" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocInlineMacroShouldBeBlockOrPreprocessorMacro" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocLinkResolve" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocListingStyle" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocPageBreak" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocReferencePattern" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocXrefWithFileExtension" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocXrefWithNaturalCrossReference" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocAttributeShouldBeDefined" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocObsoletePassthrough" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="AsciiDocUnresolvedAntoraModule" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="SpellCheckingInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="processCode" value="true" />
+      <option name="processLiterals" value="true" />
+      <option name="processComments" value="true" />
+    </inspection_tool>
+    <inspection_tool class="Style" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>
diff --git a/.qodana/qodana.yaml b/.qodana/qodana.yaml
@@ -0,0 +1,19 @@
+version: 1.0
+profile:
+  path: .qodana/asciidoc-inspection.xml
+linter: jetbrains/qodana-jvm-community:2024.3
+plugins:
+  - id: org.asciidoctor.intellij.asciidoc
+
+include:
+  - name: HttpUrlsUsage
+  - name: GrazieInspection
+
+exclude:
+  - name: All
+    paths:
+      - .github
+      - .qodana
+      - CONTRIBUTING.md
+      - LICENSE.txt
+      - README.md
diff --git a/README.md b/README.md
@@ -8,14 +8,32 @@ Governance of the specification is done in the working group Open Technology of
 
 The specification number is: **IDTA-01003-a**
 
+## Releases
+
+The following versioning scheme is applied: 'V\<major>.\<minor>.\<patch>'. 
+Major versions indicate breaking changes while minor updates are 
+backward compatible.
+The patch position is increased whenever bugfixes need to be applied. 
+The following release contains the latest version of the AAS schemas
+ (see also the [releases](https://github.com/admin-shell-io/aas-specs-iec61360/releases) 
+section of this repository):
+
+* [3.1.0](https://github.com/admin-shell-io/aas-specs-iec61360/releases/tag/v3.1.0)
+is the latest release for the `V3.1.0` version of the AAS Specification IDTA-01003-a Data Specification IEC61360, 
+containing the normative schemas for the published document
+ "Specification of the Asset Administration Shell: Part 3a - **Version 3.1.0**". 
+*Use this release if you want to work with the latest specified AAS version.*
+
+Note: The schema for this data specification is included as embedded data specification in the release of [IDTA-01001-3-1](https://github.com/admin-shell-io/aas-specs-metamodel) or its bugfix releases
+
 ## Contributing
 
 Feature requests, reports about inconsistencies, mistakes *etc.* are highly
 welcome! Please [submit a new issue](
-https://github.com/admin-shell-io/aas-specs/issues/new
+https://github.com/admin-shell-io/aas-specs-iec61360/issues/new
 ).
 
-If you want to contribute, see [CONTRIBUTING.md](https://github.com/admin-shell-io/aas-specs/blob/master/CONTRIBUTING.md). The same contribution rules apply as for [aas-specs](https://github.com/admin-shell-io/aas-specs)
+If you want to contribute, see [CONTRIBUTING.md](https://github.com/admin-shell-io/aas-specs-metamodel/blob/master/CONTRIBUTING.md). The same contribution rules apply as for [aas-specs-metamodel](https://github.com/admin-shell-io/aas-specs-metamodel)
 
 ## License
 

diff --git a/documentation/IDTA-01003-a/antora.yml b/documentation/IDTA-01003-a/antora.yml
@@ -0,0 +1,8 @@
+name: IDTA-01003-a
+title: 'Part 3a: Data Specification - IEC61360'
+version: 'v3.1'
+display_version: 'in progress'
+prerelease: true
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image1.png b/documentation/IDTA-01003-a/modules/ROOT/images/image1.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image16.png b/documentation/IDTA-01003-a/modules/ROOT/images/image16.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image17.png b/documentation/IDTA-01003-a/modules/ROOT/images/image17.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image18.png b/documentation/IDTA-01003-a/modules/ROOT/images/image18.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image2.jpg b/documentation/IDTA-01003-a/modules/ROOT/images/image2.jpg
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image3.png b/documentation/IDTA-01003-a/modules/ROOT/images/image3.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image4.png b/documentation/IDTA-01003-a/modules/ROOT/images/image4.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image5.png b/documentation/IDTA-01003-a/modules/ROOT/images/image5.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image6.png b/documentation/IDTA-01003-a/modules/ROOT/images/image6.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/images/image7.png b/documentation/IDTA-01003-a/modules/ROOT/images/image7.png
diff --git a/documentation/IDTA-01003-a/modules/ROOT/nav.adoc b/documentation/IDTA-01003-a/modules/ROOT/nav.adoc
@@ -0,0 +1,31 @@
+////
+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
+////
+
+* xref:terms-definitions-and-abbreviations.adoc[Terms and Definitions]
+* xref:preamble.adoc[Preamble]
+* xref:introduction.adoc[Introduction]
+
+* xref:specification.adoc[Specification]
+
+* xref:summary-and-outlook.adoc[Summary and Outlook]
+
+
+* xref:./annex/nav-annex.adoc[Annex]
+** xref:./annex/background.adoc[Background]
+** xref:annex/backus-naur-form.adoc[Backus Naur Form]
+** xref:annex/uml.adoc[UML]
+** xref:annex/uml-templates.adoc[UML Table Templates]
+** xref:./annex/handling-constraints.adoc[Handling Constraints]
+
+* xref:changelog.adoc[Change Log]
+* xref:bibliography.adoc[Bibliography]
+
diff --git a/documentation/IDTA-01003-a/modules/ROOT/pages/annex/background.adoc b/documentation/IDTA-01003-a/modules/ROOT/pages/annex/background.adoc
@@ -0,0 +1,78 @@
+= Background Information
+
+== General
+
+This clause provides general information about sources of information and relevant concepts for the data specification under consideration, as well as its usage in the context of the Asset Administration Shell.
+It is not normative.
+
+=== Data Elements (Part 1)
+
+.Metamodel of Data Elements (Part 1)
+[[image-data-elements]]
+[plantuml, svg]
+....
+include::partial$diagrams/data-element.puml[]
+....
+
+The data specification template IEC61360 is relevant for the definition of concept descriptions for data elements (<<image-data-elements>>).
+Submodel Elements inherit from _hasSemantics_, i.e. they have a semanticId and optionally some additional supplementary semantic IDs (<<image-has-semantics>>).
+
+xref:introduction.adoc#image-rel-metamodel-iec61360[Figure Overview Relationship Metamodel Part 1 a & Data Specifications IEC 61360] gives an overview of the relationship of concept descriptions (_ConceptDescription_) and data specifications (DataSpecification, _DataSpecificationContent_ and _HasDataSpecification_) from Part 1 for this concrete data specification template.
+
+.Metamodel of HasSemantics (Part 1)
+[[image-has-semantics]]
+[plantuml, svg]
+....
+include::partial$diagrams/has-semantics.puml[]
+....
+
+Clause xref:specification.adoc#category-of-concept-descriptions[Category of Concept Descriptions] describes how to use the data specification template to describe further of the metamodel as specified in Part 1 that may also have semantics assigned to them (by inheriting from HasSemantics): Submodel, all other SubmodelElements, SpecificAssetId, Qualifier, and Extension.
+In these cases, the preferred name and the definition are mainly used to provide a minimum of information on what the corresponding value is about.
+
+== Examples
+
+<<image-property-max-rotation-speed>> shows an example of a property with idShort "MaxRotationSpeed" with a semantic ID referring to a concept description "MaxRotationSpeed".
+The concept description shows that MaxRotationSpeed is a quantitative property because the data type is one of *_MEASURE, namely INTEGER_MEASURE.
+In this case, the definition of a physical unit is mandatory.
+It is "1/min" for MaxRotationSpeed.
+A unique ID is also provided for this physical unit.
+Concept descriptions for physical units are described e.g. in Part 4b of this document series on the Details of the Asset Administration Shell.
+
+The type INTEGER_MEASURE of the concept description is mapped to xs:integer of the property.
+
+.Example Quantitative Property MaxRotationSpeed in AASX Package Explorer
+[[image-property-max-rotation-speed]]
+image::image16.png[align=center]
+
+<<image-property-with-enum>> shows a property "CoolingType".
+Its semanticId references a concept description that defines a value list (_DataSpecificationIec612360/valueList_) with two values BAB657 and BAB611.
+
+[#_Toc129706741]
+.Example Property with Enumeration in AASX Package Explorer
+[[image-property-with-enum]]
+image::image17.png[align=center]
+
+<<image-example-cd>> shows the concept description for the value BAB657 that was used in the enumeration in <<image-property-with-enum>>.
+Most attributes are not relevant (see Clause xref:specification.adoc#category-of-concept-descriptions[Category of Concept Descriptions]).
+However, it is mandatory to set the attribute _DataSpecificationIec61360/value_, the _preferredName_ (open circuit, external cooling), and the data type (for enumeration, the data type is typically just STRING).
+
+.Example Value Concept Description in AASX Package Explorer
+[[image-example-cd]]
+image::image18.png[align=center]
+
+=== Referencing (Part 1)
+
+Besides the abstract class _HasSemantics,_ the referencing concept explained in Part 1 is also relevant (<<image-reference>>).
+In the case of the data specification template IEC61360, the only relevant key types are "GlobalReference" and "ConceptDescription".
+In case the concept description is a shadow copy of an existing data dictionary and uses the same ID, it is recommended to use the Global Reference for the _DataSpecificationIec61360/unitId_ or _ValueReferencePair/valueId_.
+Otherwise, a model reference with _Key/type_ equal to _ConceptDescription_ is used.
+
+The same applies to _HasSemantics/semanticId_ and semantic IDs in _HasSemantics/supplementalSemanticIds._
+
+.Metamodel of Reference (Part 1)
+[[image-reference]]
+[plantuml, svg]
+....
+include::partial$diagrams/reference-metamodel.puml[]
+....
+
diff --git a/documentation/IDTA-01003-a/modules/ROOT/pages/annex/backus-naur-form.adoc b/documentation/IDTA-01003-a/modules/ROOT/pages/annex/backus-naur-form.adoc
@@ -0,0 +1,74 @@
+////
+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]
+= 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 https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form[Wikipedia].
+
+A BNF specification is a set of derivation rules, written as
+
+[listing]
+....
+<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:#
+
+[example]
+....
+
+<contact-address> ::= <name> "e-mail addresses:" <e-mail-Addresses>
+
+<e-mail-Addresses> ::= {<e-mail-Address>}*
+
+<e-mail-Address> ::= <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:
+
+[example]
+....
+Hugo Me e-mail addresses: Hugo@example.com
+
+Hugo e-mail addresses: Hugo.Me@text.de
+....
+
+Invalid contact addresses:
+
+[example]
+....
+Hugo
+
+Hugo Hugo@ example.com
+
+Hugo@example.com
+....
diff --git a/documentation/IDTA-01003-a/modules/ROOT/pages/annex/handling-constraints.adoc b/documentation/IDTA-01003-a/modules/ROOT/pages/annex/handling-constraints.adoc
@@ -0,0 +1,26 @@
+////
+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
+////
+
+:page-partial:
+
+= Handling of Constraints
+
+Constraints are prefixed with *AASc-3a-* followed by a three-digit number.
+The "c" in "AASc-" was motivated by "Concept Description".
+The numbering of constraints is unique within namespace AASc-3a; a number of a constraint that was removed will not be used again.
+
+If a constraint is mentioning the ID of the Template, then the same constraints shall also be valid for deprecated data specification template IDs.
+
+====
+Note: in the Annex listing the metamodel changes, constraints with prefix AASd-, AASs- or AASc- are also listed.
+These are metamodel, security or data specification constraints, and are now part of the split document parts.
+====