Improve documentation of Value-Only

[BirgitBoss]

Is your feature request related to a problem? Please describe.

The existing rules are hard to understand. Many readers requested a more easy to understand documentation of the Value-Only serialialiation.

Additionally, Examples shall be updated to not come from Submodel but provide Value-only for every element since the API (IDTA-01002) allows $value calls not only for submodels.

see also
admin-shell-io/aas-specs-api#270
admin-shell-io/aas-specs-api#269
admin-shell-io/aas-specs-api#268

[BirgitBoss]

@mjacoby listed the remaining remaining problems in
#403 (review). Added: links to other issues if existing + additional open item.

• (1) 2^53-1 is again missing the 5
• (2) JSON schema again contains validation for Operations which are defined not to have a valueOnly serialization
• (3) Do not change Value-Only type for Range: stay with number #407 Range is again limited to number
• (4) There are no rules defined how to serialize elements other than Submodel, i.e. serialization of all other types is only given by a single example. This means serialization is seriously underdefined and unclear.
• (5) The section about limitation of numbers in JSON to 2^53-1 is still lacking any substantial reasoning. There is no such limitation in JSON itself, only in the implementations in different programming languages - and they might even be different to each other. So why this limitation?
• (6) Handling of non-existent values is not addressed at all, i.e. what is the valueOnly Serialization of a property that has no value? What about SubmodelElementCollection without elements or Submodel without any elements?
• (7) Missing serialization rules for auxiliary classes (i.e. classes that are not subclass of SubmodelElement but still part of the serialization) like Reference
• (8) Rules for serialization in section Rules for Value-Only Serialization are inconsistent/overlapping, e.g.,
  The definition of SubmodelElementCollection says

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.

while the definition of Property says

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).

If you apply these rules recursively like required by another rule, you end up with something containing the idShort of the property twice.

• (9) Check cardinalities in rules and Value-Only schema

  • "annoations" in AnnotatedRelationshipElements are not required
  • Blob/value is not required
  • EntityValue: statements are not required, entityType is not required any longer

• (10) ValueOnly: do not mention types omitted  #371 ValueOnly: do not mention types omitted

[BirgitBoss]

For (3) I created a new issue: #407 since I am not convinced to allow "all types" makes any sense for Range.

@mjacoby If you want to request to remove the section about limitation of numbers in JSON, topic (5) please raise an additional issue for this.

[BirgitBoss]

#403 covers (1) and (2) + adding examples and a table similar to metadata fields table

#408 covers (4), (8) and (9)

(5) ist still open, see #401 (comment)

The other topics are still open.