Update documentation

Clarifies string/float/double. Reformat recommendatations to state that they also are rules for VSS catalog Remove enum recommendation Fixes COVESA#705 Fixes COVESA#706 Fixes COVESA#700 Signed-off-by: Erik Jaegervall <[email protected]>
boschglobal · Feb 9, 2024 · ca75887 · ca75887
1 parent b9cff17
commit ca75887
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 12 deletions.
diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md
@@ -109,17 +109,25 @@ The VSS specification must adhere to YAML syntax. To keep the standardized VSS s
 
 ### Naming Conventions
 
-The recommended naming convention for node elements is to use camel case notation starting with a capital letter. It is recommended to use only
-`A-Z`, `a-z` and `0-9` in node names. For boolean signals it is recommended to start the name with `Is`.
+Node names in VSS must follow the restrictions specified in [Yaml](https://yaml.org/spec/1.2.2/#chapter-5-character-productions) i.e. must only use the printable subset of the Unicode character set.
+
+Tools and Generators supporting VSS may however put additional restrictions on which characters that are allowed. For maximum portability, node names in the VSS standard catalog must fulfill the following rules
+
+* Node names in the VSS standard catalog shall use camel case notation starting with a capital letter.
+* Node names in the VSS standard catalog shall use only `A-Z`, `a-z` and `0-9` in node names.
+* Boolean signals must start with `Is`.
+* Full path of node names must be unique also when using case insensitive comparison.
+  It is for example not allowed to have both `Vehicle.Abc` and `Vehicle.ABC` in the standard catalog
+  even if that is valid VSS as VSS is case sensitive.
 
 Examples:
 
 ```
-SomeBranch.AnotherBranch.MySignalName
 Vehicle.Cabin.Door.Row1.Left.IsLocked
+SomeOtherTree.AnotherBranch.MySignalName
 ```
 Naming convention for string literals can be found in the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed/)for specifying allowed values.
 
 ### Line Length
 
-It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs present in files over multiple lines.
+It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs over multiple lines.
diff --git a/docs-gen/content/rule_set/data_entry/allowed.md b/docs-gen/content/rule_set/data_entry/allowed.md
@@ -27,17 +27,17 @@ in a list.  Only values can be assigned to the data entry, which are
 specified in this list.
 
 The `datatype` specifier gives the datatype of the individual elements of the `allowed`
-list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless othwerise specified.
+list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless otherwise specified.
 
 ## Recommendation on String values
 
-For string values used for `default` and `allowed` statements it is recommended to start with `A-Z`
-and then use only `A-Z`, `0-9` and underscore (`_`).
-It is recommended to use single quotes (`'`) as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
+String values used for `default` and `allowed` statements may contain characters from the printable subset of the Unicode character set.
+If using [COVESA VSS-tools](https://github.com/COVESA/vss-tools) it is recommended to use single quotes (`'`) around values as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
 It is recommended not to specify a dedicated value corresponding to "unknown" or "undefined" unless there is a relevant use-case for that particular signal.
 The background is that a signal with an array of allowed values shall be handled just as any other signal.
 If e.g. the value of current speed or vehicle weight is unknown, then the vehicle shall not publish the corresponding signal.
-Similarly, for the example above, if the steering wheel position is unknown then `SteeringWheel.Position`shall not be published.
+Similarly, for the example above, if the steering wheel position is unknown then
+`SteeringWheel.Position` shall not be published.
 
 ## Allowed values for array datatypes
 

diff --git a/docs-gen/content/rule_set/data_entry/data_types.md b/docs-gen/content/rule_set/data_entry/data_types.md
@@ -20,9 +20,14 @@ int32      | signed 32-bit integer      | -2147483648 | 2147483647
 uint64     | unsigned 64-bit integer    | 0    | 2^64 - 1
 int64      | signed 64-bit integer      | -2^63 | 2^63 - 1
 boolean    | boolean value              | 0/false | 1/true
-float      | floating point number      | -3.4e -38 | 3.4e 38
-double     | double precision floating point number | -1.7e -300 | 1.7e 300
-string     | character string           | n/a  | n/a
+float      | IEEE 754-2008 binary32 floating point number | -3.40e 38 | 3.40e 38
+double     | IEEE 754-2008 binary64 floating point number | -1.80e 308 | 1.80e 308
+string     | character string (unicode)          | n/a  | n/a
+
+## Strings
+
+Strings in VSS supports the unicode character set. Actual encoding like UTF-8 or UTF-16 is not
+specified by VSS, that is to up to the Protocol/API/SDK implementing VSS support to decide.
 
 ## Arrays
 
@@ -57,6 +62,8 @@ The time and date format shall be as shown below, where the sub-second data and
 YYYY-MM-DDTHH:MM:SS.ssssssZ
 ```
 
+VSS also supports the unit `unix-time` that can be used together with datatype `uint32`/`uint64`/`int64`to indicate that the signal value correspond to number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970.
+
 ## Data Streams
 
 Data Entries, which describe sensors offering binary streams