Adding concept of 'format'

Signed-off-by: Sebastian Schleemilch <[email protected]>

docs-gen/content/rule_set/data_entry/data_formats.md

@@ -0,0 +1,48 @@
+---
+title: "Data Formats"
+date: 2024-08-29T12:36:12+02:00
+weight: 25
+---
+
+## Data Formats
+
+For some data it is necessary to specify the format.
+An example are dates.
+Let's say we specify a leaf e.g. `Vehicle.ProductionDate` and give it
+the datatype `string`. How would a consumer know what to expect in this string?
+It could be ISO8601, it could be a unix-timestamp or it could be something totally different.
+To provide that info, a `format` field can be used.
+
+A complete definition of the imaginary `ProductionDate` field could then look like this:
+
+```yaml
+Vehicle.ProductionDate:
+    description: The production date of the car
+    datatype: string
+    format: iso8601
+```
+
+All formats being used have to be specified in format definition files.
+
+## Format definitions file
+
+It has the following format:
+
+```yaml
+unix-time:
+  description: Unix Timestamp
+  allowed-datatypes: ['uint32','uint64','int64']
+```
+
+Both fields are required:
+- `description`: Should specify how the format is specified
+- `allowed-datatypes`: Datatypes allowed when using this format. The consistency will be enforced by `vss-tools`
+
+Please note that you can either specify `unit` or `format`.
+
+
+## Supported Data Formats in VSS Standard Catalog
+
+The catalog defines common formats in the `formats.yaml` file similar to how units are handled. `vss-tools` provides an interface to pass one or more format files.
+Like with unit files, `formats.yaml` will be loaded if it is present on the level
+of the given entry point `vspec` file.

spec/Cabin/Infotainment.vspec

@@ -234,7 +234,7 @@ HMI.IsScreenAlwaysOn:
 HMI.LastActionTime:
   datatype: string
   type: sensor
-  unit: iso8601
+  format: iso8601
   description: Time for last hmi action, formatted according to ISO 8601 with UTC time zone.
 
 HMI.DisplayOffDuration:

spec/Powertrain/TractionBattery.vspec

@@ -21,7 +21,7 @@ Id:
 ProductionDate:
   datatype: string
   type: attribute
-  unit: iso8601
+  format: iso8601
   description: Production date of battery in ISO8601 format, e.g. YYYY-MM-DD.
 
 ErrorCodes:
@@ -634,7 +634,7 @@ Charging.Timer.Mode:
 Charging.Timer.Time:
   datatype: string
   type: actuator
-  unit: iso8601
+  format: iso8601
   description: Time for next charging-related action, formatted according to ISO 8601 with UTC time zone.
                Value has no significance if Charging.Timer.Mode is 'inactive'.
 

spec/Powertrain/TractionBattery/BatteryConditioning.vspec

@@ -64,15 +64,15 @@ BatteryConditioning.StartTime:
   datatype: string
   description: Start time for battery conditioning,
                formatted according to ISO 8601 with UTC time zone.
-  unit: iso8601
+  format: iso8601
   comment: If the vehicle is asleep, this is the time the vehicle and the battery conditioning system must wake up
           and start monitoring the battery and if necessary start heating/cooling of the battery.
 
 BatteryConditioning.TargetTime:
   type: actuator
   datatype: string
   description: Target time when conditioning shall be finished, formatted according to ISO 8601 with UTC time zone.
-  unit: iso8601
+  format: iso8601
   comment: For FAST_CHARGING mode this is typically the time when charging is supposed to start.
            For DRIVING mode this is typically the expected departure time.
            Battery conditioning will be deactivated when this time has passed.

spec/Vehicle/Vehicle.vspec

@@ -97,7 +97,7 @@ VehicleIdentification.BodyType:
 VehicleIdentification.DateVehicleFirstRegistered:
   datatype: string
   type: attribute
-  unit: iso8601
+  format: iso8601
   description: The date in ISO 8601 format of the first registration of the vehicle with the respective public authorities.
 
 VehicleIdentification.LicensePlate:
@@ -114,19 +114,19 @@ VehicleIdentification.MeetsEmissionStandard:
 VehicleIdentification.ProductionDate:
   datatype: string
   type: attribute
-  unit: iso8601
+  format: iso8601
   description: The date in ISO 8601 format of production of the item, e.g. vehicle.
 
 VehicleIdentification.PurchaseDate:
   datatype: string
   type: attribute
-  unit: iso8601
+  format: iso8601
   description: The date in ISO 8601 format of the item e.g. vehicle was purchased by the current owner.
 
 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).
 
 VehicleIdentification.VehicleConfiguration:
@@ -221,7 +221,7 @@ StartTime:
   datatype: string
   type: attribute
   default: '0000-01-01T00:00Z'
-  unit: iso8601
+  format: iso8601
   description: Start time of current or latest trip, formatted according to ISO 8601 with UTC time zone.
   comment: This signal is supposed to be set whenever a new trip starts.
            A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode).
@@ -452,7 +452,7 @@ CurrentLocation:
 CurrentLocation.Timestamp:
   datatype: string
   type: sensor
-  unit: iso8601
+  format: iso8601
   description: Timestamp from GNSS system for current location, formatted according to ISO 8601 with UTC time zone.
 
 CurrentLocation.Latitude:

spec/formats.yaml

@@ -0,0 +1,15 @@
+unix-time:
+  description: Unix time in seconds
+  allowed-datatypes: ['uint32','uint64','int64']
+unix-time-ms:
+  description: Unix time in milliseconds
+  allowed-datatypes: ['uint32','uint64','int64']
+iso8601:
+  description: Date and Time expressed as a string according to ISO 8601
+  allowed-datatypes: ['string']
+ipv4:
+  description: Internet Protocol version 4
+  allowed-datatypes: ['string']
+ipv6:
+  description: Internet Protocol version 6
+  allowed-datatypes: ['string']

spec/units.yaml

@@ -214,19 +214,6 @@ years:
   quantity: duration
   allowed-datatypes: ['numeric']
 
-# Datetime
-
-unix-time:
-  definition: Number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970
-  unit: UNIX Timestamp
-  quantity: datetime
-  allowed-datatypes: ['uint32','uint64','int64']
-iso8601:
-  definition: Date and Time expressed as a string according to ISO 8601
-  unit: ISO 8601
-  quantity: datetime
-  allowed-datatypes: ['string']
-
 # Pressure
 
 mbar: