Merge pull request #319 from eclipse-esmf/316-express-relationship-between-a-value-property-and-a-corresponding-unit-reference-property

Express relationship between a "value" Property and corresponding "unit reference" property

Author: Yauhenikapl

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

@@ -75,6 +75,16 @@
    ) .
 # end::timeseries-declaration[]
 
+# tag::quantity-declaration[]
+:Parameter a samm:Entity ;
+  samm:extends samm-e:Quantity ;
+  samm:properties (
+    [ samm:extends samm-e:value ; samm:characteristic :ParameterValueCharacteristic ]
+  ) .
+:ParameterValueCharacteristic a samm:Characteristic ;
+  samm:dataType xsd:integer .
+# end::quantity-declaration[]
+
 # tag::enumeration-simple-declaration-string[]
 :Status a samm-c:Enumeration ;
    samm:dataType xsd:string ;

documentation/modules/ROOT/pages/entities.adoc

@@ -73,3 +73,25 @@ Describes a resource with a relative or absolute location and a MIME type.
 | `samm-e:resource` | The location of the resource |  xref:characteristics.adoc#resource-path-characteristic[Resource Path]
 | `samm-e:mimeType` | The MIME type of the resource | xref:characteristics.adoc#mime-typecharacteristic[MIME Type]
 |===
+
+[[quantity-entity]]
+== Quantity Entity
+[.element-urn]
+--
+{samm-e}Quantity
+--
+
+The Quantity Entity is used to represent a numeric value along with its corresponding physical unit.
+It ensures that values are always explicitly associated with their units, providing clarity and consistency
+in data representation.
+
+This entity is particularly useful when working with dynamic units that are determined at runtime.
+
+See xref:modeling-guidelines.adoc#declaring-quantities[declaring quantities] for usage in an Aspect Model.
+
+[width="100%", options="header", cols="30,40,30"]
+|===
+| Property | Description | Characteristic
+| `samm-e:value` | The numeric value | This is an xref:modeling-guidelines.adoc#abstract-entities-with-abstract-properties[Abstract Property] without a Characteristic
+| `samm-e:unit` | The corresponding physical unit of the value | xref:characteristics.adoc#unit-reference-characteristic[Unit Reference]
+|===

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

@@ -376,6 +376,38 @@ related data is explicitly linked and contained in a single Collection. When mod
 two or more collections at root level which contain unrelated data, consider creating separate
 Aspects each containing a single Collection.
 
+[[declaring-quantities]]
+==== Declaring Quantities
+
+The `xref:characteristics.adoc#unit-reference-characteristic[UnitReference]` Characteristic is used
+to associate numeric values with their respective physical units in a structured and explicit way.
+The `Quantity` Entity is designed to represent such a pairing, ensuring that values are always
+interpreted correctly with their corresponding units.
+
+A `Quantity` is defined as an entity that contains a numeric `value` and a corresponding `unit`,
+both of which are essential for properly interpreting the data.
+The `xref:entities.adoc#quantity-entity[QuantityEntity]` is declared as an Abstract Entity,
+providing a standard way to associate measurements with units.
+
+To describe these semantics, the `Quantity` Entity defines the `value` Property as
+an `xref:modeling-guidelines.adoc#abstract-entities-with-abstract-properties[Abstract Property]`,
+meaning it does not have an inherent Characteristic and must be specialized based on the context.
+The `unit` Property is assigned the `xref:characteristics.adoc#unit-reference-characteristic[Unit Reference]`
+Characteristic, which ensures that it references a recognized unit of measurement.
+
+To define a Quantity for a specific domain, the user should instantiate an Entity that extends
+the Abstract `Quantity` Entity and provide a specialized Characteristic for the `value` Property,
+specifying its data type and semantics according to the domain's needs. For details on how to extend
+an Abstract Entity, please refer
+to the `xref:modeling-guidelines.adoc#declaring-abstract-entities[Declaring Abstract Entities]` section.
+
+Example:
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tag=quantity-declaration]
+----
+
 [[declaring-either]]
 ==== Declaring Either
 

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

@@ -0,0 +1,23 @@
+# Copyright (c) 2025 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 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 samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.2.0#> .
+
+samm-e:Quantity a samm:AbstractEntity ;
+   samm:preferredName "Quantity"@en ;
+   samm:description "A numeric value and the physical unit of the value."@en ;
+   samm:properties ( samm-e:value samm-e:unit ) .
+
+samm-e:unit a samm:Property ;
+   samm:characteristic samm-c:UnitReference .
+

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

@@ -16,18 +16,19 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.io.StringWriter;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Stream;
 
-import org.apache.jena.rdf.model.Model;
-
 import org.eclipse.esmf.samm.validation.ModelLoader;
 import org.eclipse.esmf.samm.validation.SemanticError;
 import org.eclipse.esmf.samm.validation.ValidationReport;
 import org.eclipse.esmf.samm.validation.Validator;
 
+import org.apache.jena.rdf.model.Model;
+
 public abstract class AbstractShapeTest {
    final static String TEST_NAMESPACE = "org.eclipse.esmf.test";
    final static String TEST_NAMESPACE_VERSION = "1.0.0";
@@ -134,7 +135,7 @@ protected static Stream<KnownVersion> versionsUpToIncluding1_0_0() {
          + "Property's '{$this}' Characteristic's dataType.";
 
    Model loadMetaModelDefinitions( final KnownVersion version ) {
-      return ModelLoader.createModel( List.of(
+      List<String> files = new ArrayList<>( List.of(
             "samm/meta-model/" + version.toVersionString() + "/aspect-meta-model-definitions.ttl",
             "samm/meta-model/" + version.toVersionString() + "/type-conversions.ttl",
             "samm/characteristic/" + version.toVersionString() + "/characteristic-definitions.ttl",
@@ -144,6 +145,12 @@ Model loadMetaModelDefinitions( final KnownVersion version ) {
             "samm/entity/" + version.toVersionString() + "/Point3d.ttl",
             "samm/unit/" + version.toVersionString() + "/units.ttl"
       ) );
+
+      if ( version.isNewerThan( KnownVersion.SAMM_2_1_0 ) ) {
+         files.add( "samm/entity/" + version.toVersionString() + "/Quantity.ttl" );
+      }
+
+      return ModelLoader.createModel( files );
    }
 
    protected void checkValidity( final String path, final String ttlDefinition, final KnownVersion testedVersion ) {

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

@@ -0,0 +1,13 @@
+package org.eclipse.esmf.samm;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+class QuantityTest extends AbstractShapeTest {
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_2_0" )
+   void testQuantityValidationEntity( final KnownVersion metaModelVersion ) {
+      checkValidity( "quantity", "QuantityTestEntity", metaModelVersion );
+   }
+}

esmf-semantic-aspect-meta-model/src/test/resources/samm_2_2_0/quantity/org.eclipse.esmf.test/1.0.0/QuantityTestEntity.ttl

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2025 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-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.2.0#> .
+@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.2.0#> .
+@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.2.0#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+:Parameter a samm:Entity ;
+   samm:extends samm-e:Quantity ;
+   samm:properties (
+      [ samm:extends samm-e:value ; samm:characteristic :ParameterValueCharacteristic ]
+   ) .
+
+:ParameterValueCharacteristic a samm:Characteristic ;
+   samm:dataType xsd:integer .