Merge branch 'main' into chris-volk-patch-1

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,15 +7,14 @@ assignees: ''
 
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+**How: List of performed steps**
 
-**Where**
-Indicate the location of the bug (e.g., in which document, section and paragraph you found the bug).
+**What: Actual result vs expected result**
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**Where: (e.g. component, version, url, your system info)**
 
+**Input (files/screenshots)**
 
-**Additional context**
-Add any other context about the problem here.
+**Output (files/screenshots)**
+
+**Additional context (e.g. references)**

documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl

@@ -0,0 +1,49 @@
+# Copyright (c) 2024 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:com.mycompany.myapplication:1.0.0#> .
+@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .
+@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#> .
+@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.1.0#> .
+@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.1.0#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+:AspectWithEither a samm:Aspect ;
+  samm:properties ( :speedProperty ) ;
+  samm:operations ( ) .
+
+# tag::aspect-with-double-either-characteristic[]
+:speedProperty a samm:Property ;
+  samm:characteristic :Result .
+
+:Result a samm-c:Either ;
+  samm:description "The result is either an error or a SpeedValue"@en ;
+  samm-c:left :Error ;
+  samm-c:right :SpeedValue .
+
+:Error a samm-c:Either ;
+  samm:description """An error can be either a simple text,  or a complex object with separate errorCode and errorDescription"""@en ;
+  samm-c:left samm-c:Text ;
+  samm-c:right :ErrorMessage .
+
+:SpeedValue a samm-c:Quantifiable ;
+  samm:dataType xsd:integer .
+
+:ErrorMessage a samm:Characteristic ;
+  samm:dataType :ErrorEntity .
+
+:ErrorEntity a samm:Entity ;
+  samm:properties ( :errorCode :errorDescription ) .
+
+:errorCode a samm:Property ;
+  samm:characteristic samm-c:Text .
+
+:errorDescription a samm:Property ;
+  samm:characteristic samm-c:Text .
+
+# end::aspect-with-double-either-characteristic[]

documentation/modules/ROOT/examples/either-declaration.ttl

@@ -13,22 +13,26 @@
 @prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.0.0#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 
+:AspectWithEither a samm:Aspect ;
+  samm:properties ( :speedProperty ) ;
+  samm:operations ( ) .
+
 # tag::either-declaration[]
+:speedProperty a samm:Property ;
+  samm:characteristic :Result .
+
 :Result a samm-c:Either ;
-   samm-c:left :ErrorCode ;
-   samm-c:right :SuccessCode .
+  samm-c:left :ErrorMessage ;
+  samm-c:right :SpeedValue .
 
-:ErrorCode a samm-c:SingleEntity ;
-   samm:dataType :ErrorEntity .
+:ErrorMessage a samm-c:SingleEntity ;
+  samm:dataType :ErrorEntity .
 
-:SuccessCode a samm-c:SingleEntity ;
-   samm:dataType :SuccessEntity .
+:SpeedValue a samm-c:Quantifiable ;
+  samm:dataType xsd:integer .
 
 :ErrorEntity a samm:Entity ;
    samm:properties ( :errorCode :errorDescription ) .
-
-:SuccessEntity a samm:Entity ;
-   samm:properties ( :status ) .
 # end::either-declaration[]
 
 # To make :Result valid

documentation/modules/ROOT/pages/characteristics.adoc

@@ -592,6 +592,11 @@ At least one of `samm-c:maxValue` or `samm-c:minValue` must be present in a Leng
 | `samm-c:minValue` | The minimum length. Must be given as `xsd:nonNegativeInteger`. | {nok}
 |===
 
+IMPORTANT: When using the `samm-c:minValue` parameter in Length Constraint, it is crucial to consider the following:
+Creating a Model with a <<set-characteristic>>/<<sorted-set-characteristic>> based on a finite Base Characteristic (<<boolean-characteristic>> or <<enumeration-characteristic>>)
+and adding Length Constraint, the `samm-c:minValue` must not exceed the total number of elements in the Base Characteristic.
+Models with such conditions are not recognized as invalid, but no valid payloads can exist for them.
+
 [[regular-expression-constraint]]
 === Regular Expression Constraint
 [.element-urn]

documentation/modules/ROOT/pages/datatypes.adoc

