admin-shell-io · BirgitBoss · Oct 26, 2024 · Oct 17, 2024 · Oct 17, 2024 · Oct 17, 2024
diff --git a/documentation - Copy.zip b/documentation - Copy.zip
diff --git a/documentation/IDTA-01001/modules/ROOT/pages/annex/uml.adoc b/documentation/IDTA-01001/modules/ROOT/pages/annex/uml.adoc
@@ -276,6 +276,7 @@ In this case, it is recommended to add an "s".
 In case of resulting incorrect English (e.g. isCaseOf isCaseOfs), it must be decided whether to support such exceptions.
 ====
 
+[#templates-inheritance-qualifiers-and-categories]
 == Templates, Inheritance, Qualifiers, and Categories
 
 At first glance, there seems to be some overlapping within the concepts of data specification templates, extensions, inheritance, qualifiers, and categories introduced in the metamodel.
@@ -320,6 +321,7 @@ Example: the actual temperature might be good enough for non-critical visualizat
 * Concept qualifiers are used to avoid multiplying existing semantically clearly defined concepts with the corresponding qualifier information, e.g. life cycle.
 * Template qualifiers are used to guide the creation and validation of element instances.
 
+[#omg-uml-specifics]
 == Notes to Graphical UML Representation
 
 Specific graphical modelling rules, which are used in this specification but not included in this form, are explained below xref:bibliography.adoc#bib35[[35\]].
@@ -399,15 +401,21 @@ include::partial$diagrams/uml-basics/85-experimental-classes.puml[]
 ....
 
 
-<<image-86-deprecated-elements>> depicts a deprecated class, which is marked by the stereotype "Deprecated".
+<<image-deprecated-class>> depicts a deprecated class, which is marked by the stereotype "Deprecated" whereas <<image-deprecated-attribute>> depicts a deprecated attribute within a class.
 
-.Graphical Representation for Deprecated Elements
-[[image-86-deprecated-elements]]
-[plantuml, 86-deprecated-elements, svg]
+.Graphical Representation for Deprecated Class
+[[image-deprecated-class]]
+[plantuml, deprecated-class, svg]
 ....
-include::partial$diagrams/uml-basics/86-deprecated-elements.puml[]
+include::partial$diagrams/uml-basics/deprecated-class.puml[]
 ....
 
+.Graphical Representation for Deprecated Attribute
+[[image-deprecated-attribute]]
+[plantuml, deprecated-attribute, svg]
+....
+include::partial$diagrams/uml-basics/deprecated-attribute.puml[]
+....
 
 <<image-87-template-class>> shows a class representing a template.
 It is marked by the stereotype "Template".

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc
@@ -60,7 +60,7 @@ Major Changes:
 ** introduce equivalent matching and rename exact matching to value matching
 ** added notes
 * (Editorial) Adding metamodel element IDs to tables themselves for easier usage (besides grammar defining how to derive them) (https://github.com/admin-shell-io/aas-specs/issues/366[#366])
-* Update all metamodel element IDs to V3.1
+* Update all metamodel element IDs to V3.1 https://github.com/admin-shell-io/aas-specs/issues/366[#366])
 * Transfer of chapters on formats Metadata, Paths and Value-Only from Part 2 API to Part 1 Metamodel (https://github.com/admin-shell-io/aas-specs/issues/325[#325])
 * Enhanced documentation or Value-Only serialization (https://github.com/admin-shell-io/aas-specs/issues/371[#371], https://github.com/admin-shell-io/aas-specs/issues/370[#370])
 * (Editorial) Update Chapter on Value-Only Serialization
@@ -80,6 +80,7 @@ Minor Changes:
 * 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[#385])
+* add example for deprecated attribute in class in Annex UML
 * editorial changes
 
 

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/data-specifications.adoc b/documentation/IDTA-01001/modules/ROOT/pages/data-specifications.adoc
@@ -67,7 +67,7 @@ a|Description of how and in which context the data specification template is app
 
 .2+e|administration 3+| `\https://admin-shell.io/aas/3/1/DataSpecification/administration`
 a|
-Administrative information of an identifiable element
+Administrative information of the data specification template
 
 
 ====

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/grammar-semantic-ids-metamodel.adoc b/documentation/IDTA-01001/modules/ROOT/pages/grammar-semantic-ids-metamodel.adoc
@@ -153,6 +153,7 @@ In case of an attribute with a cardinality greater than 1, no further attributes
 
 ====
 Note: although the attribute name in UML is always singular, the attribute name is annotated by the plural "s" if the cardinality is > 1.
+This also holds if the resulting English is not good or valid English (see example for "isCaseOfs").
 ====
 
 [.underline]#Valid examples#:
@@ -165,6 +166,8 @@ AAS:Operation/inputVariables
 AAS:AssetAdministrationShell/submodels
 
 AAS:Submodel/submodelElements
+
+AAS:ConceptDescription/isCaseOfs
 ....
 
 _[.underline]#Invalid examples:#_
@@ -176,8 +179,10 @@ AAS:AssetAdministrationShell/submodels/administration/version
 AAS:Submodel/Property/idShort
 ....
 
+////
 These semantic identifiers are used as values for the _RefSemantic_ attribute in AutomationML Mapping of the Asset Administration Shell.
 They are also used in OPC UA to describe the semantics of the metamodel via the OPC UA _HasDictionaryEntry_ reference type.
+////
 
 Additional identifiers might be needed for specific serializations and mappings, e.g. for a set of Asset Administration Shells or a set of available concept descriptions.
 Here, the Asset Administration Shell metamodel and specification does not give any recommendations.
@@ -191,12 +196,17 @@ Their corresponding name space qualifiers are defined individually.
 
 In xml and JSON, data specifications are embedded into the schema itself using the attribute "embeddedDataSpecification".
 Here, no concept identifier shall be used.
-For example,
+
+_[.underline]#Invalid example:#_
 
 [example]
 ....
 AAS:ConceptDescription/embeddedDataSpecifications
 ....
 
-is not a valid concept identifier.
-_AAS:DataSpecificationContent_ is a valid concept identifier.
+[.underline]#Valid example#:
+
+[example]
+....
+AAS:DataSpecificationContent 
+....
diff --git a/...tation/IDTA-01001/modules/ROOT/pages/includes/embedded-data-specifications.adoc b/...tation/IDTA-01001/modules/ROOT/pages/includes/embedded-data-specifications.adoc
@@ -7,8 +7,7 @@ Consequently, some serializations or mappings support exactly the data descripti
 In the case of restricted use of data specifications, we speak of "embedded data specifications".
 <<image-59-embedded-data-specifications>> explains the realization: instead of a set of external global references to externally defined data specifications, a set of pairs consisting of an external global reference to a data specification and the data specification content itself are directly "embedded".
 Here, the data specification content belongs to the schema, while the data specification including its content are not part of the schema in the general concept.
-This is similar to the concept of _semanticIds_: either it is an external global reference to an external concept dictionary, or it is a reference to a concept description within the schema.
-However, there is only one reference allowed for _semanticId_, whereas a set of data specification references is permitted for data specifications.
+
 
 .Realization of Embedded Data Specifications
 [[image-59-embedded-data-specifications]]

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/includes/valueonly.adoc b/documentation/IDTA-01001/modules/ROOT/pages/includes/valueonly.adoc
@@ -26,12 +26,12 @@ 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/submodel-elements.adoc#SubmodelElement[SubmodelElement]s,
+* 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#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].
+* xref:spec-metamodel/core.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.
@@ -88,7 +88,7 @@ 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 xref:spec-metamodel/common.adoc#SpecificAssetId[SpecificAssetId].
+"SpecificAssetIds" is an array of objects serializing xref:spec-metamodel/core.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.

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/preamble.adoc b/documentation/IDTA-01001/modules/ROOT/pages/preamble.adoc
@@ -44,13 +44,13 @@ Clause xref:introduction.adoc[] gives a short introduction into the content of t
 
 Clause xref:general.adoc[] summarizes relevant, existing content from the standardization of Industry 4.0; i.e. it provides an overview and explains the motives, but is not absolutely necessary for an understanding of the subsequent definitions.
 
-Clause xref:grammar-semantic-ids-metamodel.adoc[]
+Clause xref:grammar-semantic-ids-metamodel.adoc[] defines how to create semantic identifiers for the elements of the metamodel itself.
 
 Clause xref:spec-metamodel/nav-spec.adoc[] is the main normative part of the document.
 It stipulates structural principles of the Administration Shell in a formal manner to ensure an exchange of information using Asset Administration Shells.
 A UML diagram has been defined for this purpose.
 
-Clause xref:data-specifications.adoc[] explains how to define predefined data specifications, including those for defining concept descriptions.
+Clause xref:data-specifications.adoc[] explains how to define predefined data specifications, including those for defining concept descriptions. A discussion on the difference of data specification templates, inheritance, qualifiers and categories can be found in the xref:annex/uml.adoc[]#templates-inheritance-qualifiers-and-categories[Annex]. 
 
 Clause xref:mappings.adoc[] provides information on the exchange of information compliant to this specification in existing data formats like XML, JSON, or RDF.
 For this purpose additional formats are defined as well as needed text serializations of complex types.
@@ -64,7 +64,7 @@ Annex xref:annex/requirements.adoc[]  collects the requirements from various doc
 Annex xref:annex/valueonly-serialization-example.adoc[] and example of a Value-Only serialization as explained in Clause xref:mappings.adoc#value-only-serialization-in-json[Mappings] is given.
 
 Annex xref:annex/backus-naur-form.adoc[] defines the grammar language used in the specification.
-Annex xref:annex/uml.adoc[] contains information about UML, while Annex xef:annex/uml-templatex.adoc provides the tables used to specify UML classes etc. as used in this specification.
+Annex xref:annex/uml.adoc[] contains information about UML, while Annex xef:annex/uml-templates.adoc[] provides the tables used to specify UML classes etc. as used in this specification.
 xref:annex/handling-constraints.adoc[] explains the numbering of constraints used in the specification.
 
 Annex xref:annex/usage-metamodel.adoc[] provides some hints for modelers.

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/sharedAnnex_alt.zip b/documentation/IDTA-01001/modules/ROOT/pages/sharedAnnex_alt.zip
diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/common.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/common.adoc
@@ -586,7 +586,7 @@ include::partial$diagrams/23-referable.puml[]
 The metamodel differentiates between elements that are identifiable, referable, or none of both.
 The latter means they are neither inheriting from _Referable_ nor from _Identifiable_, which applies e.g. to __Qualifier__s.
 
-Referable elements can be referenced via the _idShort_ (except for elements within a xref:spec-metamodel/submodel-elements.adoc#submodel-element-list-attributes [SubmodelElementList]).
+Referable elements can be referenced via the _idShort_ (except for elements within a xref:spec-metamodel/submodel-elements.adoc#submodel-element-list-attributes[SubmodelElementList]).
 For details on referencing, see Clause xref:spec-metamodel/referencing.adoc[].
 
 Not every element of the metamodel is referable.

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/nav-spec.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/nav-spec.adoc
@@ -17,7 +17,7 @@ An overview of the metamodel of the Asset Administration Shell is given in Subcl
 
 The legend of the UML diagrams and the table specification of the classes is explained in Annex xref:annex/uml-templates.adoc[] and Annex xref:annex/uml.adoc[].
 Readers familiar with UML may skip xref:annex/uml.adoc#omg-uml-general[OMG UML General].
-It is however recommended to have a look at the specifics used in this modelling, especially those on dealing with model references.
+It is however recommended to have a look at the xref:annex/uml.adoc#omg-uml-specifics[specifics] used in this modelling, especially those on dealing with model references.
 
 ////
 ====

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc
@@ -13,7 +13,7 @@ include::../includes/constraints.adoc[]
 
 == Overview
 
-To date, two kinds of references are distinguished: references to external objects or entities (external reference) and references to model elements of the same or another Asset Administration Shell (model reference).
+Two kinds of references are distinguished: references to external objects or entities (external reference) and references to model elements of the same or another Asset Administration Shell (model reference).
 Model references are also used for metamodel inherent relationships like submodels of an Asset Administration Shell (notation see Annex xref:ROOT:annex/concepts-aas.adoc[]).
 
 An external reference is a unique identifier.
@@ -159,7 +159,7 @@ The name of the model element is explicitly listed.
 |xref:KeyTypes[KeyTypes]|1
 
 .2+e|value 3+| `\https://admin-shell.io/aas/3/1/Key`
-a|The key value, for example an IRDI or a URI |xref:spec-metamodel/datatypes.adoc#Identifier[Identifier] |1
+a|The key value, for example an IRDI or a URI or the xref:spec-metamodel/common.adoc#Referable[idShort] or any other fragment value |xref:spec-metamodel/datatypes.adoc#Identifier[Identifier] |1
 |===
 
 An example for using a _FragmentId_ as type of a key is a reference to an element within a file that is part of an Asset Administration Shell aasx package.
@@ -927,7 +927,7 @@ This is an external reference but no model reference.
 ....
 
 This reference does not start with the ID of an Identifiable.
-Additionally, the value is not valid idShort for a Property submodel element.
+Additionally, the value is not valid xref:spec-metamodel/common.adoc#Referable[idShort] for a Property submodel element.
 
 [example]
 ....

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/submodel-elements.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/submodel-elements.adoc
@@ -442,7 +442,7 @@ Co-managed entities need to be part of a self-managed entity.
 a|
 Self-managed entities have their own Asset Administration Shell but can be part of another composite self-managed entity.
 
-The asset of an I4.0 Component is a self-managed entity per definition.
+The asset represented by an Asset Administration Shell is a self-managed entity per definition.
 
 |===
 

diff --git a/documentation/IDTA-01001/modules/ROOT/partials/diagrams/48-reference.puml b/documentation/IDTA-01001/modules/ROOT/partials/diagrams/48-reference.puml
@@ -6,6 +6,5 @@
 !include https://raw.githubusercontent.com/admin-shell-io/aas-specs/IDTA-01001-3-1_working/documentation/IDTA-01001/modules/ROOT/partials/diagrams/classes/enum-reference-types.puml
 
 Reference ..> ReferenceTypes
-Reference ..> Reference
 Reference ..> Key
 @enduml
diff --git a/documentation/IDTA-01001/modules/ROOT/partials/diagrams/89-asset-administration-shell.puml b/documentation/IDTA-01001/modules/ROOT/partials/diagrams/89-asset-administration-shell.puml
@@ -46,7 +46,7 @@ class Submodel{
   +category: NameType[0..1] <<Deprecated>>
   .. ::HasExtensions ..
   +extension: Extension[0..*]
-    .. ::HasKind ..
+  .. ::HasKind ..
   +kind: ModellingKind[0..1]
   .. ::HasSemantics ..
   +semanticId: Reference[0..1]

diff --git a/documentation/IDTA-01001/modules/ROOT/partials/diagrams/uml-basics/deprecated-attribute.puml b/documentation/IDTA-01001/modules/ROOT/partials/diagrams/uml-basics/deprecated-attribute.puml
@@ -0,0 +1,9 @@
+@startuml
+!theme idta from https://raw.githubusercontent.com/admin-shell-io/aas-specs-antora/main/plantuml/
+
+
+class Class1  {
+  +attr: Class2 <<Deprecated>>
+}
+
+@enduml
diff --git a/...ms/uml-basics/86-deprecated-elements.puml → ...diagrams/uml-basics/deprecated-class.puml b/...ms/uml-basics/86-deprecated-elements.puml → ...diagrams/uml-basics/deprecated-class.puml
@@ -1,6 +1,6 @@
 @startuml
 !theme idta from https://raw.githubusercontent.com/admin-shell-io/aas-specs-antora/main/plantuml/
 
-
 class Class1 <<Deprecated>>
+
 @enduml