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