refine metadata

Signed-off-by: Timm Ruppert <timm.ruppert@persival.de>

Author: TimmRuppert

doc/architecture/trace_file_mcap_format.adoc

@@ -9,6 +9,8 @@ endif::[]
 - Must allow other non-OSI data to be present in the MCAP file
 - Message records must be written into `chunk records` for indexed files
 - Only OSI top-level messages containing a timestamp field are permitted to be directly stored in MCAP channels
+- Must contain only a single scenario with a unique global time
+- A MCAP file is condidered a single dataset
 
 == Schema
 - `name` field: Full message type name, including package (e.g., `osi3.SensorData`)
@@ -32,14 +34,30 @@ endif::[]
   - Must be in nanoseconds
 
 
-== Metadata
+== File-wide Metadata
 - Must include metadata with the name `versions` containing at least the following key-value pairs:
   * `osi`: SemVer version of the minimum required OSI version
-- Must include metadata with the name `creation_date` containing at least the following key-value pairs:
-  * `timestamp`: ISO 8601 formatted creation time
-- Must include metadata with the name `description` containing at least the following key-value pairs:
-  * `text`: Scenario description
-- Additional custom metadata may be added
+- Must include metadata with the name `asam_osi` containing at least the following key-value pairs:
+  * `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario
+  * `timestamp`: ISO 8601 YYYYMMDDThhmmss.f formatted creation time of the file 
+- It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs:
+  * `description`: Short human-readable scenario description
+  * `creator`: csv of person or company (not tool) creating the file
+  * 'license' csv of spdx identifiers
+  * 'data_sources' csv of model, scenario player, etc.
+- Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadate. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given:
+  - GAIA-X4PLC-AAD SHACL Shape
+    - Assume you want to embed the hdmap of a scenario in the MCAP file.
+    - The `context` category contains the key `GAIA-X4PLC-AAD-hdmap ` with the value `https://github.com/GAIA-X4PLC-AAD/ontology-management-base/blob/main/hdmap/hdmap_shacl.ttl`
+    - A channel metadata contains the key `GAIA-X4PLC-AAD-hdmap` with the value of the hdmap data in the given SHACLE shape.
+  - openDrive Reference
+    - Assume you want to express that oncoming traffic passes on the right side of the road.
+    - The `context` category contains the key `openDrive` with the value `https://publications.pages.asam.net/standards/ASAM_OpenDRIVE/ASAM_OpenDRIVE_Specification/1.8.1/specification/index.html`
+    - A file metadata in a new metadata category with the arbitrary name `specification` contains the key `openDrive-road-rule` with the value `RHT`
+  - Cycle time variation of a sensor
+    - Assume you want to express the interface cycle time variation of a sensor.
+    - The `context` category contains the key `iso_23150` with the value` ISO 23150:2011`
+    - A channel containing `OSI3::SensorData` messages has metadata with the key `iso_23150-cycle-time-variation:` and the value `80`
 
 == Compression
 - OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd`
@@ -65,7 +83,7 @@ When not using an optional field, the corresponding `_` delimiter must be omitte
 |An optional prefix which may be used to specify the type of scenario (e.g. `cut-in`) or uniqueness of the setup (e.g. `target-5m`). May not contain any `_` characters.
 
 |opt. timestamp
-|Defines the absolute start time for a scenario or recording. If following the recommended zero time for the timestamps of the top-level message, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601].
+|Defines the absolute start time for a scenario or recording. If following the recommended zero time for the timestamps of the top-level messages, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601].
 
 
 |type