Skip to content

Commit 01dfcdc

Browse files
aniluedeaniluede
authored
Merge branch 'eclipse-esmf:main' into 309-task-enhance-best-practice-with-rule-for-how-to-write-a-good-description
2 parents 1fb2897 + 9e77424 commit 01dfcdc

File tree

23 files changed

+582
-58
lines changed

23 files changed

+582
-58
lines changed

‎documentation/antora.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ start_page: ROOT:index.adoc
55
nav:
66
- modules/ROOT/nav.adoc
77
- modules/appendix/nav.adoc
8+
- modules/release-notes/nav.adoc
89
- modules/legal/nav.adoc

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

Lines changed: 89 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,12 +70,21 @@
7070

7171
:MachineStateTimeSeriesEntity a samm:Entity ;
7272
samm:extends samm-e:TimeSeriesEntity ;
73-
samm:properties ( :machineState ) .
74-
75-
:machineState a samm:Property ;
76-
samm:characteristic :MachineState .
73+
samm:properties (
74+
[ samm:extends samm-e:value ; samm:characteristic :MachineState ]
75+
) .
7776
# end::timeseries-declaration[]
7877

78+
# tag::quantity-declaration[]
79+
:Parameter a samm:Entity ;
80+
samm:extends samm-e:Quantity ;
81+
samm:properties (
82+
[ samm:extends samm-e:value ; samm:characteristic :ParameterValueCharacteristic ]
83+
) .
84+
:ParameterValueCharacteristic a samm:Characteristic ;
85+
samm:dataType xsd:integer .
86+
# end::quantity-declaration[]
87+
7988
# tag::enumeration-simple-declaration-string[]
8089
:Status a samm-c:Enumeration ;
8190
samm:dataType xsd:string ;
@@ -100,6 +109,82 @@
100109
samm-c:values ( "2010-01-01"^^xsd:date "2012-05-07"^^xsd:date "2018-03-08"^^xsd:date ) .
101110
# end::enumeration-simple-declaration-date[]
102111

112+
# tag::value-declaration[]
113+
:GreenLight a samm:Value ;
114+
samm:value "green" ;
115+
samm:preferredName "Normal"@en ;
116+
samm:description "Indicates that the speed of position change is within specification."@en ;
117+
samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
118+
# end::value-declaration[]
119+
120+
# tag::value-in-example-value-additional[]
121+
:warningLevelProperty a samm:Property ;
122+
samm:exampleValue :GreenLight ;
123+
samm:characteristic [
124+
a samm:Characteristic ;
125+
samm:dataType xsd:string ;
126+
] .
127+
128+
:GreenLight a samm:Value ;
129+
samm:value "green" ;
130+
samm:preferredName "Normal"@en ;
131+
samm:description "Indicates that the speed of position change is within specification."@en ;
132+
samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
133+
# end::value-in-example-value-additional[]
134+
135+
# tag::value-in-example-value-anonymous[]
136+
:propertyWithExampleValue a samm:Property ;
137+
samm:exampleValue [
138+
a samm:Value ;
139+
samm:description "Some Description"@en ;
140+
samm:value 2 ;
141+
] ;
142+
samm:characteristic [
143+
a samm:Characteristic ;
144+
samm:dataType xsd:integer ;
145+
] .
146+
# end::value-in-example-value-anonymous[]
147+
148+
# tag::enumeration-value-type-is-value-reference[]
149+
:TrafficLight a samm-c:Enumeration ;
150+
samm:name "TrafficLight" ;
151+
samm:preferredName "Warning Level"@en ;
152+
samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
153+
samm:dataType xsd:string ;
154+
samm-c:values ( :GreenLight ) .
155+
156+
:GreenLight a samm:Value ;
157+
samm:value "green" ;
158+
samm:preferredName "Normal"@en ;
159+
samm:description "Indicates that the speed of position change is within specification."@en ;
160+
samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
161+
# end::enumeration-value-type-is-value-reference[]
162+
163+
# tag::enumeration-value-type-in-value-mixed-instance[]
164+
:TrafficLight a samm-c:Enumeration ;
165+
samm:name "TrafficLight" ;
166+
samm:preferredName "Warning Level"@en ;
167+
samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
168+
samm:dataType xsd:string ;
169+
samm-c:values (
170+
:GreenLight # A reference to named described scalar value
171+
"yellow" # A direct literal value
172+
[
173+
a samm:Value ; # An anonymous described scalar value with additional metadata
174+
samm:value "red" ;
175+
samm:preferredName "Critical Warning"@en ;
176+
samm:description "Indicates that the position change is outside the specification."@en
177+
]
178+
) .
179+
180+
:GreenLight a samm:Value ;
181+
samm:value "green" ;
182+
samm:preferredName "Normal"@en ;
183+
samm:description "Indicates that the speed of position change is within specification."@en ;
184+
samm:see <https://en.wikipedia.org/wiki/Traffic_light> .
185+
186+
# end::enumeration-value-type-in-value-mixed-instance[]
187+
103188
# tag::enumeration-complex-declaration[]
104189
:Results a samm-c:Enumeration ;
105190
samm:dataType :Result ;