@@ -69,7 +69,7 @@ definition in the respective standards and an informative description of their v
 .12+| Limited-range integer numbers
 | `https://www.w3.org/TR/xmlschema11-2/#byte[xsd:byte]` | -128…+127 (8 bit) | -1, 0, 127 | {nok}
 | `https://www.w3.org/TR/xmlschema11-2/#short[xsd:short]` | -32768…+32767 (16 bit) | -1, 0, 32767 | {nok}
-| `https://www.w3.org/TR/xmlschema11-2/#int[xsd:int]` | 2147483648…+2147483647 (32 bit) | -1, 0, 2147483647 | {nok}
+| `https://www.w3.org/TR/xmlschema11-2/#int[xsd:int]` | -2147483648…+2147483647 (32 bit) | -1, 0, 2147483647 | {nok}
 | `https://www.w3.org/TR/xmlschema11-2/#long[xsd:long]` | -9223372036854775808…+9223372036854775807 (64 bit) | -1, 0, 9223372036854775807 | {nok}
 | `https://www.w3.org/TR/xmlschema11-2/#unsignedByte[xsd:unsignedByte]` | 0…255 (8 bit) | 0, 1, 255 | {nok}
 | `https://www.w3.org/TR/xmlschema11-2/#unsignedShort[xsd:unsignedShort]` | 0…65535 (16 bit) | 0, 1, 65535 | {nok}
@@ -95,6 +95,25 @@ unsuitable in Aspect Models and _should not_ be used:
 `xsd:QName`, `xsd:ENTITY`, `xsd:ID`, `xsd:IDREF`, `xsd:NOTATION`, `xsd:IDREFS`, `xsd:ENTITIES`,
 `xsd:NMTOKENS`, `rdf:HTML` and `rdf:XMLLiteral`.
 
+[[samm-curie]]
+== Value range for `samm:curie` values
+
+Values with the type of `samm:curie` are interpreted in the context of the Aspect Model that
+describes the Aspect. The prefix part of their value therefore refers to the RDF prefixes as defined
+in the Aspect Model. Aspect Models do not use the https://www.w3.org/TR/turtle/#relative-iri[@base
+or BASE] directive in RDF/Turtle, so values with `samm:curie` type must always contain a colon `:`
+to delimit the (possibly) empty prefix part from the local name.
+
+.Allowed `samm:curie` values
+[options="header"]
+|===
+| Example Curie value | Allowed | Interpreted as URI
+| `unit:hectopascal` | {ok} | `{unit}hectopascal`
+| `xsd:string` | {ok} | `\http://www.w3.org/2001/XMLSchema#string`
+| `:myProperty` | {ok} | Depends on the Aspect Model's `@prefix :` definition
+| `myProperty` | {nok} |
+|===
+
 [[implicit-conversions]]
 == Implicit Conversions
 

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

@@ -382,7 +382,7 @@ Aspects each containing a single Collection.
 Describes a Property whose value can have one of two possible types (a disjoint union). This
 Characteristic is special since it does not directly define a data type. The data type is defined in
 the two Characteristics which define the left and right value of the disjoint union. Also see
-xref:characteristics.adoc#either-characteristic[Either].
+xref:characteristics.adoc#either-characteristic[Either] and xref:payloads.adoc#characteristics-payload-mappings[Payload mappings to JSON for Characteristics].
 
 Example:
 
@@ -566,10 +566,8 @@ include::example$extending-entity-declaration-inheritance.ttl[tags=extending-ent
 [[declaring-abstract-entities]]
 ==== Declaring Abstract Entities
 
-In contrast to Entities, Abstract Entities cannot directly be used as data types. The main use case
-for Abstract Entities is to share Properties across multiple Entities. This can be achieved through
-inheritance: Abstract Entities can extend other Entities and Abstract Entities and can themselves be
-extended in a manner not dissimilar to how abstract classes are used in many programming languages.
+In contrast to Entities, Abstract Entities cannot directly be instantiated. A Characteristic class may have a type `samm:entity` or `samm:AbstractEntity`. But a Characteristic instance cannot have a type `samm:AbstractEntity`. If there is an instance created from a Characteristic that uses an Abstract Entity as its type, this Characteristic instance's dataType must be a sub-Entity of the Abstract Entity.
+The main use case for Abstract Entities is to share Properties across multiple Entities. This can be achieved through inheritance: Abstract Entities can extend other Entities and Abstract Entities and can themselves be extended in a manner not dissimilar to how abstract classes are used in many programming languages.
 
 In the following example, both `SteeringWheel` and `Seat` _extend_ the Abstract Entity
 `VehicleComponent`. Both inherit the `typeNumber` and the `manufacturer` Properties:

documentation/modules/ROOT/pages/payloads.adoc

@@ -174,8 +174,103 @@ A Property `errorMessages` with a Collection Characteristic and effective data t
 }
 ----
 
