Merge pull request #322 from eclipse-esmf/52-allow-description-of-enumeration-values

Add new Value type

Author: Yauhenikapl

documentation/modules/ROOT/examples/aspect-sample.ttl

@@ -109,6 +109,82 @@
    samm-c:values ( "2010-01-01"^^xsd:date "2012-05-07"^^xsd:date "2018-03-08"^^xsd:date ) .
 # end::enumeration-simple-declaration-date[]
 
+# tag::value-declaration[]
+:GreenLight a samm:Value ;
+   samm:value "green" ;
+   samm:preferredName "Normal"@en ;
+   samm:description "Indicates that the speed of position change is within specification."@en ;
+   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
+# end::value-declaration[]
+
+# tag::value-in-example-value-additional[]
+:warningLevelProperty a samm:Property ;
+   samm:exampleValue :GreenLight ;
+   samm:characteristic [
+      a samm:Characteristic ;
+      samm:dataType xsd:string ;
+   ] .
+
+:GreenLight a samm:Value ;
+   samm:value "green" ;
+   samm:preferredName "Normal"@en ;
+   samm:description "Indicates that the speed of position change is within specification."@en ;
+   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
+# end::value-in-example-value-additional[]
+
+# tag::value-in-example-value-anonymous[]
+:propertyWithExampleValue a samm:Property ;
+   samm:exampleValue [
+      a samm:Value ;
+      samm:description "Some Description"@en ;
+      samm:value 2 ;
+   ] ;
+   samm:characteristic [
+      a samm:Characteristic ;
+      samm:dataType xsd:integer ;
+   ] .
+# end::value-in-example-value-anonymous[]
+
+# tag::enumeration-value-type-is-value-reference[]
+:TrafficLight a samm-c:Enumeration ;
+   samm:name "TrafficLight" ;
+   samm:preferredName "Warning Level"@en ;
+   samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
+   samm:dataType xsd:string ;
+   samm-c:values ( :GreenLight ) .
+
+:GreenLight a samm:Value ;
+   samm:value "green" ;
+   samm:preferredName "Normal"@en ;
+   samm:description "Indicates that the speed of position change is within specification."@en ;
+   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
+# end::enumeration-value-type-is-value-reference[]
+
+# tag::enumeration-value-type-in-value-mixed-instance[]
+:TrafficLight a samm-c:Enumeration ;
+   samm:name "TrafficLight" ;
+   samm:preferredName "Warning Level"@en ;
+   samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
+   samm:dataType xsd:string ;
+   samm-c:values (
+      :GreenLight        # A reference to named described scalar value
+      "yellow"           # A direct literal value
+      [
+         a samm:Value ;  # An anonymous described scalar value with additional metadata
+         samm:value "red" ;
+         samm:preferredName "Critical Warning"@en ;
+         samm:description "Indicates that the position change is outside the specification."@en
+      ]
+   ) .
+
+:GreenLight a samm:Value ;
+   samm:value "green" ;
+   samm:preferredName "Normal"@en ;
+   samm:description "Indicates that the speed of position change is within specification."@en ;
+   samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
+
+# end::enumeration-value-type-in-value-mixed-instance[]
+
 # tag::enumeration-complex-declaration[]
 :Results a samm-c:Enumeration ;
    samm:dataType :Result ;

documentation/modules/ROOT/pages/modeling-guidelines.adoc

@@ -162,22 +162,30 @@ that all model elements have], Properties have the following attributes:
 | Attributes | Description | Required
 | `samm:characteristic` | The xref:characteristics.adoc#characteristics[Characteristic] describing
   this Property. | {ok}
-| `samm:exampleValue` | An exemplary value the Property can take on that helps to understand the
-intended meaning of the property better. This can only be set for Properties with scalar data types
-(e.g., `xsd:string` or `xsd:float`, but not Entities). The data type of the `samm:exampleValue` must
-be convertible to the effective data type of the Property's Characteristic. For example, if the
-Characteristic's `samm:dataType` is `xsd:int`, `xsd:short` is also a valid type for the
-`samm:exampleValue`. Refer to section xref:datatypes.adoc#implicit-conversions[Implicit Conversions]
+| `samm:exampleValue` | An exemplary value that the Property can take, helping to clarify the intended meaning of the Property.
+This attribute supports both scalar literal values (e.g., xsd:string, xsd:float), an anonymous described scalar value,
+and value references that point to example values (i.e., references to instances of xref:modeling-guidelines.adoc#value-type[samm:Value]).
+In either case, the data type of the `samm:exampleValue` must be convertible to the effective data type defined by the Property's Characteristic.
+For example, if the Characteristic's `samm:dataType`
+is `xsd:int`, a value with the type `xsd:short` is also acceptable. Refer to section xref:datatypes.adoc#implicit-conversions[Implicit Conversions]
 for more details. | {nok}
 |===
 
-Example:
+Example with Literal type:
 
 [source,turtle,subs="attributes+"]
 ----
 include::example$aspect-sample.ttl[tags=property-declaration]
 ----
 
+Example with value reference type:
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
+----
+
+
 [[declaring-characteristics]]
 === Declaring Characteristics
 
@@ -304,6 +312,28 @@ Example with literal `xsd:date` values:
 include::example$aspect-sample.ttl[tags=enumeration-simple-declaration-date]
 ----
 
+[[enumeration-with-value-type-in-value]]
+Example Using Value in an Enumeration:
+
+An Enumeration can include complex values to enrich the semantic description of the enumeration items.
+This is especially useful when you want to provide additional metadata—such as a preferred name, description,
+or external reference—for a specific value.
+
+There are several ways to define values in an Enumeration:
+
+- Value Reference example:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=enumeration-value-type-is-value-reference]
+----
+
+- Multiple (anonymous described scalar value and value reference) Value Definitions:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=enumeration-value-type-in-value-mixed-instance]
+----
+
+
 [[enumeration-with-complex-value]]
 Example with complex values:
 