‎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: 97 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -162,22 +162,30 @@ that all model elements have], Properties have the following attributes:
162162
| Attributes | Description | Required
163163
| `samm:characteristic` | The xref:characteristics.adoc#characteristics[Characteristic] describing
164164
this Property. | {ok}
165-
| `samm:exampleValue` | An exemplary value the Property can take on that helps to understand the
166-
intended meaning of the property better. This can only be set for Properties with scalar data types
167-
(e.g., `xsd:string` or `xsd:float`, but not Entities). The data type of the `samm:exampleValue` must
168-
be convertible to the effective data type of the Property's Characteristic. For example, if the
169-
Characteristic's `samm:dataType` is `xsd:int`, `xsd:short` is also a valid type for the
170-
`samm:exampleValue`. Refer to section xref:datatypes.adoc#implicit-conversions[Implicit Conversions]
165+
| `samm:exampleValue` | An exemplary value that the Property can take, helping to clarify the intended meaning of the Property.
166+
This attribute supports both scalar literal values (e.g., xsd:string, xsd:float), an anonymous described scalar value,
167+
and value references that point to example values (i.e., references to instances of xref:modeling-guidelines.adoc#value-type[samm:Value]).
168+
In either case, the data type of the `samm:exampleValue` must be convertible to the effective data type defined by the Property's Characteristic.
169+
For example, if the Characteristic's `samm:dataType`
170+
is `xsd:int`, a value with the type `xsd:short` is also acceptable. Refer to section xref:datatypes.adoc#implicit-conversions[Implicit Conversions]
171171
for more details. | {nok}
172172
|===
173173

174-
Example:
174+
Example with Literal type:
175175

176176
[source,turtle,subs="attributes+"]
177177
----
178178
include::example$aspect-sample.ttl[tags=property-declaration]
179179
----
180180

181+
Example with value reference type:
182+
183+
[source,turtle,subs="attributes+"]
184+
----
185+
include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
186+
----
187+
188+
181189
[[declaring-characteristics]]
182190
=== Declaring Characteristics
183191

@@ -304,6 +312,28 @@ Example with literal `xsd:date` values:
304312
include::example$aspect-sample.ttl[tags=enumeration-simple-declaration-date]
305313
----
306314

315+
[[enumeration-with-value-type-in-value]]
316+
Example Using Value in an Enumeration:
317+
318+
An Enumeration can include complex values to enrich the semantic description of the enumeration items.
319+
This is especially useful when you want to provide additional metadata—such as a preferred name, description,
320+
or external reference—for a specific value.
321+
322+
There are several ways to define values in an Enumeration:
323+
324+
- Value Reference example:
325+
[source,turtle,subs="attributes+"]
326+
----
327+
include::example$aspect-sample.ttl[tags=enumeration-value-type-is-value-reference]
328+
----
329+
330+
- Multiple (anonymous described scalar value and value reference) Value Definitions:
331+
[source,turtle,subs="attributes+"]
332+
----
333+
include::example$aspect-sample.ttl[tags=enumeration-value-type-in-value-mixed-instance]
334+
----
335+
336+
307337
[[enumeration-with-complex-value]]
308338
Example with complex values:
309339

@@ -376,6 +406,38 @@ related data is explicitly linked and contained in a single Collection. When mod
376406
two or more collections at root level which contain unrelated data, consider creating separate
377407
Aspects each containing a single Collection.
378408

409+
[[declaring-quantities]]
410+
==== Declaring Quantities
411+
412+
The `xref:characteristics.adoc#unit-reference-characteristic[UnitReference]` Characteristic is used
413+
to associate numeric values with their respective physical units in a structured and explicit way.
414+
The `Quantity` Entity is designed to represent such a pairing, ensuring that values are always
415+
interpreted correctly with their corresponding units.
416+
417+
A `Quantity` is defined as an entity that contains a numeric `value` and a corresponding `unit`,
418+
both of which are essential for properly interpreting the data.
419+
The `xref:entities.adoc#quantity-entity[QuantityEntity]` is declared as an Abstract Entity,
420+
providing a standard way to associate measurements with units.
421+
422+
To describe these semantics, the `Quantity` Entity defines the `value` Property as
423+
an `xref:modeling-guidelines.adoc#abstract-entities-with-abstract-properties[Abstract Property]`,
424+
meaning it does not have an inherent Characteristic and must be specialized based on the context.
425+
The `unit` Property is assigned the `xref:characteristics.adoc#unit-reference-characteristic[Unit Reference]`
426+
Characteristic, which ensures that it references a recognized unit of measurement.
427+
428+
To define a Quantity for a specific domain, the user should instantiate an Entity that extends
429+
the Abstract `Quantity` Entity and provide a specialized Characteristic for the `value` Property,
430+
specifying its data type and semantics according to the domain's needs. For details on how to extend
431+
an Abstract Entity, please refer
432+
to the `xref:modeling-guidelines.adoc#declaring-abstract-entities[Declaring Abstract Entities]` section.
433+
434+
Example:
435+
436+
[source,turtle,subs="attributes+"]
437+
----
438+
include::example$aspect-sample.ttl[tag=quantity-declaration]
439+
----
440+
379441
[[declaring-either]]
380442
==== Declaring Either
381443

@@ -710,6 +772,34 @@ for example:
710772
include::example$aspect-sample.ttl[tags=see-dontuse]
711773
----
712774

775+
[[value-type]]
776+
=== Declaring Value
777+
778+
The `samm:Value` type is designed to represent a value enriched with semantic metadata.
779+
It encapsulates the actual data (which can be a literal or a reference) along with additional descriptive information.
780+
This type is used to enhance clarity in Enumerations and Properties by allowing you to attach a human-readable label,
781+
a detailed description, and an external reference to the value.
782+
783+
[source,turtle,subs="attributes+"]
784+
----
785+
include::example$aspect-sample.ttl[tags=value-declaration]
786+
----
787+
788+
Also, as an ExampleValue in Property:
789+
790+
- Additional Value:
791+
[source,turtle,subs="attributes+"]
792+
----
793+
include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
794+
----
795+
796+
- Anonymous ExampleValue:
797+
[source,turtle,subs="attributes+"]
798+
----
799+
include::example$aspect-sample.ttl[tags=value-in-example-value-anonymous]
800+
----
801+
802+
713803
[[optional-properties]]
714804
=== Optional Properties
715805

‎documentation/modules/appendix/nav.adoc‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,5 @@ SPDX-License-Identifier: MPL-2.0
1111
.Appendix
1212
* xref:best-practices.adoc[Best Practices]
1313
* xref:model-evolution.adoc[Model Evolution]
14-
* xref:release-notes.adoc[Release Notes]
1514
* xref:unitcatalog.adoc[Unit Catalog]
1615
* xref:bibliography.adoc[Bibliography]

‎documentation/modules/release-notes/nav.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
////
2+
Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH
3+
4+
See the AUTHORS file(s) distributed with this work for additional information regarding authorship.
5+
6+
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
7+
If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/
8+
SPDX-License-Identifier: MPL-2.0
9+
////
10+
11+
* xref:release-notes.adoc[Release Notes]

documentation/modules/appendix/pages/release-notes.adoc renamed to documentation/modules/release-notes/pages/release-notes.adoc

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ on validation and documentation as follows:
2828
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/161[Issue on Github].
2929

3030
* Validation of
31-
xref:samm-specification:ROOT:characteristics#time-series-characteristic[samm-c:TimeSeries] was
31+
xref:ROOT:characteristics#time-series-characteristic[samm-c:TimeSeries] was
3232
improved: The referenced type is checked by the validation now.
3333
https://github.com/eclipse-esmf/esmf-sdk/issues/194[Issue on Github].
3434

@@ -50,23 +50,23 @@ https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/161[Issue
5050
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0005-rdf-vocabulary.md[Aspect Meta Model RDF Vocabulary]
5151
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0006-unit-catalog.md[Unit Catalog: Use UNECE Recommendation 20]
5252

53-
* Section on xref:samm-specification:ROOT:modeling-guidelines.adoc#declaring-events[Declaring
54-
Events] was added; wrong edges in the xref:samm-specification:ROOT:meta-model-elements.adoc[Meta
53+
* Section on xref:ROOT:modeling-guidelines.adoc#declaring-events[Declaring
54+
Events] was added; wrong edges in the xref:ROOT:meta-model-elements.adoc[Meta
5555
Model Elements overview diagram] were fixed.
5656
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/104[Issue on Github].
5757

58-
* xref:samm-specification:ROOT:modeling-guidelines.adoc#naming-rules[Naming convention] for Events
58+
* xref:ROOT:modeling-guidelines.adoc#naming-rules[Naming convention] for Events
5959
was clarified: Events should use UpperCamelCase, like Aspects, Entities, Constraints and
6060
Characteristics. https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/147[Issue on Github].
6161

62-
* Section on xref:samm-specification:appendix:model-evolution.adoc[Model Evolution] was added in
62+
* Section on xref:appendix:model-evolution.adoc[Model Evolution] was added in
6363
appendix. https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/82[Issue on
6464
Github].
6565

6666
* Reference to outdated terminology "leaf Characteristic" was fixed.
6767
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/pull/215[Issue on Github].
6868

69-
* Japanese sample text in xref:samm-specification:ROOT:datatypes.adoc[Data Types] was fixed.
69+
* Japanese sample text in xref:ROOT:datatypes.adoc[Data Types] was fixed.
7070
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/172[Issue on Github].
7171

7272
[[samm-2.1.0-others]]
@@ -104,19 +104,19 @@ re-released as Eclipse Semantic Modeling Framework (ESMF) Semantic Aspect Meta M
104104
of an element is the local name part of its URI, i.e., the part following the `#` symbol.
105105
* The meta model elements `Unit`, `QuantityKinds` and their corresponding attributes have been moved
106106
from the `unit` namespace to the `bamm` namespace. The unit namespace is now solely reserved for
107-
the units of the xref:samm-specification:appendix:unitcatalog.adoc#unit-catalog-units[unit
107+
the units of the xref:appendix:unitcatalog.adoc#unit-catalog-units[unit
108108
catalog] itself.
109109
* The
110110
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/src/main/resources/samm/unit/2.0.0/units.ttl[formal
111111
description (units.ttl)] of the units catalog is now automatically generated from its original
112-
source (see xref:samm-specification:ROOT:units.adoc[Units]) and the
112+
source (see xref:ROOT:units.adoc[Units]) and the
113113
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/esmf-samm-build-plugin/src/main/resources/custom-units.ttl[local adjustments].
114114
* The `localeCode` and `languageCode` attributes have been moved from the `bamm` namespace to the
115115
`bamm-c` namespace.
116116
* Shared model elements have been adjusted:
117-
** The xref:samm-specification:ROOT:entities.adoc#point-3d[Point3d Entity] has been changed to use
117+
** The xref:ROOT:entities.adoc#point-3d[Point3d Entity] has been changed to use
118118
Abstract Properties for its components;
119-
** The xref:samm-specification:ROOT:entities.adoc#time-series-entity[Time Series Entity] has been
119+
** The xref:ROOT:entities.adoc#time-series-entity[Time Series Entity] has been
120120
changed to use an Abstract Property for its `value` component
121121
* The attributes `bamm:properties`, `bamm:operations` and `bamm:events` on `bamm:Aspect` are now
122122
optional, i.e., they do not have to be added any more even when they are empty lists.

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -514,9 +514,10 @@ samm-c:EnumerationShape
514514
$this samm-c:values ?values .
515515
$this samm:dataType ?definedDataType .
516516
?values rdf:rest*/rdf:first ?item .
517-
bind( datatype( ?item ) as ?literalDataType ) .
518-
bind( strlen( str( ?literalDataType ) ) as ?literalDataTypeLength ) .
519-
filter( ( ?literalDataType != ?definedDataType ) && ( ?literalDataTypeLength > 0 ) ) .
517+
optional { ?item a samm:Value ; samm:value ?innerValue . }
518+
bind( coalesce( datatype(?innerValue), datatype(?item) ) AS ?literalDataType ) .
519+
filter( strlen(str(?literalDataType)) > 0 ) .
520+
filter( ?literalDataType != ?definedDataType ) .
520521
bind( 'ERR_WRONG_DATATYPE' as ?code )
521522
bind( ?item as ?highlight )
522523
}

0 commit comments

Comments
 (0)