Merge pull request #279 from eclipse-esmf/271-properly-document-mappi…

…ng-either-to-json-payload

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

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/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:
 

documentation/modules/ROOT/pages/payloads.adoc

@@ -174,8 +174,100 @@ 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..."
+    }
+  }
+}
+----
+
+[[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]).