editorial changes, missing files, update UML (#505)

* Fix xrefs and tags

* Fix `aasd127` variable

* add container-element.puml file

* figure for overview subtypes ContainerElement

* inherit from ContainerElement, not from SubmodelElement

* add removal of AASd-120 to table with changed constraints

* remove AASd-120 #432

* Fix unresolved xrefs

* fix Typo

* .puml for logical enumerations for KeyTypes etc.

* add captions for every logical enum

* fix link

* no subtopic of recommendation of external references:
move

* correct changelog w.r.t. OPC UA and AML

* add { for JSON example

---------

Co-authored-by: zrgt <garmaev@gmx.de>

documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc

@@ -18,7 +18,7 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 
 == Composite I4.0 Components
 
-As described in Clause xref:general.adoc#life_cycle_with_type_assets_and_instance_assets[], there is a class of relationships between assets of different hierarchy levels.
+As described in Clause xref:general.adoc#life-cycle-with-type-assets-and-instance-assets[], there is a class of relationships between assets of different hierarchy levels.
 In this class of relationships, automation equipment is explained as a complex, interrelated graph of automation devices and products, performing intelligent production and self-learning/optimization tasks.
 
 Details and examples for composite I4.0 Components can be found in xref:bibliography.adoc#bib13[[13\]].

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

@@ -40,7 +40,7 @@ Note: before V3.0, the security metamodel and the predefined data specifications
 Major Changes:
 
 * New value "Role" to enumeration AssetKind (https://github.com/admin-shell-io/aas-specs/issues/294[#294])
-* New abstract class "ContainerElement" as subtype of "SubmodelElement", subtypes: AnnotatedRelationshipElement, Entity, SubmodelElementCollection, SubmodelElementLis. Includes introducing new enumeration for container elements and extending existing enumerations for submodel elements "AasSubmodelElement" etc. (https://github.com/admin-shell-io/aas-specs/issues/333[#333])
+* New abstract class "ContainerElement" as subtype of "SubmodelElement", subtypes: AnnotatedRelationshipElement, Entity, SubmodelElementCollection, SubmodelElementList. Includes introducing new enumeration for container elements and extending existing enumerations for submodel elements "AasSubmodelElement" etc. (https://github.com/admin-shell-io/aas-specs/issues/333[#333])
 * Data type Identifier: change length from 2000 to 2048 characters (https://github.com/admin-shell-io/aas-specs/issues/306[#306])
 * Referable/idShort and Constraint AASd-002: now also allows hyphens to be included in name (https://github.com/admin-shell-io/aas-specs/issues/295[#295])
 * Entity/entityType and Constraint AASd-014: entityType now optional (https://github.com/admin-shell-io/aas-specs/issues/287[#287])
@@ -73,8 +73,10 @@ also abbreviations partly adopted; changes:
 ** add table similar to metadata table: which attributes are displayed in Value-Only serialization
 ** update examples to provide Value-Only serialization for every submodel element (not in the context of a Submodel as before)
 ** add clause for Submodel Example (with properties from SMT Technical Data, not Families any longer)
+* update Schema for JSON-Value Serialization (https://github.com/admin-shell-io/aas-specs/issues/366[#366])
+
 * remove recommendation to use external references for semanticId (https://github.com/admin-shell-io/aas-specs/issues/376[#376]) and related attributes like valueId and isCaseOf (https://github.com/admin-shell-io/aas-specs/issues/396[#396])
-** update Schema for JSON-Value Serialization (https://github.com/admin-shell-io/aas-specs/issues/366[#366])
+
 * remove clauses on OPC UA and AutomationML mappings (https://github.com/admin-shell-io/aas-specs/issues/373[#373], https://github.com/admin-shell-io/aas-specs/issues/397[#397])
 * update explanatory text and notes in the context of AdministrativeInformation (https://github.com/admin-shell-io/aas-specs/issues/331[#331])
 * Transfer from .docx to asciidoc (.adoc) and maintenance in GitHub
@@ -83,9 +85,8 @@ also abbreviations partly adopted; changes:
 Minor Changes:
 
 * explanation of ValueOnly-Normal round-trip issues (https://github.com/admin-shell-io/aas-specs/issues/364[#364])
-* remove recommendation to use external reference for semanticId (https://github.com/admin-shell-io/aas-specs/issues/376[#376]) and related attributes like valueId and isCaseOf (https://github.com/admin-shell-io/aas-specs/issues/396[#396])
-* update information on OPC UA mapping (https://github.com/admin-shell-io/aas-specs/issues/373[#373])
-* update information on AutomationML mapping (https://github.com/admin-shell-io/aas-specs/issues/397[#397])
+* remove information on OPC UA mapping (https://github.com/admin-shell-io/aas-specs/issues/373[#373])
+* remove information on AutomationML mapping (https://github.com/admin-shell-io/aas-specs/issues/397[#397])
 * update bibliography (newer versions, link update, removal of entries not referenced)
 * consistent usage of idShortPath and IRDI-Path (https://github.com/admin-shell-io/aas-specs/issues/385[#385])
 * add example for deprecated attribute in class in Annex UML
@@ -107,7 +108,7 @@ Minor Changes:
 | {empty} | xref:spec-metamodel/submodel-elements.adoc#Blob[Blob/contentType] a| now optional
 | {empty} | xref:spec-metamodel/submodel-elements.adoc#Entity[Entity/entityType] a| now optional
 | {empty} | xref:spec-metamodel/submodel-elements.adoc#File[File/contentType] a| now optional
-| {empty} | xref:spec-metamodel/referencing.adoc#FragmentKeys[ragmentKeys/ContainerElement] a| Add new value "ContainerElement" to enumeration FragmentKeys, because AasSubmodelElements was extended
+| {empty} | xref:spec-metamodel/referencing.adoc#FragmentKeys[FragmentKeys/ContainerElement] a| Add new value "ContainerElement" to enumeration FragmentKeys, because AasSubmodelElements was extended
 | {empty} | xref:spec-metamodel/datatypes.adoc#Identifier[Identifier] a| data type: change length from 2000 to 2024 characters
 | {empty} | xref:spec-metamodel/datatypes.adoc#NameType[NameType] a| implicit change due to change of Constraint AASd-002
 | {empty}  | xref:spec-metamodel/common.adoc#Referable[Referable/idShort] a| implicit change because constraint AASd-002 now also allows hyphen
@@ -122,10 +123,10 @@ Minor Changes:
 |===
 |{empty} |*New Elements V3.1 vs V3.0.1* |*Comment*
 
-|{empty} | xref:spec-metamodel/referencing.adoc#AasContainerElements[AasContainerSubmodelElements] | New enumeration for container submodel elements
+|{empty} | xref:spec-metamodel/referencing.adoc#AasContainerSubmodelElements[AasContainerSubmodelElements] | New enumeration for container submodel elements
 |{empty} | xref:spec-metamodel/core.adoc#AssetKind[AssetKind/Role] | New value in enumeration
 |{empty} | xref:spec-metamodel/submodel-elements.adoc#ContainerElement[ContainerElement] | New abstract class
-|{empty} | xref:spec-metamodel/referencing.adoc#AasNonContainerElements[AasNonContainerSubmodelElements] | New enumeration for non-container submodel elements
+|{empty} | xref:spec-metamodel/referencing.adoc#AasNonContainerSubmodelElements[AasNonContainerSubmodelElements] | New enumeration for non-container submodel elements
 |===
 
 .New, Changed or Removed Constraints
@@ -147,6 +148,11 @@ Update version of globalAssetId
 
 Constraint AASd-116:
 "globalAssetId" (case-insensitive) is a reserved key for SpecificAssetId/name with the semantics as defined in `\https://admin-shell.io/aas/3/1/AssetInformation/globalAssetId`.
+
+
+|{empty}  | AASd-120 | Removed a|
+Constraint AASd-120: idShort of submodel elements being a direct child of a SubmodelElementList shall not be specified.
+
 |===
 
 == Changes V3.0.1 vs. V3.0

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

@@ -33,6 +33,7 @@ Subclause xref:general.adoc#events[Events] discusses aspects of event handling.
 [#types-and-instances]
 == Types and Instances
 
+[#life-cycle-with-type-assets-and-instance-assets]
 === Life Cycle with Type Assets and Instance Assets
 
 Industry 4.0 utilizes an extended understanding of assets, comprising elements such as factories, production systems, equipment, machines, components, produced products and raw materials, business processes and orders, immaterial assets (such as processes, software, documents, plans, intellectual property, standards), services, human personnel, etc..

documentation/IDTA-01001/modules/ROOT/pages/includes/constraints.adoc

@@ -36,15 +36,13 @@ every entry needs to be in one line, no \
 :aasd117: pass:q[[underline]#Constraint AASd-117:# xref:ROOT:spec-metamodel/common.adoc#Referable[idShort] of non-identifiable __Referable__s not being a direct child of a xref:ROOT:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] shall be specified.]
 :aasd118: pass:q[[underline]#Constraint AASd-118:# If a supplemental semantic ID (xref:ROOT:spec-metamodel/core.adoc#HasSemantics[HasSemantics/supplementalSemanticId]) is defined, there shall also be a main semantic ID (xref:ROOT:spec-metamodel/core.adoc#HasSemantics[HasSemantics/semanticId]).]
 :aasd119: pass:q[[underline]#Constraint AASd-119:# If any xref:ROOT:spec-metamodel/common.adoc#Qualifier[Qualifier/kind] value of a _Qualifiable/qualifier_ is equal to xref:ROOT:spec-metamodel/common.adoc#QualifierKind[TemplateQualifier] and the qualified element inherits from "_hasKind"_, the qualified element shall be of kind _Template_ (_HasKind/kind = "Template"_).]
-:aasd120: pass:q[[underline]#Constraint AASd-120:# xref:ROOT:spec-metamodel/common.adoc#Referable[idShort] of submodel elements being a direct child of a xref:ROOT:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] shall not be specified.]
 :aasd121: pass:q[[underline]#Constraint AASd-121:# For xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s, the value of xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] of the first _key_ of _Reference/keys_ shall be one of xref:ROOT:spec-metamodel/referencing.adoc#GloballyIdentifiables[GloballyIdentifiables].]
 :aasd122: pass:q[[underline]#Constraint AASd-122:# For external references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ExternalReference], the value of xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] of the first key of _Reference/keys_ shall be one of xref:ROOT:spec-metamodel/referencing.adoc#GenericGloballyIdentifiables[GenericGloballyIdentifiables].]
 :aasd123: pass:q[[underline]#Constraint AASd-123:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference], the value of xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] of the first _key_ of _Reference/keys_ shall be one of xref:ROOT:spec-metamodel/referencing.adoc#AasIdentifiables[AasIdentifiables].]
 :aasd124: pass:q[[underline]#Constraint AASd-124:# For external references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ExternalReference], the last _key_ of _Reference/keys_ shall be either one of _GenericGloballyIdentifiables_ or one of xref:ROOT:spec-metamodel/referencing.adoc#GenericFragmentKeys[GenericFragmentKeys].]
 :aasd125: pass:q[[underline]#Constraint AASd-125:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference/type] = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference] with more than one key in _Reference/keys_, the value of xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] of each of the keys following the first key of _Reference/keys_ shall be one of xref:ROOT:spec-metamodel/referencing.adoc#FragmentKeys[FragmentKeys].]
 :aasd126: pass:q[[underline]#Constraint AASd-126:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference] with more than one key in _Reference/keys,_ the value of xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] of the last xref:ROOT:spec-metamodel/referencing.adoc#Key[Key] in the reference key chain may be one of xref:ROOT:spec-metamodel/referencing.adoc#GenericFragmentKeys[GenericFragmentKeys] or no key at all shall have a value out of xref:ROOT:spec-metamodel/referencing.adoc#GenericFragmentKeys[GenericFragmentKeys].]
-:aasd127: pass:q[[underline]#Constraint AASd-127:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference] with more than one key in _Reference/keys,_ a key with xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] _FragmentReference_ shall be preceded by a key with xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] _File_ or _Blob_. 
-All other Asset Administration Shell fragments, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] values out of xref:ROOT:spec-metamodel/referencing.adoc#AasSubmodelElements[AasSubmodelElements] , do not support fragments.]
+:aasd127: pass:q[[underline]#Constraint AASd-127:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference] with more than one key in _Reference/keys,_ a key with xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] _FragmentReference_ shall be preceded by a key with xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] _File_ or _Blob_. All other Asset Administration Shell fragments, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] values out of xref:ROOT:spec-metamodel/referencing.adoc#AasSubmodelElements[AasSubmodelElements] , do not support fragments.]
 :aasd128: pass:q[[underline]#Constraint AASd-128:# For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[Reference]s with _Reference/type_ = xref:ROOT:spec-metamodel/referencing.adoc#ReferenceTypes[ModelReference], the xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/value] of a xref:ROOT:spec-metamodel/referencing.adoc#Key[Key] preceded by a xref:ROOT:spec-metamodel/referencing.adoc#Key[Key] with xref:ROOT:spec-metamodel/referencing.adoc#Key[Key/type] = xref:ROOT:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] is an integer number denoting the position in the array of the submodel element list.]
 :aasd129: pass:q[[underline]#Constraint AASd-129:# If any xref:ROOT:spec-metamodel/common.adoc#Qualifier[Qualifier/kind] value of a xref:ROOT:spec-metamodel/submodel-elements.adoc#SubmodelElement[SubmodelElement/qualifier] (attribute _qualifier_ inherited via xref:ROOT:spec-metamodel/common.adoc#Qualifiable[Qualifiable]) is equal to xref:ROOT:spec-metamodel/common.adoc#QualifierKind[TemplateQualifier], the submodel element shall be part of a submodel template, i.e. a _Submodel_ with xref:ROOT:spec-metamodel/core.adoc#Submodel[Submodel/kind] (attribute _kind_ inherited via xref:ROOT:spec-metamodel/common.adoc#HasKind[HasKind]) value equal to xref:ROOT:spec-metamodel/common.adoc#ModellingKind[Template].]
 :aasd130: pass:q[[underline]#Constraint AASd-130:# An attribute with data type "string" shall be restricted to the characters as defined in XML Schema 1.0, i.e. the string shall consist of these characters only: ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\u00010000-\u0010FFFF]*$.]

documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/grammar-serialization-reference.adoc

@@ -73,6 +73,6 @@ The examples in this document therefore do not use this prefix.
 
 ....
 
-In the last example the xref:spec-metamodel/common.adoc##HasSemantics[semanticId] of the property with idShort "Temperature" is expected to be "0173-1#02-BAA120#008", the xref:spec-metamodel/referencing.adoc##Reference[referredSemanticId].
+In the last example the xref:spec-metamodel/common.adoc#HasSemantics[semanticId] of the property with idShort "Temperature" is expected to be "0173-1#02-BAA120#008", the xref:spec-metamodel/referencing.adoc#Reference[referredSemanticId].
 
 For further examples including invalid examples please see xref:spec-metamodel/referencing.adoc#constraints[Constraints for Referencing in Asset Administration Shells].

documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc

@@ -28,7 +28,7 @@ Two separate requests make it possible to build up a user interface (UI) and sho
 Values are only available for
 
 * All subtypes of abstract type xref:spec-metamodel/submodel-elements.adoc#DataElement[DataElement],
-* xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList]  and xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] SubmodelElementCollection resp. for their included xref:spec-metamodel/core.adoc#SubmodelElement[SubmodelElement]s,
+* xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList]  and xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] resp. for their included xref:spec-metamodel/core.adoc#SubmodelElement[SubmodelElement]s,
 * xref:spec-metamodel/submodel-elements.adoc#ReferenceElement[ReferenceElement],
 * xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement] + xref:spec-metamodel/submodel-elements.adoc#AnnotatedRelationshipElement[AnnotatedRelationshipElement],
 * xref:spec-metamodel/submodel-elements.adoc#Entity[Entity],
@@ -47,7 +47,7 @@ A leaf submodel element follows the rules for the different submodel elements co
 If it is not a leaf element, the serialization rules must be transitively followed until the value is a leaf submodel element.
 * xref:spec-metamodel/referencing.adoc#Reference[Reference] is serialized in format "Normal".
 * xref:spec-metamodel/core.adoc#SpecificAssetId[SpecificAssetId] is serialized in format "Normal".
-* xref:spec-metamodel/submodel-elements.adoc#SubmodelElement[SubmodelElement]s without a value are not serialized.
+* xref:spec-metamodel/core.adoc#SubmodelElement[SubmodelElement]s without a value are not serialized.
 
 * For each submodel element within the submodel, the submodel collection or submodel list:
 
@@ -316,6 +316,7 @@ is serialized to
 
 [source,json,linenums]
 ----
+{
  "prop1": "value of prop1"
 }
 ----

documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/constraints.adoc

@@ -27,7 +27,6 @@ They are documented as part of the class specification.
 Note: in other words (AASd-117), __idShort__ is mandatory for all __Referable__s except for referables being direct childs of __SubmodelElementList__s and for all __Identifiable__s.
 ====
 
-{aasd120}
 
 {aasd022}
 

documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/overview.adoc

@@ -85,8 +85,8 @@ The elements of package "Core" are specified as first class citizens in Clause x
 Elements of package "Common" are specified in Clause xref:spec-metamodel/common.adoc[].
 The elements of package "Referencing" are specified in Clause xref:spec-metamodel/referencing.adoc[].
 Elements from package "Types" are specified in Clause xref:spec-metamodel/datatypes.adoc[].
-Elements from package "Envirnonment" are specified in Clause xref:spec-metamodel/environment.adoc[].
-Elements from package "ConceptDescriptions" are specified in Clause xref:spec-metamodel/concept-descriptions.adoc[].
+Elements from package "Environment" are specified in Clause xref:spec-metamodel/environment.adoc[].
+Elements from package "ConceptDescriptions" are specified in Clause xref:spec-metamodel/concept-description.adoc[].
 The only package that is not listed is "Data Specifications (Templates)" because data specifications are handled differently.
 Data specification templates are explained in Clause xref:data-specifications.adoc[].