minor changes (#475)

* fix typo: ModellReference to ModelReference

* fix xref and <<l>>-links
add xref for constant Clause references etc.
other syntactical or formatting issues

* Fix Refs, Implement Minor Fixes and Editorial Changes (#474)

* added more xref

* add xref

* xref added

* correct version like for all other metamodel semantic IDs to V3.1

* add <<ordered>> to Reference/Key
(table was correct)

* add xref

* start with small letter after Note: consistently

* add name to SML (even if not needed in serilaization)

* add xref

* correct puml to denote inheritance as explained in Annex UML

* fix ref to issue in github (formatting)

* AASd-116 all semantic Id of metamodel elements increased version 3/1

* Fix xrefs and attributes in constraints.adoc

* Fix dot lines

* Remove duplicated word

---------

Co-authored-by: Igor Garmaev <[email protected]>
Co-authored-by: zrgt <[email protected]>

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

@@ -79,7 +79,7 @@ Minor Changes:
 * 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])
 * 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)
+* consistent usage of idShortPath and IRDI-Path (https://github.com/admin-shell-io/aas-specs/issues/385[#385])
 * editorial changes
 
 
@@ -123,6 +123,12 @@ Constraint AASd-002: _idShort_ of __Referable__s shall only feature letters, dig
 Change since Entity/entityType is now optional
 
 Constraint AASd-014: Either the attribute globalAssetId or specificAssetId of an Entity must be set if Entity/entityType is set to "SelfManagedEntity".
+
+|{empty}  | AASd-016 | Update a|
+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`.
 |===
 
 == Changes V3.0.1 vs. V3.0

documentation/IDTA-01001/modules/ROOT/pages/grammar-semantic-ids-metamodel.adoc

@@ -37,7 +37,7 @@ For data specifications this is defined within the corresponding specifications
 ....
 
 ====
-Note: The Data Specification ID should include versioning information.
+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].
 ====

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

@@ -13,8 +13,8 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 === Format "Path" (idShortPath Serialization) in JSON
 
 To get only the idShortPaths of a submodel element hierarchy, the serialization format is specified in terms of an idShortPath notation to be returned in an JSON array.
-The notation differs depending on whether a SubmodelElementCollection or a SubmodelElementList is present.
-In the first case, the submodel element's idShort is separated by "." (dot) from top level down to child level.
+The notation differs depending on whether a xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] or a xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] is present.
+In the first case, the submodel element's xref:spec-metamodel/common.adoc#Referable[idShort] is separated by "." (dot) from top level down to child level.
 In the second case, square brackets with an index "[<Index>]" are appended after the idShort of the containing SubmodelElementList.
 In any case, the first item of any idShortPath is the idShort of the requested element.
 
@@ -51,7 +51,7 @@ Submodel: MySubmodel
 *** Property: "MySubTestValue1"
 *** Property: "MySubTestValue2"
 ** SML: MySubSubmodelElementList2
-*** SML
+*** SML: MySubSubmodelElementList3
 **** Property: "MySubTestValue3"
 ====
 
@@ -76,5 +76,5 @@ idShortPaths for SMC MySubmodelElementCollection within the Submodel above:
 ----
 
 ====
-Note: There is no idShortPath for Identifiables because idShort is optional for Identifiables.
+Note: There is no idShortPath for xref:spec-metamodel/common.adoc#Identifiable[Identifiable]s because idShort is optional for Identifiables.
 ====

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

@@ -25,13 +25,13 @@ 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 _DataElement_,
-* SubmodelElementList and SubmodelElementCollection resp. for their included SubmodelElements,
-* ReferenceElement,
-* RelationshipElement + AnnotatedRelationshipElement,
-* Entity,
-* BasicEventElement,
-* Submodel.
+* 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/submodel-elements.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],
+* xref:spec-metamodel/submodel-elements.adoc#BasicEventElement[BasicEventElement],
+* xref:spec-metamodel/submodel-elements.adoc#Submodel[Submodel].
 
 Capabilities are excluded from the serialization scope since only data containing elements are in the focus.
 They are consequently omitted in the serialization.
@@ -45,16 +45,16 @@ 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.
 * For each submodel element within the submodel, the submodel collection or submodel list:
 
-** _Property_ is serialized as $\{Property/idShort}: $\{Property/value} where $\{Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section).
-** _MultiLanguageProperty_ is serialized as named JSON object with $\{MultiLanguageProperty/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#Property[Property]  is serialized as $\{Property/idShort}: $\{Property/value} where $\{Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section).
+** xref:spec-metamodel/submodel-elements.adoc#MultiLanguageProperty[MultiLanguageProperty]  is serialized as named JSON object with $\{MultiLanguageProperty/idShort} as the name of the containing JSON property.
 The JSON object contains an array of JSON objects for each language of the _MultiLanguageProperty_ with the language as name and the corresponding localized string as value of the respective JSON property.
 The language name is defined as two chars according to ISO 639-1.
-** _Range_ is serialized as named JSON object with $\{Range/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#Range[Range]  is serialized as named JSON object with $\{Range/idShort} as the name of the containing JSON property.
 The JSON object contains two JSON properties.
 The first is named "min".
 The second is named "max".
 Their corresponding values are $\{Range/min} and $\{Range/max}.
-** _File_ and _Blob_ are serialized as named JSON objects with $\{File/idShort} or $\{Blob/idShort}as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#File[File]  and xref:spec-metamodel/submodel-elements.adoc#Blob[Blob]  are serialized as named JSON objects with $\{File/idShort} or $\{Blob/idShort}as the name of the containing JSON property.
 The JSON object contains two JSON properties.
 The first refers to the content type named $\{File/contentType} resp.
 $\{Blob/contentType}.
@@ -64,35 +64,35 @@ The resulting ValueOnly object is indistinguishable whether it contains File or
 Therefore, the receiver needs to take the type of the target resource into account.
 Since the receiver knows in advance if a File or a Blob SubmodelElement shall be manipulated, it can parse the transferred Value-Only object accordingly as a File or Blob object.
 For Blobs the value attribute is optional (in this case a Blob can be distinguished from a File).
-** _SubmodelElementCollection_ is serialized as named JSON object with $\{SubmodelElementCollection/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] is serialized as named JSON object with $\{SubmodelElementCollection/idShort} as the name of the containing JSON property.
 The elements contained within the struct are serialized according to their respective type with $\{SubmodelElement/idShort} as the name of the containing JSON property.
-** _SubmodelElementList_ is serialized as a named JSON array with $\{SubmodelElementList/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] is serialized as a named JSON array with $\{SubmodelElementList/idShort} as the name of the containing JSON property.
 The elements in the JSON array are the ValueOnly serializations of the elements contained in the SubmodelElementList while preserving the order, i.e. index n in the JSON array is the ValueOnly serialization of the element at index n of the SubmodelElementList.
-** _ReferenceElement_ is serialized as $\{ReferenceElement/idShort}: $\{ReferenceElement/value} where $\{ReferenceElement/value} is the serialization of the _Reference_ class in format "Normal".
-** _RelationshipElement_ is serialized as named JSON object with $\{RelationshipElement/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#ReferenceElement[ReferenceElement] is serialized as $\{ReferenceElement/idShort}: $\{ReferenceElement/value} where $\{ReferenceElement/value} is the serialization of the _Reference_ class in format "Normal".
+** xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement] is serialized as named JSON object with $\{RelationshipElement/idShort} as the name of the containing JSON property.
 The JSON object contains two JSON properties.
 The first is named "first".
 The second is named "second".
 Their corresponding values are $\{RelationshipElement/first} resp.
 $\{Relationship/second}.
 The values are serialized according to the serialization of a _ReferenceElement_ (see above).
-** _AnnotatedRelationshipElement_ is serialized according to the serialization of a _RelationshipElement_ (see above).
+** xref:spec-metamodel/submodel-elements.adoc#AnnotatedRelationshipElement[AnnotatedRelationshipElement] is serialized according to the serialization of a _RelationshipElement_ (see above).
 Additionally, a third named JSON object is introduced with "annotations" as the name of the containing JSON property.
 The value is $\{AnnotatedRelationshipElement/annotations}.
 The values of the array items are serialized depending on the type of the annotation data element.
 Annotations are optional.
-** _Entity_ is serialized as named JSON object with $\{Entity/idShort} as the name of the containing JSON property.
+** xref:spec-metamodel/submodel-elements.adoc#Entity[Entity] is serialized as named JSON object with $\{Entity/idShort} as the name of the containing JSON property.
 The JSON object contains four JSON properties.
 The first is named "statements" $\{Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause.
 The second is named "globalAssetId" and the third "specificAssetIds".
 Either a "globalAssetId" value or a "specificAssetIds" value shall exist.
 The other attributes are optional.
 "globalAssetId" corresponds to a _Reference_ (see above).
-"SpecificAssetIds" is an array of objects serializing _SpecificAssetId_.
+"SpecificAssetIds" is an array of objects serializing xref:spec-metamodel/common.adoc#SpecificAssetId[SpecificAssetId].
 A single _SpecificAssetId_ in the array corresponds to the serialization of the _SpecificAssetId_ class in format "Normal".
 The forth property is named "entityType" and contains a string representation of $\{Entity/entityType}.
-Statements and the entityType are optional.
-** _BasicEventElement_ is serialized as named JSON object with $\{BasicEventElement/idShort} as the name of the containing JSON property.
+_Statements_ and the _entityType_ are optional.
+** xref:spec-metamodel/submodel-elements.adoc#BasicEventElement[BasicEventElement] is serialized as named JSON object with $\{BasicEventElement/idShort} as the name of the containing JSON property.
 The JSON object contains one JSON property named "observed" with the corresponding value of $\{BasicEventElement/observed} as the standard serialization of the _Reference_ class.
 
 
@@ -506,7 +506,7 @@ For a BasicEventElement named "MyBasicEvent", the Value-Only-payload is minimize
 === JSON-Schema for the Value-Only Serialization
 
 The following JSON-Schema represents the validation schema for the ValueOnly-Serialization of submodel elements.
-This holds true for all submodel elements mentioned in the previous clause except for _SubmodelElementCollections_.
+This holds true for all submodel elements mentioned in the previous clause except for xref:spec-metamodel/submodel-elements.adoc#submodel-element-collection-attributes[SubmodelElementCollection.
 Since xref:spec-metamodel/submodel-elements.adoc#submodel-element-collection-attributes[SubmodelElementCollection]s are treated as objects containing submodel elements of any kind, the integration into the same validation schema would result in a circular reference or ambiguous results ignoring the actual validation of submodel elements other than _SubmodelElementCollections_.
 Hence, the same validation schema must be applied for each _SubmodelElementCollection_ within a submodel element hierarchy.
 In this case, it may be necessary to create a specific JSON-Schema for the individual use case.

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

@@ -558,7 +558,7 @@ e|xs:yearMonthDuration |see: https://www.w3.org/TR/xmlschema-2/#yearMonthDuratio
 h|Enumeration: |[[DataTypeDefRdf]]DataTypeDefRdf
 h|Explanation: |Enumeration listing all RDF types
 |Set of: |--
-h|ID: | `\https://admin-shell.io/aas/3/0/DataTypeDefRdf`
+h|ID: | `\https://admin-shell.io/aas/3/1/DataTypeDefRdf`
 
 h|Literal h|Explanation
 e|rdf:langString |String with a language tag

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

@@ -114,7 +114,7 @@ include::partial$diagrams/49-key.puml[]
 ....
 
 
-Keys are used to define references (_Reference_).
+Keys are used to define references (xref:spec-metamodel/referencing.adoc#Reference[Reference]).
 
 <<model-for-refs-keys>> presents a logical model of key types.
 These logical enumerations are used to formulate constraints.

documentation/IDTA-01001/modules/ROOT/partials/diagrams/90-submodel-element.puml

@@ -4,15 +4,20 @@
 
 !include https://raw.githubusercontent.com/admin-shell-io/aas-specs/IDTA-01001-3-1_working/documentation/IDTA-01001/modules/ROOT/partials/diagrams/classes/submodel-element.puml
 abstract class SubmodelElement {
+  .. ::Referable ..
   +idShort: IdShortType[0..1]
   +displayName: MultiLanguageNameType[0..1]
   +description: MultiLanguageTextType[0..1]
+  +category: NameType[0..1] <<Deprecated>>
+  .. ::HasExtensions ..
   +extension: Extension[0..*]
+  .. ::HasSemantics ..
   +semanticId: Reference[0..1]
   +supplementalSemanticId: Reference[0..*]
+  .. ::Qualifiable ..
   +qualifier: Qualifier[0..*]
-  +embeddedDataSpecification: EmbeddedDataSpecification[0..*]
-  +category: NameType[0..1] <<Deprecated>>
+  .. ::HasDataSpecification ..
+  +dataSpecification: Reference[0..*]
 }
 
 !include https://raw.githubusercontent.com/admin-shell-io/aas-specs/IDTA-01001-3-1_working/documentation/IDTA-01001/modules/ROOT/partials/diagrams/classes/relationship-element.puml

documentation/IDTA-01001/modules/ROOT/partials/diagrams/classes/reference.puml

@@ -2,7 +2,7 @@
 class Reference {
   +type: ReferenceTypes
   +referredSemanticId: Reference[0..1]
-  +key: Key[1..*]
+  +key: Key[1..*] <<ordered>>
 }
 Reference ..> Reference
 @enduml