Skip to content

Commit

Permalink
Merge branch 'IDTA-01001-3-1_working' into BiBo/editorialChanges2
Browse files Browse the repository at this point in the history
  • Loading branch information
@BirgitBoss
BirgitBoss authored Dec 13, 2024
2 parents 7317b7e + a1a9205 commit f90b70d
Show file tree
Hide file tree
Showing 1,504 changed files with 27,969 additions and 16,754 deletions.
25 changes: 23 additions & 2 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ If you are contributing for the first time, please inform yourself about the [LI


**Create Feature branches**.
We develop using the feature branches, see [this section of the Git book].
We develop using feature branches, see [this section of the Git book].

[this section of the Git book]: https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows.

Expand Down Expand Up @@ -88,7 +88,6 @@ Minor changes (simple failures, typos, *etc.*) and additional content (more exam

Major changes must first be presented and approved in the [IDTA] workstream "AAS in Detail". If the creator of a PR is not a member of the workstream, a dedicated assignee will present it.

[Platform Industrie 4.0]: http://www.plattform-i40.de
[IDTA]: https://industrialdigitaltwin.org/


Expand All @@ -107,3 +106,25 @@ You successfully contributed to the aas-spec-api repository.
If you are a member of the workstream team, please delete the feature branch you directly created within the aas-specs repository.

Otherwise, if you are not part of the team and you forked the repository, feel free to delete your fork.


## License Headers & Licensing

By default, all files contributed require headers - this will ensure the license and copyright clearing at the end. Only if inline comments are not possible, e.g., for JSON files, the copyright declaration can be omitted.

Also, all contributions must have the same license as the source.

The header should follow the following template:

```
////
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
////
```

53 changes: 36 additions & 17 deletions documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,25 +40,32 @@ 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])
* 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])
* Change RelationshipElement: attributes "first" and "second" now optional (conformant to "min" and "max" of "Range")(https://github.com/admin-shell-io/aas-specs/issues/412[#412]), AnnotatedRelationshipElement inherits from RelationshipElement and is thus also affected.
* Change File and Blob: attribute "contentType" now optional (https://github.com/admin-shell-io/aas-specs/issues/412[#412]),
* Relaxation of grammar for semantic IDs for metamodel elements in the context of data specifications (https://github.com/admin-shell-io/aas-specs/issues/307[#307])
* Terms and Definitions adopted to IEC 63278-1:2023 (before IEC 63278-1 Draft July 2022 was the basis), (https://github.com/admin-shell-io/aas-specs/issues/365[#365]) also abbreviations partly adopted; changes:
** changed: asset
** changed: digital representation (example only)
** removed: ontology
** changed: service
** removed: smart manufacturing
** changed: Submodel
** changed: Submodel template
** changed: Submodel template element
** removed: technical functionality
* Update clause on matching algorithm for references (https://github.com/admin-shell-io/aas-specs/issues/350[#350])
** introduce equivalent matching and rename exact matching to value matching
** added notes

* Change File and Blob: attribute "contentType" now optional (https://github.com/admin-shell-io/aas-specs/issues/412[#412])
* remove AASd-120: idShort also allowed for elements within a SubmodelElementList (https://github.com/admin-shell-io/aas-specs/issues/432[#432])
* Relaxation of grammar for semantic IDs for metamodel elements in the context of data specifications
(https://github.com/admin-shell-io/aas-specs/issues/307[#307])
* Terms and Definitions adopted to IEC 63278-1:2023 (before IEC 63278-1 Draft July 2022 was the basis),
(https://github.com/admin-shell-io/aas-specs/issues/365[#365])
also abbreviations partly adopted; changes:
** changed: asset
** changed: digital representation (example only)
** removed: ontology
** changed: service
** removed: smart manufacturing
** changed: Submodel
** changed: Submodel template
** changed: Submodel template element
** removed: technical functionality
* Update clause on matching algorithm for references
(https://github.com/admin-shell-io/aas-specs/issues/350[#350])
** 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 (https://github.com/admin-shell-io/aas-specs/issues/366[#366])
* Transfer of clauses 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])
Expand All @@ -76,6 +83,9 @@ Major 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])
* 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
Expand All @@ -89,24 +99,33 @@ Minor Changes:
|===
|*Nc* |*V3.1 Change w.r.t. V3.0.1* |*Comment*


| {empty} | xref:spec-metamodel/referencing.adoc#KeyTypes[KeyTypes/ContainerElement] a| Add new value "ContainerElement" to enumeration KeyTypes, because AasSubmodelElements was extended
| {empty} | xref:spec-metamodel/referencing.adoc#AasReferableNonIdentifiables[AasReferableNonIdentifiables/ContainerElement] a| Add new value "ContainerElement" to enumeration AasReferableNonIdentifiables, because AasSubmodelElements was extended
| {empty} | xref:spec-metamodel/referencing.adoc#AasReferables[AasReferables/ContainerElement] a| Add new value "ContainerElement" to enumeration AasReferables, because AasSubmodelElements was extended
| {empty} | xref:spec-metamodel/referencing.adoc#AasSubmodelElements[AasSubmodelElements/ContainerElement] a| Add new value "ContainerElement" to enumeration AasSubmodelElements
| {empty} | xref:spec-metamodel/core.adoc#AssetKind[AssetKind] a| Add new value "Role" to enumeration AssetKind
| {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/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
| {empty} | xref:spec-metamodel/common.adoc#Referable[Referable/idShort] a| implicit change because constraint AASd-002 now also allows hyphen
| {empty} | xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement/first] a| now optional
| {empty} | xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement/second] a| now optional


|===

.New Elements in Metamodel
[cols="5%,41%,51%",options="header",]
|===
|{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/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
|===

.New, Changed or Removed Constraints
Expand Down
59 changes: 53 additions & 6 deletions documentation/IDTA-01001/modules/ROOT/pages/general.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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.
Expand Down
Loading

0 comments on commit f90b70d

Please sign in to comment.