Skip to content

Commit 3d13af3

Browse files
YauhenikaplYauhenikapl
committed
Express relationship between a "value" Property and corresponding "unit reference" property
1 parent 66bb29f commit 3d13af3

File tree

6 files changed

+165
-0
lines changed

6 files changed

+165
-0
lines changed

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,34 @@
7575
) .
7676
# end::timeseries-declaration[]
7777

78+
# tag::quantity-declaration[]
79+
:Parameter a samm:Entity ;
80+
samm:extends samm-e:Quantity ;
81+
samm:properties ( :parameterValue :parameterUnit ) .
82+
83+
:parameterValue a samm:Property ;
84+
samm:characteristic :ParameterValueCharacteristic .
85+
86+
:ParameterValueCharacteristic a samm:Characteristic ;
87+
samm:dataType xsd:integer .
88+
89+
:parameterUnit a samm:Property ;
90+
samm:characteristic samm-c:UnitReference .
91+
92+
:ProcessParameterDetails a samm:Entity ;
93+
samm:properties ( :parameter ) .
94+
95+
:parameter a samm:Property ;
96+
samm:characteristic [
97+
a samm-c:SingleEntity ;
98+
samm:dataType :Parameter ;
99+
] .
100+
101+
:TestMeasurement a :Parameter ;
102+
:parameterValue 75 ;
103+
:parameterUnit unit:kilogram .
104+
# end::quantity-declaration[]
105+
78106
# tag::enumeration-simple-declaration-string[]
79107
:Status a samm-c:Enumeration ;
80108
samm:dataType xsd:string ;

‎documentation/modules/ROOT/pages/entities.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,25 @@ Describes a resource with a relative or absolute location and a MIME type.
7373
| `samm-e:resource` | The location of the resource | xref:characteristics.adoc#resource-path-characteristic[Resource Path]
7474
| `samm-e:mimeType` | The MIME type of the resource | xref:characteristics.adoc#mime-typecharacteristic[MIME Type]
7575
|===
76+
77+
[[quantity-entity]]
78+
== Quantity Entity
79+
[.element-urn]
80+
--
81+
{samm-e}Quantity
82+
--
83+
84+
The Quantity Entity is used to represent a numeric value along with its corresponding physical unit.
85+
It ensures that values are always explicitly associated with their units, providing clarity and consistency
86+
in data representation.
87+
88+
This entity is particularly useful when working with dynamic units that are determined at runtime.
89+
90+
See xref:modeling-guidelines.adoc#declaring-quantities[declaring quantities] for usage in an Aspect Model.
91+
92+
[width="100%", options="header", cols="30,40,30"]
93+
|===
94+
| Property | Description | Characteristic
95+
| `samm-e:value` | The numeric value | This is an xref:modeling-guidelines.adoc#abstract-entities-with-abstract-properties[Abstract Property] without a Characteristic
96+
| `samm-e:unit` | The corresponding physical unit of the value | xref:characteristics.adoc#unit-reference-characteristic[Unit Reference]
97+
|===

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,6 +376,43 @@ related data is explicitly linked and contained in a single Collection. When mod
376376
two or more collections at root level which contain unrelated data, consider creating separate
377377
Aspects each containing a single Collection.
378378