+[[characteristics-payload-mappings]]
+== Specific payload mappings for Characteristics
 
-CAUTION: Due to the https://www.ecma-international.org/ecma-262/5.1/#sec-8.5[limits in the
+This section describes how data payloads look like for specific xref:characteristics.adoc[Characteristics].
+
+|===
+| Characteristic Name | Corresponding JSON data type
+| `samm-c:Either` | A JSON object with exactly either a `left` or `right` key. If the `left` key is present, its data type is the effective data type of the Characteristic referred to by `samm-c:left`; if the `right` key is present, its data type is the effective data type of the Characteristic referred to by `samm-c:right`.
+|===
+
+
+The following example Aspect uses `samm-c:Either` to express that the Property `speedValue` can either return the integer value for speed,
+or an Error message (using an Entity), if the value could not be determined (cf. xref:modeling-guidelines.adoc#declaring-either[Declaring Either]).
+
+So, assuming an Aspect Model has a Property `speedProperty` with its `samm:characteristic` set to `:Result` according to the following definition:
+[source,turtle,subs="attributes+"]
+----
+include::ROOT:example$either-declaration.ttl[tags=either-declaration]
+----
+
+the corresponding JSON payload either contains a `left` key with the error description:
+[source,json]
+----
+{
+  "result": {
+    "left": {
+      "errorCode": "...",
+      "errorDescription": "..."
+    }
+  }
+}
+----
+or it can contain a `right` key with the success status:
+[source,json]
+----
+{
+  "result": {
+    "right": {
+      "status": "..."
+    }
+  }
+}
+----
+
+In the following example the Property `speedProperty` can either return the integer value for speed `SpeedValue`,
+or an `Error`, if the value could not be determined. `Error` can either return the `samm-c:Text` with simple error text or `ErrorMessage` (using an Entity) for details of error like `errorCode` and `errorDescription`.
+
+So, assuming the Property `speedProperty` with `samm-characteristics` set to `:Result` according to the following definition:
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-with-double-either-characteristic.ttl[tags=aspect-with-double-either-characteristic]
+----
+
+it can contain `right` key with the speed value:
+[source,json]
+----
+{
+  "speedProperty": {
+    "right": 60
+  }
+}
+----
+
+or possible `left` key of `Error` contains Error message:
+[source,json]
+----
+{
+  "speedProperty" : {
+    "left" : {
+      "right" : {
+        "errorDescription" : "...",
+        "errorCode" : "..."
+      }
+    }
+  }
+}
+----
+
+or it can contain `right` key of `Error` with simple error text:
+[source,json]
+----
+{
+  "speedProperty" : {
+    "left" : {
+      "left" : "Simple error description..."
+    }
+  }
+}
+----
+
+IMPORTANT: If the model is invalid, it might be impossible to build a JSON payload that corresponds to the model.
+For example, if a Set of `xsd:boolean` values has a xref:characteristics.adoc#length-constraint[Length Constraint] of `samm-c:minValue` 3, no valid payload can be constructed.
+
+[[limitations]]
+== Limitations
+
+Due to the https://www.ecma-international.org/ecma-262/5.1/#sec-8.5[limits in the
 represention of numbers] in JSON, the maximum integer number that can be used without losing
 precision is 2⁵³-1 (defined as
 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER[Number.MAX_SAFE_INTEGER]).

documentation/modules/appendix/pages/best-practices.adoc

@@ -84,9 +84,16 @@ range, while a Property such as `numberOfProducedItems` is not logically limited
 [[choosing-a-unit]]
 == Choosing a Unit
 
-When trying to refer to a physical unit, please see the
-xref:appendix:unitcatalog.adoc[Unit Catalog]. When searching for the unit,
-remember that the unit catalog uses British English.
+When trying to refer to a physical unit, please see the xref:appendix:unitcatalog.adoc[Unit
+Catalog]. When searching for the unit, remember that the unit catalog uses British English, e.g.,
+_metre_ instead of _meter_.
+
+TIP: If you're modeling quantities for which both the metric system and the imperial system provide
+units, such as meter vs feet, it is always recommended to use the metric system (preferably SI units
+like meter or others like kilometer if more common in the domain) – unless there are specific
+reasons to create the model differently. In any case it is strongly discouraged to add multiple
+Properties in the same scope representing the same value only using different units due to the
+inherent complexity.
 
 [[choosing-a-characteristic]]
 == Choosing a Characteristic

