Merge pull request #302 from eclipse-esmf/138-describe-semantics-of-reference-submodel-element

Yauhenikapl · web-flow · commit b90b1d7f06df · 2024-07-01T08:36:52.000+03:00
Add Reference Characteristic definition and shape.
diff --git a/documentation/modules/ROOT/diagrams/characteristics-instances.dot b/documentation/modules/ROOT/diagrams/characteristics-instances.dot
@@ -131,6 +131,18 @@ digraph characteristics_instances {
     </table>>
   ]
 
+  Reference [
+    label =
+    <<table border="0" cellpadding="5" cellspacing="0" cellborder="1" href="../characteristics.html#reference-characteristic">
+    <tr>
+      <td><u>Reference</u></td>
+    </tr>
+    <tr>
+      <td>dataType : xsd:anyURI</td>
+    </tr>
+    </table>>
+  ]
+
   MultiLanguageText [
     label =
     <<table border="0" cellpadding="5" cellspacing="0" cellborder="1" href="../characteristics.html#multi-language-text-characteristic">
@@ -181,6 +193,7 @@ digraph characteristics_instances {
   { rank = same;
     Timestamp;
     UnitReference;
+    Reference;
     ResourcePath;
     MimeType;
     Boolean;
@@ -192,12 +205,14 @@ digraph characteristics_instances {
   Locale -> Characteristic
   Language -> Characteristic
   UnitReference -> Characteristic
+  Reference -> Characteristic
   MultiLanguageText -> Characteristic
   ResourcePath -> Characteristic
   MimeType -> Characteristic
 
   Timestamp -> Text [style=invis]
   UnitReference -> MultiLanguageText [style=invis]
+  Reference -> MultiLanguageText [style=invis]
   ResourcePath -> Locale[style=invis]
   MimeType -> Language [style=invis]
   Boolean -> Language [style=invis]
diff --git a/documentation/modules/ROOT/examples/reference-declaration.ttl b/documentation/modules/ROOT/examples/reference-declaration.ttl
@@ -0,0 +1,22 @@
+#
+# Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
+#
+# See the AUTHORS file(s) distributed with this work for additional
+# information regarding authorship.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+@prefix : <urn:samm:org.eclipse.esmf.samm.test:1.0.0#> .
+@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.2.0#> .
+@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.2.0#> .
+@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.2.0#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# tag::content[]
+:TestProperty a samm:Property ;
+    samm:characteristic samm-c:Reference .
+# end::content[]
diff --git a/documentation/modules/ROOT/images/characteristics-instances.svg b/documentation/modules/ROOT/images/characteristics-instances.svg
diff --git a/documentation/modules/ROOT/pages/characteristics.adoc b/documentation/modules/ROOT/pages/characteristics.adoc
@@ -447,6 +447,21 @@ See xref:modeling-guidelines.adoc#using-unit-reference[Using Unit Reference] for
 
 dataType: `xref:datatypes.adoc#data-types[samm:curie]`
 
+[[reference-characteristic]]
+=== Reference
+[.element-urn]
+--
+{samm-c}Reference
+--
+
+A reference is a value that refers to a concept such as a resource or a model element.
+It can be a xref:namespaces.adoc#meta-model-identifiers-definition[SAMM meta model identifier],
+a xref:namespaces.adoc#aspect-model-element-identifiers-definition[SAMM model element identifier],
+a resource URI, or a URI referring to a concept in a different formalism or vocabulary.
+The value follows the same rules as a xref:modeling-guidelines.adoc#adding-external-references[samm:see reference].
+
+See xref:modeling-guidelines.adoc#declaring-reference[declaring Reference] for usage in an Aspect Model.
+
 [[constraints]]
 == Constraints
 
diff --git a/documentation/modules/ROOT/pages/modeling-guidelines.adoc b/documentation/modules/ROOT/pages/modeling-guidelines.adoc
@@ -445,6 +445,21 @@ deconstruction rule corresponds with the named fields; secondly, it is used for
 check if it can be deconstructed using the deconstruction rule and reconstructed using the elements,
 i.e., that the deconstruction rule actually does what the model author intended.
 
+[[declaring-reference]]
+==== Declaring Reference
+
+The xref:characteristics.adoc#reference-characteristic[Reference] Characteristic is intended to be used
+for scenarios where a reference to a concept external to the Aspect Model is required, but the value of the
+reference (i.e., the identifier of the linked concept) is not known at modeling time yet. Other than that,
+it is conceptually similar to a xref:modeling-guidelines.adoc#adding-external-references[samm:see reference].
+
+:attribute-missing: skip
+[source,turtle,subs="attributes+"]
+----
+include::example$reference-declaration.ttl[tags=content]
+----
+:attribute-missing: warn
+
 [[using-unit-reference]]
 ==== Using Unit Reference
 
diff --git a/esmf-semantic-aspect-meta-model/src/main/resources/samm/characteristic/2.2.0/characteristic-instances.ttl b/esmf-semantic-aspect-meta-model/src/main/resources/samm/characteristic/2.2.0/characteristic-instances.ttl
@@ -59,3 +59,8 @@ samm-c:MimeType a samm:Characteristic ;
    samm:description """A MIME type as defined in RFC 2046, for example "application/pdf"."""@en ;
    samm:dataType xsd:string .
 
+samm-c:Reference a samm:Characteristic ;
+    samm:preferredName "Reference"@en ;
+    samm:description "Defines a unique type of Property. This reference can either be a global reference, such as a URN, or it can refer to a Property of another aspect within a different twin."@en ;
+    samm:dataType xsd:anyURI .
+
diff --git a/esmf-semantic-aspect-meta-model/src/test/java/org/eclipse/esmf/samm/ReferenceShapeTest.java b/esmf-semantic-aspect-meta-model/src/test/java/org/eclipse/esmf/samm/ReferenceShapeTest.java
@@ -0,0 +1,13 @@
+package org.eclipse.esmf.samm;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+class ReferenceShapeTest extends AbstractShapeTest {
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_2_0" )
+   void testValidReferenceExpectSuccess( final KnownVersion metaModelVersion ) {
+      checkValidity( "reference-shape", "TestReference", metaModelVersion );
+   }
+}
diff --git a/esmf-semantic-aspect-meta-model/src/test/resources/samm_2_2_0/reference-shape/org.eclipse.esmf.test/1.0.0/TestReference.ttl b/esmf-semantic-aspect-meta-model/src/test/resources/samm_2_2_0/reference-shape/org.eclipse.esmf.test/1.0.0/TestReference.ttl
@@ -0,0 +1,20 @@
+#
+# Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
+#
+# See the AUTHORS file(s) distributed with this work for additional
+# information regarding authorship.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+@prefix : <urn:samm:org.eclipse.esmf.samm.test:1.0.0#> .
+@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.2.0#> .
+@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.2.0#> .
+@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.2.0#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+:TestProperty a samm:Property ;
+    samm:characteristic samm-c:Reference .
