Datatype/Unit for Timestamps

[erikbosch]

As of today we represent Timestamps in COVESA as string signals where we in free text specify that the value is a timestamp and shall be formatted according to ISO 8601. This is however difficult to interpret for tooling, there it would be better to have a formal notation that this signal actually contains a timestamp. I see two "easy" ways to solve this:

• One is to invent a new datatype "timestamp", "iso_8601_timestamp" or similar, where we in documentation says that this datatype by default should be a string formatted according to ISO 8601.
• Another possibility is to use unit for this purpose ( and keep string as type).

Both methods would help SDKs/APIs/GUIs to know that this should be a timestamp so they can offer a nice date-picker and/or a timestamp-validator. If using a downstream project like VISS or KUKSA you should still use an ISO 8601 string when exchanging data.

Any thoughts?

https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_types/#timestamps

Timestamps are in VSS typically represented as strings, formatted according to ISO 8601. Timestamps shall be expressed in UTC (Coordinated Universal Time), with special UTC designator (“Z”). Time resolution SHALL at least be seconds, with subsecond resolution as an optional degree of precision when desired. The time and date format shall be as shown below, where the sub-second data and delimiter is optional.

[ppb2020]

Unit is typically used to tell the user how to interpret a value. Thus, I think "iso8601" as a unit would make sense. I would remove the restriction that the timestamp be in UTC, as ISO 8601 allows the specification of a time zone in teh string, which means that it is always possible to convert back to UTC.

One issue with this approach, though, is that it also requires the dataype to be a string. AFAIK, there no such enforcement today (that is, no enforcement of a specific datatype for any unit). Should this be considered?

This downside is resolved by the first proposed solution, as a datatype of "ISO8601" or "ISO_8601" could be enforced to be a string with a specific format. Here, I would also allow time zone specification as per ISO 8601

This aligns with some thoughts I have been having of proposing a new datatype called, say, "reference", where the datatype would be a string that is expected to contain a node path name. For example:

DriverPosition:
  datatype: reference
  type: attribute
  default: "Vehicle.Cabin.Seat.Row1.Pos1"
  description: The position of the driver seat.

This is similar to a datatype of "iSO8601", where the value is expected to be a string in a specific format that can be parsed and validated.

[erikbosch]

As of today the tooling does not check that the datatype-unit combination makes sense. You can specify km/h as unit and string as datatype if you like, but that is maybe not a good idea as we have not specified how the textual representation should look like concerning for example comma or period or separator for decimals.

What we easily could do is to extend the "unit-syntax" in https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/units.yaml so that it specifies allowed datatypes, either explicitly mentioning every allowed dataype like datatype : [uint8, float, uint32, ...] or symbolic groups like datatype: numeric (any int or float type) or datatype: string, and let tooling check that it is fulfilled.

[Kostadin-Ivanov]

units.yaml already holds entries for ms, s, min, h, day, weeks, months, years - which are more like time period measurements and UNIX Timestamp - which is described a s"point in time".

Maybe for date-time related properties, the UNIX Timestamp should be sufficient, but then there might be required a format entry, which then should specify the ISO 8601 format.

Further more, since UNIX Timestamp "measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch, without adjustments made due to leap seconds." the provided default / example for corresponding date-time property(ies) might also need to be adjusted in proper timestamp values.

Anyway, I also think that a unit: iso8601 would be plenty enough to indicate that corresponding property is to be handled (formatted) as per ISO 8601 standard with or without time zone. With regards to the datatype, I think that the string is the correct and assumed type for ISO 8601 based values. With respect to the UNIX Timestamp, I'd say that correct datatype should be integer since there is only numbers in its value.

Whether these should be validated on VSS level or in the RBS-VSS-TOOLS (init.py or vsstree.py), maybe rbs-vss-tools would be the right place to pre-validate the VSS, but this can be further decided.

[erikbosch]

For most of the signals where we today use string+iso8601 we could likely have managed using unix timestamp as well, but then as you say combined with a reasonable sized integer (uint32,int64 or uint64). Even if we do not have any signals using unix timestamps in the standard catalog, it could possibly be useful for custom signals.

[Kostadin-Ivanov]

Understand.

Then I guess that the suggestion of having: datatype: string/number unit: iso8601/UNIX Timestamp would fit perfect for date and time related properties (attributes ), so the VSS reader (person) / parser (some script) would easily catch the type and format of the corresponding property (attribute) and know how to read / parse it for further use based on the specified unit.

[erikbosch]

Current status: Both units supported, but in discussion (and here) agreed that string/iso8601 format is preferred in standard catalog.