fix or improve explanation for References and Semantics (#482)

* fix formatting

* #480 add example with referredSemanticId

* extension of #480: added invalid examples for all constraints for References

* closes #471 different syntax intelligent matching

* closes #473 Matching semanticId
value-match and exact match

* closes #479 supplementalSemanticId and isCaseOf

* see #479 now isCaseOf included in strategy

* add note that implementations may differ

Co-authored-by: s-heppner <[email protected]>

* grammar

* fix typo

Co-authored-by: s-heppner <[email protected]>

* exact match for semanticIc
+ formatting

---------

Co-authored-by: s-heppner <[email protected]>

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

@@ -444,18 +444,30 @@ This semantic ID helps to easily find the semantic definition of the submodel (s
 
 When comparing two elements, different use cases should be considered in order to define how these two elements are semantically related.
 This clause gives first hints on the aspects to consider when dealing with matching semantic identifiers.
+The actual implementations in applications may differ from the strategies presented here. 
 For example, semantic references including context information as represented in IRDI-Path in ECLASS are not yet considered.
 Sometimes a concept description is derived from another concept description or is identical to or at least compatible with another concept description.
-The metamodel foresees an attribute "isCaseOf" for such semantic IDs.
-However, these are not considered in the matching strategies described in this clause.
+
 
 *Exact Matching (identical semanticIds) – DEFAULT*
 
-* With exact matching, two semantic IDs need to be string-identical.
-** Example: Property with idShort "ManufacturerName" + semanticId 0173-1#02-AAO677#002 and Property with idShort "Herstellername" + semanticId 0173-1#02-AAO677#002 have exactly equal semantics.
+* With exact matching, two semantic IDs need to represent two exact matching references (see xref:general.adoc#matching-algorithm-for-references[Matching Algorithm for References]).
+** Example: Property with idShort "ManufacturerName" + semanticId  value 0173-1#02-AAO677#002 and Property with idShort "Herstellername" + semanticId value 0173-1#02-AAO677#002 have exactly equal semantics if the key types in both semanticIds are identical plus the other attributes of a Reference like _type_ and _referredSemanticId_ as well. So if the first key type of property "ManufacturerName" is "ExternalReference" and the first key type of the semanticId of property  "Herstellername" is "ModelReference" then the two semanticIds are no exact match. Or if the first reference contains a referredSemanticId value and the second does not the two semantic IDs are not exact matches.
+
+====
+Note: Typically, a semanticId does not have a _referredSemanticId_
+====
+
+*Value Matching*
+
+* With value matching, the key values of the two semantic IDs being compared need to be string-identical, i.e. the two references need to value match (see xref:general.adoc#matching-algorithm-for-references[Matching Algorithm for References]).
+** Example: Property with idShort "ManufacturerName" + semanticId 0173-1#02-AAO677#002 and Property with idShort "Herstellername" + semanticId 0173-1#02-AAO677#002 have value equal semantics.
+
 
 *Intelligent Matching (compatible semanticIds)*
 
+Diffent kinds of intelligent matching may be considered to be implemented. Some are explained in the following.
+
 * Ignore Versioning
 ** With intelligent matching, different versions of a concept definition may be matched.
 For example, if semantic versioning is used to version the concept description, then upward or backward compatible versions can be matched.
@@ -467,6 +479,36 @@ In the example above, two IRDIs from ECLASS are compared.
 ECLASS rules ensure that the semantics is always backward compatible for new versions; a new IRDI would be created for breaking changes.
 ====
 
+
+* Consider different syntax of identifiers
+
+** With intelligent matching, different syntax of the same identifier may be matched.
+For example ECLASS allows to specify an identifier of a concept definition as IRDI or as URL.
+ECLASS and IEC CDD both use IRDIs, however, the limiters are different.
+** Example: \https://api.eclass-cdp.com/0173-1-02-AAC895-008
+matches 0173-1#02-AAC895#008
+** Example: 0173-1#02-AAC895#008 matches 0173/1///02#AAC895#008 
+
+* Consider supplemental semantic IDs (any)
+
+** With intelligent matching two sets of semantic IDs may be compared: Input is a set of semantic IDs, not distinguishing between semanticId and supplementalSemanticId. SupplementalSemanticIds are not ordered, so index information is not relevant. The input matches to an element for which either its semanticId is in the Input set of semantic IDs or one of its supplemental IDs matches to ones of the semantic IDs in the Input set.
+** In addition exact or value matching of semantic IDs can be distinguished (see before)
+** Example: Input Set = { 0173/1///02#AAC895#008} matches for a property with semanticId = \https://api.eclass-cdp.com/0173-1-02-AAC895-008 and supplementalSemanticId = 0173/1///02#AAC895#008.
+** Example: Input Set = { 0173-1#02-AAC895#00, \https://api.eclass-cdp.com/0173-1-02-AAC895-008, 0173/1///02#AAC895#008 } would match for a property with semanticId = \https://api.eclass-cdp.com/0173-1-02-AAC895-008 and no supplemental semantic IDs.
+
+* Consider supplemental semantic IDs (all)
+
+** With intelligent matching two sets of semantic IDs may be compared: Input is a set of semantic IDs, not distinguishing between semanticId and supplementalSemanticId. SupplementalSemanticIds are not ordered, so index information is not relevant. The input matches to an element for which all the semantic IDS of the input set are available, either as semantic ID or as supplementalSemanticId. 
+** In addition exact or value matching of semantic IDs can be distinguished (see before) 
+** Example: Input Set = { 0173/1///02#AAC895#008} matches for a property with semanticId = \https://api.eclass-cdp.com/0173-1-02-AAC895-008 and supplementalSemanticId = 0173/1///02#AAC895#008.
+** Example: Input Set = { 0173-1#02-AAC895#00, \https://api.eclass-cdp.com/0173-1-02-AAC895-008, 0173/1///02#AAC895#008 } does not match for a property with semanticId = \https://api.eclass-cdp.com/0173-1-02-AAC895-008 and no supplemental semantic IDs.
+
+* Consider supplemental semantic IDs and isCaseOf
+
+** The two intelligent matching strategies "Consider supplemental semantic IDs (any)" and "Consider supplemental semantic IDs (all)" may be extended to also include the isCaseOf information of a ConceptDescription referenced via one of the semantic IDs (semanticId or supplementalSemanticId) of an element.
+** Example: Input Set = { 0173/1///02#AAC895#008} matches for a property with semanticId = [ModelRef](ConceptDescription) \https://admin-shell.io.example if the isCaseOf value of the referenced concept description with id =  \https://admin-shell.io.example is equal to 0173/1///02#AAC895#008.
+
+
 * Consider Semantic Mappings
 ** Existing semantic mapping information can be considered for intelligent matching.
 Semantic mappings may exist within one and the same dictionary, but also between different dictionaries and ontologies.
@@ -482,6 +524,9 @@ Note: this example does not represent an existing semantic mapping; it is only a
 ** With intelligent matching, domain knowledge available in machine-readable form may be taken into account, such as an "is-a"-relationship between two concept definitions.
 ** Example: a Hammer drill (0173-1#01-ADS698#010) and a percussion drill (0173-1#01-ADS700#010) are drills for mineral material (0173-1#01-ADN177#005) and are compatible with a request or constraints asking for drills for mineral material.
 
+
+
+
 [#matching-algorithm-for-references]
 === Matching Algorithm for References
 
@@ -499,7 +544,7 @@ In this case the data consumer only knows the external ID whereas the provider m
 Matching does not mean to define equivalence classes that allow to overwrite constraints as defined in the specification for valid instances of the metamodel.
 ====
 
-**Equivalence matching of two references**
+**Exact matching of two references**
 
 * Two References are identical if all attributes values are identical.
 
@@ -510,13 +555,15 @@ Matching does not mean to define equivalence classes that allow to overwrite con
 (GlobalReference)0173-1#01-ADS698#010, (GlobalReference)0173-1#01-ADS700#010
 ....
 
-matches
+is no exact match for
 
 [listing]
 ....
 (GlobalReference 0173-1#01-ADS698#010, (FragmentReference)0173-1#01-ADS700#010
 ....
 
+but a value match.
+
 **Value matching of two references**
 
 * An external reference A matches an external reference B if all values of all keys are identical.

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

@@ -71,7 +71,7 @@ For model references, i.e. xref:ROOT:spec-metamodel/referencing.adoc#Reference[R
 :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_. \
+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.]

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

@@ -7,6 +7,7 @@ https://creativecommons.org/licenses/by/4.0/).
 SPDX-License-Identifier: CC-BY-4.0
 
 ////
+
 [[part1-introduction]]
 = Introduction
 

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

@@ -67,5 +67,12 @@ The examples in this document therefore do not use this prefix.
 
 
 (Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title
+
+
+[ModelRef- 0173-1#02-BAA120#008 -](Submodel)https://example.com/aas/1/1/1234859590, (Property)Temperature
+
 ....
 
+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/spec-metamodel/referencing.adoc

@@ -874,15 +874,52 @@ Note: which kind of fragments are supported depends on the content type and the
 In the following examples for valid und invalid model references and external references are given.
 The notation follows the grammar as defined in Clause xref:mappings/mappings.adoc#reference-serialization[Text Serialization of Values of Type "Reference"].
 
+
+
 [.underline]#Examples for valid references:#
 
 [example]
 ....
 (Submodel)https://example.com/aas/1/1/1234859590
 
+[ModelRef](Submodel)https://example.com/aas/1/1/1234859590
+
 (GlobalReference)https://example.com/specification.html
+
+[ExternalRef](GlobalReference)https://example.com/specification.html
+....
+
+
+
+[.underline]#Examples for invalid references:#
+
+[example]
+....
+[Submodel](GlobalReference)https://example.com/aas/1/1/1234859590
 ....
 
+Key type "Submodel" is not a globally identifiable (see Constraint AASd-121).
+
+[example]
+....
+[ExternalRef](Submodel)https://example.com/aas/1/1/1234859590
+....
+
+Key type "Submodel" is no generic globally identifiable (see Constraint AASd-122).
+
+
+[example]
+....
+[ModelRef](GlobalReference)https://example.com/aas/1/1/1234859590
+....
+
+Key type "GlobalReference" is no AAS identifiable (see Constraint AASd-123). 
+The last key type "GlobalReference" is neither a generic globally identifiable nor a generic fragment key (see Constraint AASd-124).
+
+
+
+
+
 [.underline]#Examples for valid external references:#
 
 [example]
@@ -910,6 +947,8 @@ https://example.com/specification.html#Hints
 ....
 ====
 
+
+
 [.underline]#Examples for valid model references:#
 
 [example]
@@ -932,7 +971,7 @@ Note:
 
 [example]
 ....
-(SubmodelElementCollection)0, (MultiLanguageProperty)Title
+(SubmodelElementList)0, (MultiLanguageProperty)Title
 ....
 
 may be identical to
@@ -945,8 +984,7 @@ may be identical to
 semantically and content-wise.
 The difference is that more than one document is allowed in the first submodel and thus a submodel element list is defined:
 elements in a list are numbered.
-However, it is also possible to define a display name in this case.
-The display name of the SubmodelElementCollection should be the same in both bases, e.g. "Users Manual".
+
 ====
 
 [example]
@@ -976,6 +1014,9 @@ https://example.com/specification.html
 (Submodel)https://example.com/aas/1/1/1234859590, (Blob)Specification, (FragmentReference)Hints
 ....
 
+
+
+
 [.underline]#Examples for invalid model references:#
 
 [example]
@@ -985,24 +1026,38 @@ https://example.com/specification.html
 
 This is an external reference but no model reference.
 
+
 [example]
 ....
 (Property)0173-1#02-BAA120#008
 ....
 
-This reference does not start with the ID of an Identifiable.
-Additionally, the value is not valid xref:spec-metamodel/common.adoc#Referable[idShort] for a Property submodel element.
+This reference does not start with the ID of an Identifiable, i.e. key type "Property" is no AAS identifiable (see Constraint AASd-123).
+Additionally, the value is not a valid xref:spec-metamodel/common.adoc#Referable[idShort] for a Property submodel element since it contains special characters like "#" (see Constraint AASd-002).
+
+
+[example]
+....
+[ModelRef](FragmentReference)Hints (Property)Temperature
+....
+
+Key "Property" is no generic fragment key and therefore fragment key "FragmentReference" is not allowed before (see Constraint AASd-126).
+
+
 
 [example]
 ....
 (Submodel)https://example.com/aas/1/1/1234859590, (EventElement)Event, (FragmentReference)Comment
 ....
 
-This model reference is invalid because fragment references so far are only defined for _File_ and _Blob_ submodel elements (see Constraint AASd-127).
+This model reference is invalid because fragment references so far are only defined for "File" and "Blob" submodel elements (see Constraint AASd-127).
+
 
 [example]
 ....
 (AssetAdministrationShell)https://example.com/aas/1/0/12348, (Submodel)https://example.com/aas/1/1/1234859590, (Property)Temperature
 ....
 
-This is not a valid model reference because _AssetAdministrationShell_ and _Submodel_ are both global identifiables.
+This is not a valid model reference because key type "AssetAdministrationShell"  and "Submodel" are both global identifiables and there shall be only one (see Constraints AASd-125).
+
+