Add changes for idShortPath and ValueOnly fixes from part 2 v3.0.2 (#372

) * add changes for idShortPath and ValueOnly fixes from part 2 v3.0.2 * Update valueOnly for SubmodelElementList correct text, examples were correct, no? Co-authored-by: Michael Jacoby <[email protected]> --------- Co-authored-by: Birgit Boss <[email protected]> Co-authored-by: Michael Jacoby <[email protected]>
admin-shell-io · Apr 10, 2024 · 88cc091 · 88cc091
1 parent f1da010
commit 88cc091
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 14 deletions.
diff --git a/documentation/IDTA-01001/modules/ROOT/pages/includes/IDTA-01001_ValueOnly.adoc b/documentation/IDTA-01001/modules/ROOT/pages/includes/IDTA-01001_ValueOnly.adoc
@@ -23,7 +23,8 @@ Values are only available for
 * ReferenceElement,
 * RelationshipElement + AnnotatedRelationshipElement,
 * Entity,
-* BasicEventElement.
+* BasicEventElement,
+* Submodel.
 
 Capabilities are excluded from the serialization scope since only data containing elements are in the focus. They are consequently omitted in the serialization.
 
@@ -32,17 +33,18 @@ The following rules shall be adhered to when serializing a submodel with the for
 * A submodel is serialized as an unnamed JSON object.
 * A submodel element is considered a leaf submodel element if it does not contain other submodel elements. A leaf submodel element follows the rules for the different submodel elements considered in the serialization, as described below. If it is not a leaf element, the serialization rules must be transitively followed until the value is a leaf submodel element.
 * For each submodel element:
-** _Property_ is serialized as ${Property/idShort}: ${Property/value} where ${Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section).
-** _MultiLanguageProperty_ is serialized as named JSON object with ${MultiLanguageProperty/idShort} as the name of the containing JSON property. The JSON object contains an array of JSON objects for each language of the _MultiLanguageProperty_ with the language as name and the corresponding localized string as value of the respective JSON property. The language name is defined as two chars according to ISO 639-1.
-** _Range_ is serialized as named JSON object with ${Range/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “min”. The second is named “max”. Their corresponding values are ${Range/min} and ${Range/max}.
-** _File_ and _Blob_ are serialized as named JSON objects with ${File/idShort} or ${Blob/idShort}as the name of the containing JSON property. The JSON object contains two JSON properties. The first refers to the content type named ${File/contentType} resp. ${Blob/contentType}. The latter refers to the value named “value” ${File/value} resp. ${Blob/value}. The resulting ValueOnly object is indistinguishable whether it contains File or Blob attributes. Therefore, the receiver needs to take the type of the target resource into account. Since the receiver knows in advance if a File or a Blob SubmodelElement shall be manipulated, it can parse the transferred ValueOnly object accordingly as a File or Blob object.
-** _SubmodelElementCollection_ is serialized as named JSON object with ${SubmodelElementCollection/idShort} as the name of the containing JSON property. The elements contained within the struct are serialized according to their respective type with ${SubmodelElement/idShort} as the name of the containing JSON property.
-** _SubmodelElementList_ is serialized as a JSON array with the index of the contained SubmodelElement in the list as the position in the JSON array. The elements contained within the list are serialized according to their respective type.
-** _ReferenceElement_ is serialized as ${ReferenceElement/idShort}: ${ReferenceElement/value} where ${ReferenceElement/value} is the serialization of the _Reference_ class.
-** _RelationshipElement_ is serialized as named JSON object with ${RelationshipElement/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “first”. The second is named “second”. Their corresponding values are ${RelationshipElement/first} resp. ${Relationship/second}. The values are serialized according to the serialization of a _ReferenceElement_ (see above).
-** _AnnotatedRelationshipElement_ is serialized according to the serialization of a _ReleationshipElement_ (see above). Additionally, a third named JSON object is introduced with “annotations” as the name of the containing JSON property. The value is ${AnnotatedRelationshipElement/annotations}. The values of the array items are serialized depending on the type of the annotation data element.
-** _Entity_ is serialized as named JSON object with ${Entity/idShort} as the name of the containing JSON property. The JSON object contains three JSON properties. The first is named “statements” ${Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause. The second is named either “globalAssetId” or “specificAssetId” and contains either a _Reference_ (see above) or a _SpecificAssetId_. The third property is named “entityType” and contains a string representation of ${Entity/entityType}.
-** _BasicEventElement_ is serialized as named JSON object with ${BasicEventElement/idShort} as the name of the containing JSON property. The JSON object contains one JSON property named “observed” with the corresponding value of ${BasicEventElement/observed} as the standard serialization of the _Reference_ class.
+
+** _Property_ is serialized as $\{Property/idShort}: $\{Property/value} where $\{Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section).
+** _MultiLanguageProperty_ is serialized as named JSON object with $\{MultiLanguageProperty/idShort} as the name of the containing JSON property. The JSON object contains an array of JSON objects for each language of the _MultiLanguageProperty_ with the language as name and the corresponding localized string as value of the respective JSON property. The language name is defined as two chars according to ISO 639-1.
+** _Range_ is serialized as named JSON object with $\{Range/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “min”. The second is named “max”. Their corresponding values are $\{Range/min} and $\{Range/max}.
+** _File_ and _Blob_ are serialized as named JSON objects with $\{File/idShort} or $\{Blob/idShort}as the name of the containing JSON property. The JSON object contains two JSON properties. The first refers to the content type named $\{File/contentType} resp. $\{Blob/contentType}. The latter refers to the value named “value” $\{File/value} resp. $\{Blob/value}. The resulting ValueOnly object is indistinguishable whether it contains File or Blob attributes. Therefore, the receiver needs to take the type of the target resource into account. Since the receiver knows in advance if a File or a Blob SubmodelElement shall be manipulated, it can parse the transferred ValueOnly object accordingly as a File or Blob object.
+** _SubmodelElementCollection_ is serialized as named JSON object with $\{SubmodelElementCollection/idShort} as the name of the containing JSON property. The elements contained within the struct are serialized according to their respective type with $\{SubmodelElement/idShort} as the name of the containing JSON property.
+** _SubmodelElementList_ is serialized as a named JSON array with $\{SubmodelElementList/idShort} as the name of the containing JSON property. The elements in the JSON array are the ValueOnly serializations of the elements contained in the SubmodelElementList while preserving the order, i.e. index n in the JSON array is the ValueOnly serialization of the element at index n of the SubmodelElementList.
+** _ReferenceElement_ is serialized as $\{ReferenceElement/idShort}: $\{ReferenceElement/value} where $\{ReferenceElement/value} is the serialization of the _Reference_ class.
+** _RelationshipElement_ is serialized as named JSON object with $\{RelationshipElement/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “first”. The second is named “second”. Their corresponding values are $\{RelationshipElement/first} resp. $\{Relationship/second}. The values are serialized according to the serialization of a _ReferenceElement_ (see above).
+** _AnnotatedRelationshipElement_ is serialized according to the serialization of a _ReleationshipElement_ (see above). Additionally, a third named JSON object is introduced with “annotations” as the name of the containing JSON property. The value is $\{AnnotatedRelationshipElement/annotations}. The values of the array items are serialized depending on the type of the annotation data element.
+** _Entity_ is serialized as named JSON object with $\{Entity/idShort} as the name of the containing JSON property. The JSON object contains three JSON properties. The first is named “statements” $\{Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause. The second is named either “globalAssetId” or “specificAssetId” and contains either a _Reference_ (see above) or a _SpecificAssetId_. The third property is named “entityType” and contains a string representation of $\{Entity/entityType}.
+** _BasicEventElement_ is serialized as named JSON object with $\{BasicEventElement/idShort} as the name of the containing JSON property. The JSON object contains one JSON property named “observed” with the corresponding value of $\{BasicEventElement/observed} as the standard serialization of the _Reference_ class.
 ** _SpecificAssetId_ is serialized as named JSON object with three JSON properties named as the attributes of _SpecificAssetId._
 
 * Submodel elements defined in the submodel other than the ones mentioned above are not subject to serialization of that SerializationModifier.

diff --git a/documentation/IDTA-01001/modules/ROOT/pages/includes/IDTA-01001_idShortPath.adoc b/documentation/IDTA-01001/modules/ROOT/pages/includes/IDTA-01001_idShortPath.adoc
@@ -12,7 +12,10 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d
 
 === Format "Path" (IdShortPath Serialization) in JSON
 
-To get only the idShort paths of a submodel element hierarchy, the serialization format is specified in terms of an idShortPath notation to be returned in an JSON array. The notation differs depending on whether a SubmodelElementCollection or a SubmodelElementList is present. In the first case, the submodel element's idShort is separated by "." (dot) from top level down to child level. In the second case, square brackets with an index "[<Index>]" are appended after the idShort of the containing SubmodelElementList.
+To get only the idShort paths of a submodel element hierarchy, the serialization format is specified in terms of an idShortPath notation to be returned in an JSON array. 
+The notation differs depending on whether a SubmodelElementCollection or a SubmodelElementList is present. In the first case, the submodel element's idShort 
+is separated by "." (dot) from top level down to child level. In the second case, square brackets with an index "[<Index>]" are appended after the idShort of the containing SubmodelElementList.
+In any case, the first item of any idShortPath is the idShort of the requested element.
 
 [.underline]#Grammar:#
 
@@ -28,11 +31,12 @@ To get only the idShort paths of a submodel element hierarchy, the serialization
 <NonZeroDigit>  ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
 ....
 
-In the following example the IdShortPaths of an element within the Submodel are described: 
+n the following example, where a request for idShort paths targets a  _MySubmodelElementCollection_ with SerializationModifier level = deep, the list of idShort paths is returned as follows:
 
 ====
 EXAMPLE Submodel
 
+
 Submodel: MySubmodel
 
 * Property: MyTopLevelProperty