Properly document mapping of samm-c:Either to JSON payloads

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

@@ -0,0 +1,52 @@
+# 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#> .
+
+# tag::aspect-with-double-either-characteristic[]
+:AspectWithEither a samm:Aspect ;
+   samm:name "AspectWithEither" ;
+   samm:properties ( :speedProperty ) ;
+   samm:operations ( ) .
+
+:speedProperty a samm:Property ;
+   samm:name "speedProperty" ;
+   samm:characteristic :TestEither .
+
+:TestEither a samm-c:Either ;
+   samm:name "TestEither" ;
+   samm:preferredName "Test Either"@en ;
+   samm:description "This is a test Either."@en ;
+   samm:see <http://example.com/> ;
+   samm-c:left :LeftType ;
+   samm-c:right :IsMoving .
+
+:LeftType a samm-c:Either ;
+   samm:name "TestEither" ;
+   samm:preferredName "Left Either Type"@en ;
+   samm:description "This is a left Either type."@en ;
+   samm:see <http://example.com/> ;
+   samm-c:left :IsMovingLeft ;
+   samm-c:right :Speed .
+
+:IsMoving a samm:Characteristic ;
+   samm:name "isMoving" ;
+   samm:dataType xsd:boolean .
+
+:IsMovingLeft a samm:Characteristic ;
+   samm:name "isMovingLeft" ;
+   samm:dataType xsd:boolean .
+
+:Speed a samm:Characteristic ;
+   samm:name "speed" ;
+   samm:dataType xsd:integer .

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

@@ -0,0 +1,40 @@
+# 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#> .
+
+# tag::aspect-with-either-characteristic[]
+:AspectWithEither a samm:Aspect ;
+   samm:name "AspectWithEither" ;
+   samm:properties ( :speedProperty ) ;
+   samm:operations ( ) .
+
+:speedProperty a samm:Property ;
+   samm:name "speedProperty" ;
+   samm:characteristic :TestEither .
+
+:TestEither a samm-c:Either ;
+   samm:name "TestEither" ;
+   samm:preferredName "Test Either"@en ;
+   samm:description "This is a test Either."@en ;
+   samm:see <http://example.com/> ;
+   samm-c:left :IsMoving ;
+   samm-c:right :Speed .
+
+:IsMoving a samm:Characteristic ;
+   samm:name "isMoving" ;
+   samm:dataType xsd:boolean .
+
+:Speed a samm:Characteristic ;
+   samm:name "speed" ;
+   samm:dataType xsd:integer .

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:payload.adoc#characteristics-payload-mappings[Payload mappings to JSON for Characteristics].
 
 Example:
 

documentation/modules/ROOT/pages/payloads.adoc

@@ -174,6 +174,77 @@ A Property `errorMessages` with a Collection Characteristic and effective data t
 }
 ----
 
+[[characteristics-payload-mappings]]
+== Specific payload mappings for Characteristics
+
+In this section provided specific cases for the xref:characteristics.adoc[Characteristics].
+
+|===
+| Characteristic Name | Corresponding JSON data type
+| `samm-c:Either` | A JSON object with the left field and the value, which is one of the types proposed in `xref:characteristics.adoc#either-characteristic[Either]`.
+|===
+
+
+Example for `samm-c:Either`, a Property `speedProperty` has Characteristic and effective data type `samm-c:Either` and the possible values
+`isMoving` (`xref:datatypes.adoc#data-types[xsd:boolean]` data type) or '60' (`xsd:integer`) would be serialized in the JSON payload as follows:
+
+Example:
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-with-either-characteristic.ttl[tags=aspect-with-either-characteristic]
+----
+
+Generated payload:
+
+[source,json]
+----
+{
+  "speedProperty": {
+    "left": true
+  }
+}
+----
+
+or
+
+----
+{
+  "speedProperty": {
+    "left": 60
+  }
+}
+----
+
+Another one example for Property `speedProperty` has Characteristic and effective data type `samm-c:Either`. Field `samm-c:left` has type `samm-c:Either` and field `samm-c:right` has type `xref:datatypes.adoc#data-types[xsd:boolean]`.
+Field `samm-c:left` has possible values `isMoving` (`xref:datatypes.adoc#data-types[xsd:boolean]` data type) or '60' (`xsd:integer`). This structure would be serialized in the JSON payload as follows:
+
+Example:
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-with-double-either-characteristic.ttl[tags=aspect-with-double-either-characteristic]
+----
+
+[source,json]
+----
+{
+  "speedProperty": {
+    "left": {
+        "left": 60
+    }
+  }
+}
+
+or
+
+{
+  "speedProperty": {
+    "left": true
+  }
+}
+----
+
 
 CAUTION: 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