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

Changes:
- Update documentation;
- Add .ttl Model for Either cases.

Fixes: #271

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

@@ -0,0 +1,52 @@
+# Copyright (c) 2023 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.0.0#> .
+@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.0.0#> .
+@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.0.0#> .
+@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.0.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) 2023 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.0.0#> .
+@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.0.0#> .
+@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.0.0#> .
+@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.0.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/payloads.adoc

@@ -145,12 +145,11 @@ the data. The mappings are described in the following table.
 .2+| Encoded binary data
 | `xsd:hexBinary` | String
 | `xsd:base64Binary` | String
-.4+| Miscellaneous types
+.3+| Miscellaneous types
 | `xsd:anyURI` | String
 | `samm:curie` | String
 | `rdf:langString`
 | A JSON object with a structure as described in the rules above.
-| `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]`.
 |===
 
 For example, a Property `errorMessage` with effective data type `rdf:langString` and the value
@@ -175,18 +174,41 @@ 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]`.
+|===
+
+
 Another one 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' (`Number`) would be serialized in the JSON payload as follows:
+`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
@@ -195,7 +217,15 @@ or
 ----
 
 A 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' (`Number`). This structure would be serialized in the JSON payload as follows:
+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]
 ----
 {