Refactoring and update docs.

Fixes: #271
eclipse-esmf · Jan 23, 2024 · 92013c7 · 92013c7
1 parent 4ee7f8d
commit 92013c7
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 40 deletions.
diff --git a/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl b/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl
@@ -15,38 +15,39 @@
 
 # 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:left :Status ;
    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 .
+:Status a samm-c:Either ;
+   samm:preferredName "Status Either Type"@en ;
+   samm:description "This is a Status Either for speed."@en ;
+   samm-c:left :ErrorMessage ;
+   samm-c:right :StatusCode .
 
 :Speed a samm:Characteristic ;
-   samm:name "speed" ;
    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 .
+
+:StatusCode a samm:Characteristic ;
+   samm:dataType xsd:integer .
+# end::aspect-with-double-either-characteristic[]
diff --git a/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl b/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl
@@ -15,26 +15,30 @@
 
 # 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:left :ErrorMessage ;
    samm-c:right :Speed .
 
-:IsMoving a samm:Characteristic ;
-   samm:name "isMoving" ;
-   samm:dataType xsd:boolean .
+:ErrorMessage a samm:Characteristic ;
+   samm:dataType :ErrorEntity .
 
 :Speed a samm:Characteristic ;
-   samm:name "speed" ;
    samm:dataType xsd:integer .
+
+: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-either-characteristic[]
diff --git a/documentation/modules/ROOT/pages/payloads.adoc b/documentation/modules/ROOT/pages/payloads.adoc
@@ -177,7 +177,7 @@ 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].
+This section describes how data payloads look like for specific xref:characteristics.adoc[Characteristics].
 
 |===
 | Characteristic Name | Corresponding JSON data type
@@ -186,7 +186,7 @@ In this section provided specific cases for the xref:characteristics.adoc[Charac
 
 
 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:
+`ErrorMessage` (`xref:characteristics.adoc#single-entity-characteristic[Entity]` data type), which shows why speed can't be retrieved, or '60' (`xsd:integer`) would be serialized in the JSON payload as follows:
 
 Example:
 
@@ -200,14 +200,18 @@ Generated payload:
 [source,json]
 ----
 {
-  "speedProperty": {
-    "left": true
+  "speedProperty" : {
+    "left" : {
+      "errorDescription" : "yedUsFwdkelQbxeTeQOvaScfqIOOmaa",
+      "errorCode" : "eOMtThyhVNLWUZNRcBaQKxI"
+    }
   }
 }
 ----
 
 or
 
+[source,json]
 ----
 {
   "speedProperty": {
@@ -216,8 +220,8 @@ or
 }
 ----
 
-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:
+Another one example for Property `speedProperty` has Characteristic and effective data type `samm-c:Either`. Field `samm-c:left` with name 'Status' has type `samm-c:Either` and field `samm-c:right` with name 'Speed has type `xsd:integer`.
+Field `samm-c:left` with name 'ErrorMessage' has `xref:characteristics.adoc#single-entity-characteristic[Entity]` data type and shows why speed can't be retrieved or 'StatusCode' with (`xsd:integer`) data type in `samm-c:right` field. This structure would be serialized in the JSON payload as follows:
 
 Example:
 
@@ -229,18 +233,37 @@ include::example$aspect-with-double-either-characteristic.ttl[tags=aspect-with-d
 [source,json]
 ----
 {
-  "speedProperty": {
-    "left": {
-        "left": 60
+  "speedProperty" : {
+    "left" : {
+      "left" : {
+        "errorDescription" : "yedUsFwdkelQbxeTeQOvaScfqIOOmaa",
+        "errorCode" : "eOMtThyhVNLWUZNRcBaQKxI"
+      }
+    }
+  }
+}
+----
+
+or
+
+[source,json]
+----
+{
+  "speedProperty" : {
+    "left" : {
+      "left" : 200
     }
   }
 }
+----
 
 or
 
+[source,json]
+----
 {
   "speedProperty": {
-    "left": true
+    "left": 60
   }
 }
 ----