Adding concept of 'format'

[sschleemilch]

About

Current use of units comes to its limits for dates.
unix-time as well as iso8601 are no units. Instead they represent a certain format.
That is why we should have a more correct way of specifying that: format.
The concept is similar with the one of units in regard of files and similar format.

vss-tools should forbid the usage of unit and format at the same time.
I thought about letting format elements also specify allowed-units. This would allow narrowing down unix-time whether it is in unit seconds or milli seconds. I decided against that due to simplicity. Otherwise, allowed-datatypes have to be merged or the one from format need to have priority or something in the middle.
For the sake of simplicity for the user and since the problem is probably only related to unix-time, I threw away that idea.
Instead, for unix time we have right now two entries: unix-time and unix-time-ms

[erikbosch]

We need to discuss if we still want to use something like quantity for formats, to indicate that some formats represent the same type of content, like if you use iso8601 you could possibly convert it to unix-time-ms, but not to ipv4.

If we do not want to reuse the quantity concept then we should possibly remove datetime from the quantity file.

[sschleemilch]

That's a good point. I did not think about quantities so much here

[erikbosch]

Mom:

• Please review/discuss
• Daniel: Possibly use "kind" instead of "quantity"

[jdacoello]

• Daniel: Possibly use "kind" instead of "quantity"

Units and their quantity kinds are comprehensively modelled in artefacts like the Quantities, Units, Dimensions and Types (QUDT). It would be a smart move to adopt the units listed in a maintained model, like this one.

For example. The property Speed can be specified with the default unit km/h which, in such a model, has a unique identifier http://qudt.org/vocab/unit:KiloM-PER-HR.

Likewise, quantity kinds specify the fact that the actual quantity of a property can be represented with different compatible units. http://qudt.org/vocab/quantitykind/. If an established model is used as a reference, it would be sufficient to specify either the unit or the quantity kind via pointers to those concepts. For example:

Example a. Specifying speed as a property that..

a.1: ...might be represented with any compatible unit:

Vehicle.Speed:
  type: Sensor
  quantity_kind: http://qudt.org/vocab/quantitykind/LinearVelocity # Any compatible unit is valid.
  description: ...
  ...

a.2: ...must be represented with a given unit:

Vehicle.Speed:
  type: Sensor
  unit: http://qudt.org/vocab/unit:KiloM-PER-HR  # Enforcing the use of a particular unit
  description: ...
  ...

Example b. Specifying the timestamp of the observation of the current location:

CurrentLocation.Timestamp:
  datatype: uint32
  type: sensor
  quantity_kind: http://qudt.org/vocab/quantitykind/Time
  unit: http://qudt.org/vocab/unit/SEC
  description: Timestamp from GNSS system for current location, formatted according to ISO 8601 with UTC time zone.

Deciding which of the above examples is the right one depends on the scope we define for VSS. So far, VSS has been descriptive only, so in that case something like quantity_kind should be sufficient. However, if we want to enforce a particular unit, then the field unit makes more sense.

[erikbosch]

Thanks for the input @jdacoello

The idea when introducing the quantity file was to go a bit in this direction. In the past we had a domain field in the unit file, but we did not specify the domains anywhere. When renaming domain to quantity we also introduced a quantity file to be able to give a better definition of the quantity. If I remember it correctly we had also at that time a discussion if a signal should specify unit or quantity. The conclusion is/was that as long as we have stupid/simple APIs we must specify a default unit explicitly or implicitly, as when using for example VISS to read/write data you do not pass unit info. A more advanced API could take the quantity information from the unit definition and use that to offer/accept the signal in multiple units supporting that quantity

We could use labels like http://qudt.org/vocab/unit:KiloM-PER-HR to specify (default) unit for a signal. But it has two drawbacks. The first is that it is a long identifier which might be cumbersome if you add/edit VSS signals in a text editor. The second is that any reference system (like qudt) not will cover all units we want to have.

My favorite example is "stars" that we for some historical reason have in the unit file (but do not use for any signal)

  stars:
    label: stars
    description: Rating measured in stars
    domain: rating

As of today I am a bit reluctant to use qudt labels directly in *.vspec files, but I have no problem including qudt references in the unit/quantity/format files as needed. When creating the quantity file I tried to reuse definitions and add a reference, like in the example below. One can off course discuss if the QUDT definition at https://qudt.org/vocab/quantitykind/LinearVelocity is better or worse than the ISO definition

velocity:
  definition: Vector quantity giving the rate of change of a position vector (ISO 80000-3:2019)

[erikbosch]

MoM:

• Daniel: we can save time by using curated list
• Daniel: We can keep prefix/aliases
• Daniel: Timestamp should not be units, we may have format plus units
• Erik: Continue review/discuss
• S Schleemilch - expects to use either format or unit.

[erikbosch]

MoM: Continue discuss next week, agree on how proceed

[erikbosch]

Took a second look here. I suggest we discuss it at next meeting like this:

First agree on whether we want to "split" unit to unit and format

If not, not much reason to discuss details. I can accept if we from a logical perspective want to split them, but I do not really know if there are any practical advantages. One disadvantage could be that we need to add one more parameter to the tool, but if we use the same feature that we look in the same folder as the root *.vspec by default that should not be a big problem.

Details

If we agree we need to discuss details. My proposal for now:

• Remove datetime as quantity
• Add support for a qudt attribute in unit and quantity files. Then we could start mapping to qudt and later check how much that actually is mapped. Or should we make it more general and call the attribute uri so that we could use "custom" uri's as well, like https://covesa.global/vocab/unit/stars for the (obsolete) stars unit or private ones like https://bosch.com/vocab/unit/some_private_bosch_unit
• Wait with merging this PR until we have a vss-tools implementation.

I am also thinking if we need to have a transition period. Like keeping unit and format in parallel for a while, so you could analyze the upcoming VSS 6.0 with vss-tools 5.0. Input there would be appreciated.

VehicleIdentification.VehicleModelDate:
  datatype: string
  type: attribute
  unit: iso8601
  format: iso8601
  description: The release date in ISO 8601 format of a vehicle model (often used to differentiate versions of the same make and model).

[erikbosch]

MoM:

• S Schildt - do we really gain anything from this change? I am not opposed, but not enthustiastic
• Stefan: No distinct opinion
• Daniel: If we specify format we can reuse regexps and similar

[erikbosch]

MoM:

• Put on hold for now, changing to draft, leave open for now