Add new Value type

Author: Yauhenikapl

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

@@ -109,6 +109,79 @@
    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[]
+:ValueOne a samm:Value ;
+   samm:value 1;
+   samm:preferredName "ValueOne Preferred Name"@en ;
+   samm:description "The value one description"@en ;
+   samm:see <https://en.wikipedia.org/wiki/One> .
+# end::value-declaration[]
+
+# tag::value-in-example-value-additional[]
+:valueWithProperty a samm:Property ;
+   samm:exampleValue :ValueOne ;
+   samm:characteristic [
+      a samm:Characteristic ;
+      samm:dataType xsd:integer ;
+   ] .
+
+:ValueOne a samm:Value ;
+   samm:value 1;
+   samm:preferredName "ValueOne Preferred Name"@en ;
+   samm:description "The value one description"@en ;
+   samm:see <https://en.wikipedia.org/wiki/One> .
+# 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-in-value-single-instance[]
+:SomeValueEnum a samm-c:Enumeration ;
+   samm:name "SomeValueEnum" ;
+   samm:preferredName "Some Value Enum"@en ;
+   samm:description "An enumeration of integers"@en ;
+   samm:dataType xsd:integer ;
+   samm-c:values ( :ValueOne ) .
+
+:ValueOne a samm:Value ;
+   samm:value 1 ;
+   samm:preferredName "ValueOne Preferred Name"@en ;
+   samm:description "The value one description"@en ;
+   samm:see <https://en.wikipedia.org/wiki/One> .
+# end::enumeration-value-type-in-value-single-instance[]
+
+# tag::enumeration-value-type-in-value-mixed-instance[]
+:SomeValueEnum a samm-c:Enumeration ;
+   samm:name "SomeValueEnum" ;
+   samm:preferredName "Some Value Enum"@en ;
+   samm:description "An enumeration of integers"@en ;
+   samm:dataType xsd:integer ;
+   samm-c:values (
+      :ValueOne         # A reference to a globally defined samm:Value
+      2                 # A direct literal value
+      [
+        a samm:Value ;  # An inline complex value with additional metadata
+        samm:value 3
+      ]
+   ) .
+
+:ValueOne a samm:Value ;
+   samm:value 1 ;
+   samm:preferredName "ValueOne Preferred Name"@en ;
+   samm:description "The value one description"@en ;
+   samm:see <https://en.wikipedia.org/wiki/One> .
+# 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

@@ -163,21 +163,30 @@ that all model elements have], Properties have the following attributes:
 | `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]
+intended meaning of the property better. This attribute supports both scalar literal values
+(e.g., `xsd:string`, `xsd:float`) and entity-based example values (i.e., references to instances of
+xref:modeling-guidelines.adoc#value-type[samm:Value]
+enriched with semantic metadata). 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 entity-based type:
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
+----
+
+
 [[declaring-characteristics]]
 === Declaring Characteristics
 
@@ -304,6 +313,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:
+
+- Single Global Instance:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=enumeration-value-type-in-value-single-instance]
+----
+
+- Mixed 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 +773,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) and entity-based 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 0 ;
+    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";