@@ -742,6 +772,34 @@ for example:
 include::example$aspect-sample.ttl[tags=see-dontuse]
 ----
 
+[[value-type]]
+=== Declaring Value
+
+The `samm:Value` type is designed to represent a value enriched with semantic metadata.
+It encapsulates the actual data (which can be a literal or a reference) along with additional descriptive information.
+This type is used to enhance clarity in Enumerations and Properties by allowing you to attach a human-readable label,
+a detailed description, and an external reference to the value.
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=value-declaration]
+----
+
+Also, as an ExampleValue in Property:
+
+ - Additional Value:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
+----
+
+ - Anonymous ExampleValue:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=value-in-example-value-anonymous]
+----
+
+
 [[optional-properties]]
 === Optional Properties
 

esmf-semantic-aspect-meta-model/src/main/resources/samm/characteristic/2.2.0/characteristic-shapes.ttl

@@ -514,9 +514,10 @@ samm-c:EnumerationShape
              $this samm-c:values ?values .
              $this samm:dataType ?definedDataType .
              ?values rdf:rest*/rdf:first ?item .
-             bind( datatype( ?item ) as ?literalDataType ) .
-             bind( strlen( str( ?literalDataType ) ) as ?literalDataTypeLength ) .
-             filter( ( ?literalDataType != ?definedDataType ) && ( ?literalDataTypeLength > 0 ) ) .
+             optional { ?item a samm:Value ; samm:value ?innerValue . }
+             bind( coalesce( datatype(?innerValue), datatype(?item) ) AS ?literalDataType ) .
+             filter( strlen(str(?literalDataType)) > 0 ) .
+             filter( ?literalDataType != ?definedDataType ) .
              bind( 'ERR_WRONG_DATATYPE' as ?code )
              bind( ?item as ?highlight )
            }

esmf-semantic-aspect-meta-model/src/main/resources/samm/meta-model/2.2.0/aspect-meta-model-definitions.ttl

@@ -77,6 +77,10 @@ samm:Namespace rdfs:subClassOf mmm:NamedConcept ;
    rdfs:label "Namespace" ;
    rdfs:comment "A Namespace can provide a human-readable name and a description for namespaces." .
 
+samm:Value rdfs:subClassOf mmm:ConceptWithProperties ;
+   rdfs:label: "Value" ;
+   rdfs:comment "A type is designed to represent a value enriched with semantic metadata.".
+
 # Meta meta model attributes used in Shapes
 mmm:listType a rdf:Property ;
    rdfs:label "listType" ;
@@ -152,7 +156,7 @@ samm:parameters a mmm:Attribute ;
 
 samm:exampleValue a mmm:Attribute ;
    rdfs:label "exampleValue" ;
-   rdfs:comment "An exemplary value the Property can take on that helps to understand the intended meaning of the property better. This can only be set for Properties with scalar data types (e.g. xsd:string or xsd:float, but not Entities). The data type of the samm:exampleValue must be convertable to the effective data type of the Property’s Characteristic." ;
+   rdfs:comment "An exemplary value the Property can take on that helps to understand the intended meaning of the property better. This attribute supports both scalar literal values (e.g., xsd:string or xsd:float), an anonymous described scalar value and value references example values (i.e., references to instances of samm:Value enriched with semantic metadata). The data type of the samm:exampleValue must be convertable to the effective data type of the Property’s Characteristic." ;
    rdfs:domain samm:Property ;
    rdfs:range rdfs:Resource .
 

esmf-semantic-aspect-meta-model/src/main/resources/samm/meta-model/2.2.0/aspect-meta-model-shapes.ttl

@@ -290,24 +290,24 @@ samm:PropertyShape
       sh:minCount 1 ;
       sh:maxCount 1 ;
       sh:class samm:Characteristic ;
-      sh:maxCount 1 ;
       sh:name "characteristic" ;
       sh:description "The Characteristic describing the semantics of the Property." ;
    ] ;
    sh:property [
       sh:order 4 ;
       sh:path samm:exampleValue ;
-      sh:nodeKind sh:Literal ;
       sh:sparql [
          a sh:SPARQLConstraint ;
          sh:message "The datatype '{?value}' of the exampleValue neither matches nor can be cast to the Property's '{$this}' Characteristic's dataType." ;
          sh:prefixes samm:prefixDeclarations ;
          sh:select """
-            select $this ?value ?code ?highlight
+            select $this ?value ?exampleValue ?providedType ?characteristicDataType ?code ?highlight
             where {
                $this samm:exampleValue ?exampleValue .
                $this samm:characteristic/samm-c:baseCharacteristic*/samm:dataType ?characteristicDataType .
-               bind( datatype( ?exampleValue ) as ?providedType )
+               optional { ?exampleValue a samm:Value ; samm:value ?innerValue . }
+               bind( coalesce(?innerValue, ?exampleValue) as ?actualValue )
+               bind( datatype(?actualValue) as ?providedType )
                filter( ?providedType not in (
                   xsd:string,
                   xsd:boolean,
@@ -374,8 +374,10 @@ samm:PropertyShape
          select $this ?exampleValue ?code
             where {
                $this samm:exampleValue ?exampleValue .
-               bind( datatype( ?exampleValue ) as ?providedType )
-               filter ( ?providedType = xsd:boolean && ( str( ?exampleValue ) != "true" && str( ?exampleValue ) != "false" ) )
+               optional { ?exampleValue a samm:Value ; samm:value ?innerValue . }
+               bind( coalesce(?innerValue, ?exampleValue) as ?actualValue )
+               bind( datatype(?actualValue) as ?providedType )
+               filter ( ?providedType = xsd:boolean && ( str(?actualValue) != "true" && str(?actualValue) != "false" ) )
                bind('ERR_EXAMPLE_VALUE_NOT_ALLOWED' AS ?code)
             }
          """
@@ -1024,3 +1026,14 @@ samm:ConstrainListTypeUsageShape
          """
       ]
    ] .
+
+samm:ValueShape
+  a sh:NodeShape ;
+  sh:targetClass samm:Value ;
+  sh:property [
+    sh:path samm:value ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:name "value" ;
+    sh:description "A single constant value or link to another resource." ;
+  ] .

esmf-semantic-aspect-meta-model/src/test/java/org/eclipse/esmf/samm/AbstractShapeTest.java

@@ -68,6 +68,10 @@ protected static Stream<KnownVersion> versionsUpToIncluding1_0_0() {
       return versionsUpToIncluding( KnownVersion.SAMM_1_0_0 );
    }
 
+   protected static Stream<KnownVersion> versionsUpToIncluding2_1_0() {
+      return versionsUpToIncluding( KnownVersion.SAMM_2_1_0 );
+   }
+
    final String violationUrn = "http://www.w3.org/ns/shacl#Violation";
    final String warningUrn = "http://www.w3.org/ns/shacl#Warning";
 

esmf-semantic-aspect-meta-model/src/test/java/org/eclipse/esmf/samm/EnumerationShapeTest.java

@@ -18,17 +18,17 @@
 
 import org.eclipse.esmf.samm.validation.SemanticError;
 
-public class EnumerationShapeTest extends AbstractShapeTest {
+class EnumerationShapeTest extends AbstractShapeTest {
 
    @ParameterizedTest
    @MethodSource( value = "allVersions" )
-   public void testEnumerationValidationExpectSuccess( final KnownVersion metaModelVersion ) {
+   void testEnumerationValidationExpectSuccess( final KnownVersion metaModelVersion ) {
       checkValidity( "enumeration-shape", "TestEnumeration", metaModelVersion );
    }
 
    @ParameterizedTest
    @MethodSource( value = "allVersions" )
-   public void testMissingRequiredPropertiesExpectFailure2( final KnownVersion metaModelVersion ) {
+   void testMissingRequiredPropertiesExpectFailure2( final KnownVersion metaModelVersion ) {
       final SammUrns sammUrns = new SammUrns( metaModelVersion );
       final String focusNode = testNamespacePrefix + "TestEnumerationMissingRequiredProperties";
 
@@ -42,7 +42,7 @@ public void testMissingRequiredPropertiesExpectFailure2( final KnownVersion meta
 
    @ParameterizedTest
    @MethodSource( value = "allVersions" )
-   public void testValueIsNotOfDefinedDataTypeExpectFailure( final KnownVersion metaModelVersion ) {
+   void testValueIsNotOfDefinedDataTypeExpectFailure( final KnownVersion metaModelVersion ) {
       final SammUrns sammUrns = new SammUrns( metaModelVersion );
       final String focusNode = testNamespacePrefix + "TestEnumerationValueIsNotOfDefinedDataType";
 
@@ -56,7 +56,7 @@ public void testValueIsNotOfDefinedDataTypeExpectFailure( final KnownVersion met
 
    @ParameterizedTest
    @MethodSource( value = "allVersions" )
-   public void testValueIsNotALiteralTypeExpectFailure( final KnownVersion metaModelVersion ) {
+   void testValueIsNotALiteralTypeExpectFailure( final KnownVersion metaModelVersion ) {
       final SammUrns sammUrns = new SammUrns( metaModelVersion );
       final String focusNode = testNamespacePrefix + "TestEnumerationValueIsNotALiteralType";