From b1ac8c817013404f1cef62971f41a210e9225911 Mon Sep 17 00:00:00 2001 From: Yauhenikapl Date: Mon, 22 Jan 2024 12:44:53 +0300 Subject: [PATCH] Properly document mapping of samm-c:Either to JSON payloads Changes: - Update documentation; - Add .ttl Model for Either cases. Fixes: #271 --- ...pect-with-double-either-characteristic.ttl | 52 +++++++++++++++++++ .../aspect-with-either-characteristic.ttl | 40 ++++++++++++++ .../modules/ROOT/pages/payloads.adoc | 38 ++++++++++++-- 3 files changed, 126 insertions(+), 4 deletions(-) create mode 100644 documentation/modules/ROOT/examples/aspect-with-double-either-characteristic.ttl create 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 new file mode 100644 index 00000000..d5f5674d --- /dev/null +++ b/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 : . +@prefix samm: . +@prefix samm-c: . +@prefix samm-e: . +@prefix unit: . +@prefix xsd: . + +# 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 ; + 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 ; + 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 . diff --git a/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl b/documentation/modules/ROOT/examples/aspect-with-either-characteristic.ttl new file mode 100644 index 00000000..08019e9e --- /dev/null +++ b/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 : . +@prefix samm: . +@prefix samm-c: . +@prefix samm-e: . +@prefix unit: . +@prefix xsd: . + +# 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 ; + 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 . diff --git a/documentation/modules/ROOT/pages/payloads.adoc b/documentation/modules/ROOT/pages/payloads.adoc index 519f0463..9a565bed 100644 --- a/documentation/modules/ROOT/pages/payloads.adoc +++ b/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,8 +174,29 @@ 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] ---- { @@ -184,9 +204,11 @@ Another one example for `samm-c:Either`, a Property `speedProperty` has Characte "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] ---- {