From c44ce83bf350e065648ec8eb3a141028501daf9c Mon Sep 17 00:00:00 2001 From: Yauhenikapl Date: Thu, 1 Feb 2024 08:46:57 +0300 Subject: [PATCH] Refactoring and update docs. - Refactoring and adjusting docs. Fixes: #271 --- ...pect-with-double-either-characteristic.ttl | 10 ++-- .../aspect-with-either-characteristic.ttl | 44 --------------- .../modules/ROOT/pages/payloads.adoc | 55 +++++++++---------- 3 files changed, 32 insertions(+), 77 deletions(-) delete mode 100644 documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl diff --git a/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl b/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl index ba1c6b0..9c3df76 100644 --- a/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl +++ b/documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl @@ -15,19 +15,19 @@ # tag::aspect-with-double-either-characteristic[] :AspectWithEither a samm:Aspect ; - samm:properties ( :speedProperty ) ; + samm:properties ( :`speedProperty` ) ; samm:operations ( ) . :speedProperty a samm:Property ; - samm:characteristic :TestEither . + samm:characteristic :Result . -:TestEither a samm-c:Either ; +:Result a samm-c:Either ; samm:preferredName "Test Either"@en ; samm:description "This is a test Either."@en ; - samm-c:left :Status ; + samm-c:left :Error ; samm-c:right :Speed . -:Status a samm-c:Either ; +:Error a samm-c:Either ; samm:preferredName "Status Either Type"@en ; samm:description "This is a Status Either for speed."@en ; samm-c:left :ErrorMessage ; diff --git a/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl b/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl deleted file mode 100644 index 31ab909..0000000 --- a/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl +++ /dev/null @@ -1,44 +0,0 @@ -# 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 : . -@prefix samm: . -@prefix samm-c: . -@prefix samm-e: . -@prefix unit: . -@prefix xsd: . - -# tag::aspect-with-either-characteristic[] -:AspectWithEither a samm:Aspect ; - samm:properties ( :speedProperty ) ; - samm:operations ( ) . - -:speedProperty a samm:Property ; - samm:characteristic :TestEither . - -:TestEither a samm-c:Either ; - samm:preferredName "Test Either"@en ; - samm:description "This is a test Either."@en ; - samm-c:left :ErrorMessage ; - samm-c:right :Speed . - -:ErrorMessage a samm:Characteristic ; - samm:dataType :ErrorEntity . - -:Speed a samm:Characteristic ; - 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 index 5db167f..43c10cd 100644 --- a/documentation/modules/ROOT/pages/payloads.adoc +++ b/documentation/modules/ROOT/pages/payloads.adoc @@ -181,89 +181,88 @@ This section describes how data payloads look like for specific xref:characteris |=== | 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]`. +| `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`. |=== -Example for `samm-c:Either`, a Property `speedProperty` has Characteristic and effective data type `samm-c:Either` and the possible values -`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: +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 `result` with its `samm:characteristic` set to `:Result` according to the following definition: [source,turtle,subs="attributes+"] ---- -include::example$aspect-with-either-characteristic.ttl[tags=aspect-with-either-characteristic] +include::example$declaring-either.ttl[tags=either-declaration] ---- -Generated payload: - +the corresponding JSON payload either contain a `left` key with the error description: [source,json] ---- { - "speedProperty" : { - "left" : { - "errorDescription" : "yedUsFwdkelQbxeTeQOvaScfqIOOmaa", - "errorCode" : "eOMtThyhVNLWUZNRcBaQKxI" + "result": { + "left": { + "errorCode": "...", + "errorDescription": "..." } } } ---- - -or - +or it can contain a `right` key with the success status: [source,json] ---- { - "speedProperty": { - "left": 60 + "result": { + "right": { + "status": "..." + } } } ---- -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: +Another one example Aspect uses `samm-c:Either` to express that the Property `speedValue` can either return the integer value for speed, +or an `Error`, if the value could not be determined. `Error` can either return the integer value for status code (StatusCode) or Error message (using an Entity). +So, assuming an Aspect has a 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] ---- +the corresponding JSON payload either contain a `left` key with the `Error`: + +- possible `left` key possible contains Error message: [source,json] ---- { "speedProperty" : { "left" : { "left" : { - "errorDescription" : "yedUsFwdkelQbxeTeQOvaScfqIOOmaa", - "errorCode" : "eOMtThyhVNLWUZNRcBaQKxI" + "errorDescription" : "...", + "errorCode" : "..." } } } } ---- -or +- or it can contain `right` key for with integer value of `StatusCode`: [source,json] ---- { "speedProperty" : { "left" : { - "left" : 200 + "right" : 200 } } } ---- -or - +or it can contain `right` key with the speed value: [source,json] ---- { "speedProperty": { - "left": 60 + "right": 60 } } ----