esmf-samm-build-plugin/pom.xml

@@ -26,7 +26,7 @@
 
    <properties>
       <maven-plugin-plugin-version>3.6.4</maven-plugin-plugin-version>
-      <plantuml-version>1.2023.8</plantuml-version>
+      <plantuml-version>1.2023.9</plantuml-version>
    </properties>
 
    <dependencies>

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

@@ -366,6 +366,20 @@ samm:PropertyShape
             }
          """
       ] ;
+      sh:sparql [
+         a sh:SPARQLConstraint ;
+         sh:message "An example value with boolean dataType '{$this}' can contain just 'true' or 'false' values in lower case." ;
+         sh:prefixes samm:prefixDeclarations ;
+         sh:select """
+         select $this ?exampleValue ?code
+            where {
+               $this samm:exampleValue ?exampleValue .
+               bind( datatype( ?exampleValue ) as ?providedType )
+               filter ( ?providedType = xsd:boolean && ( str( ?exampleValue ) != "true" && str( ?exampleValue ) != "false" ) )
+               bind('ERR_EXAMPLE_VALUE_NOT_ALLOWED' AS ?code)
+            }
+         """
+      ] ;
       sh:minCount 0 ;
       sh:maxCount 1 ;
       sh:name "exampleValue" ;

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

@@ -80,6 +80,8 @@ protected static Stream<KnownVersion> versionsUpToIncluding1_0_0() {
    final String messageMissingDatatype = "No datatype is defined on the Characteristic instance '{$this}'.";
 
    final String messageHasToUseSubClass = "Constraint '{$this}' has invalid type samm:Constraint, only subtypes of samm:Constraint may be used.";
+
+   final String messageWrongBooleanValues = "An example value with boolean dataType '{$this}' can contain just 'true' or 'false' values in lower case.";
    final String messageInvalidEntryEntityPropertyList =
          "Element '{?value}' in the Entity's '{$this}' properties list must be a property - either directly or " +
                "via a reference to a property with an attribute samm:optional \"true\"^^xsd:boolean and/or samm:payloadName or "

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

@@ -167,4 +167,37 @@ public void testCharacteristicInstanceWithCharacteristicAsDataTypeExpectFailure(
             instanceId, sammUrns.datatypeUrn, violationUrn, value );
       expectSemanticValidationErrors( "characteristic-shape", instanceName, metaModelVersion, resultForDataType );
    }
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_0_0" )
+   public void testCharacteristicWithEntityDataType( final KnownVersion metaModelVersion ) {
+      checkValidity( "characteristic-shape", "TestCharacteristicInstanceWithEntityDataType",
+              metaModelVersion );
+   }
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_2_0" )
+   public void testCharacteristicWithAbstractEntityDataType( final KnownVersion metaModelVersion ) {
+      checkValidity( "characteristic-shape", "TestCharacteristicInstanceWithAbstractEntityDataType",
+              metaModelVersion );
+   }
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_2_0" )
+   public void testCharacteristicWithExtendedInstantiatedAbstractEntityDataType( final KnownVersion metaModelVersion ) {
+      checkValidity( "characteristic-shape", "TestCharacteristicInstanceWithExtendedInstantiatedAbstractEntityDataType",
+              metaModelVersion );
+   }
+
+   @ParameterizedTest
+   @MethodSource( value = "versionsStartingWith2_2_0" )
+   public void testCharacteristicWithDirectInstantiatedAbstractEntityDataTypeExpectFailure( final KnownVersion metaModelVersion ) {
+      final String focusNode = testNamespacePrefix + "InstantiatedAbstractEntityInstance";
+      final String value = testNamespacePrefix + "AbstractTestEntity";
+      final String errorAbstractUsageMessage = validator.getMessageText( "samm:AbstractEntityDirectlyInstantiated", "ERR_ABSTRACT_USAGE", metaModelVersion );
+      final SemanticError resultErrorAbstractUsageMessage = new SemanticError( errorAbstractUsageMessage,
+              focusNode, "", violationUrn, value );
+      expectSemanticValidationErrors( "characteristic-shape", "TestCharacteristicInstanceWithDirectInstantiatedAbstractEntityDataType", metaModelVersion,
+              resultErrorAbstractUsageMessage );
+   }
 }