379+
[[declaring-quantities]]
380+
==== Declaring Quantities
381+
382+
The `xref:characteristics.adoc#unit-reference-characteristic[UnitReference]` Characteristic is used
383+
to associate numeric values with their respective physical units in a structured and explicit way.
384+
The `Quantity` Entity is designed to represent such a pairing, ensuring that values are always
385+
interpreted correctly with their corresponding units.
386+
387+
A `Quantity` is defined as an entity that contains a numeric `value` and a corresponding `unit`,
388+
both of which are essential for properly interpreting the data.
389+
The `xref:entities.adoc#quantity-entity[QuantityEntity]` is declared as an Abstract Entity,
390+
providing a standard way to associate measurements with units.
391+
392+
To describe these semantics, the `Quantity` Entity defines the `value` Property as
393+
an `xref:modeling-guidelines.adoc#abstract-entities-with-abstract-properties[Abstract Property]`,
394+
meaning it does not have an inherent Characteristic and must be specialized based on the context.
395+
The `unit` Property is assigned the `xref:characteristics.adoc#unit-reference-characteristic[Unit Reference]`
396+
Characteristic, which ensures that it references a recognized unit of measurement.
397+
398+
To define a Quantity for a specific domain, the user should instantiate an Entity that extends
399+
the Abstract `Quantity` Entity and provide a specialized Characteristic for the `value` Property,
400+
specifying its data type and semantics according to the domain's needs. For details on how to extend
401+
an Abstract Entity, please refer
402+
to the `xref:modeling-guidelines.adoc#declaring-abstract-entities[Declaring Abstract Entities]` section.
403+
404+
Example:
405+
406+
[source,turtle,subs="attributes+"]
407+
----
408+
include::example$aspect-sample.ttl[tag=quantity-declaration]
409+
----
410+
411+
TIP: When defining measurements, ensure that both `value` and `unit` properties are always included
412+
together to maintain semantic integrity. If multiple units are relevant for a given aspect, consider
413+
defining explicit conversions or constraints to prevent ambiguity in data interpretation.
414+
415+
379416
[[declaring-either]]
380417
==== Declaring Either
381418

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH
2+
#
3+
# See the AUTHORS file(s) distributed with this work for additional
4+
# information regarding authorship.
5+
#
6+
# This Source Code Form is subject to the terms of the Mozilla Public
7+
# License, v. 2.0. If a copy of the MPL was not distributed with this
8+
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
9+
#
10+
# SPDX-License-Identifier: MPL-2.0
11+
12+
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.2.0#> .
13+
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.2.0#> .
14+
@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.2.0#> .
15+
16+
samm-e:Quantity a samm:AbstractEntity ;
17+
samm:description "A numeric value and the physical unit of the value"@en ;
18+
samm:properties ( samm-e:value samm-e:unit ) .
19+
20+
samm-e:unit a samm:Property ;
21+
samm:characteristic samm-c:UnitReference .

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package org.eclipse.esmf.samm;
2+
3+
import org.junit.jupiter.params.ParameterizedTest;
4+
import org.junit.jupiter.params.provider.MethodSource;
5+
6+
class QuantityTest extends AbstractShapeTest {
7+
8+
@ParameterizedTest
9+
@MethodSource( value = "versionsStartingWith2_2_0" )
10+
void testQuantityValidationEntity( final KnownVersion metaModelVersion ) {
11+
checkValidity( "quantity", "QuantityTestEntity", metaModelVersion );
12+
}
13+
}

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
#
2+
# Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH
3+
#
4+
# See the AUTHORS file(s) distributed with this work for additional
5+
# information regarding authorship.
6+
#
7+
# This Source Code Form is subject to the terms of the Mozilla Public
8+
# License, v. 2.0. If a copy of the MPL was not distributed with this
9+
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
10+
#
11+
# SPDX-License-Identifier: MPL-2.0
12+
#
13+
@prefix : <urn:samm:org.eclipse.esmf.samm.test:1.0.0#> .
14+
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.2.0#> .
15+
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.2.0#> .
16+
@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.2.0#> .
17+
@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.2.0#> .
18+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
19+
20+
:Parameter a samm:Entity ;
21+
samm:extends samm-e:Quantity ;
22+
samm:properties ( :parameterValue :parameterUnit ) .
23+
24+
:parameterValue a samm:Property ;
25+
samm:characteristic :ParameterValueCharacteristic .
26+
27+
:ParameterValueCharacteristic a samm:Characteristic ;
28+
samm:dataType xsd:integer .
29+
30+
:parameterUnit a samm:Property ;
31+
samm:characteristic samm-c:UnitReference .
32+
33+
:ProcessParameterDetails a samm:Entity ;
34+
samm:properties ( :parameter ) .
35+
36+
:parameter a samm:Property ;
37+
samm:characteristic [
38+
a samm-c:SingleEntity ;
39+
samm:dataType :Parameter ;
40+
] .
41+
42+
:TestMeasurement a :Parameter ;
43+
:parameterValue 75 ;
44+
:parameterUnit unit:kilogram .

0 commit comments

Comments
 (0)