DataFrames, MultiTSFrames and Series with attached Metadata¶

{
  "dataset_metadata": {
    # metadata 
    # * specific to the dataset (typically interval)
    # * what should happen during saving, in particular invalidation / deletion of existing data

    "metric_key": "id", # which key from the metric metadata identifies the metric in the
    # metric column of the dataframe. optional, if missing or none, "id" should be used.

    # "single_metric"
    # if only a single metric is present (e.g. in SERIES), this is the key
    # of the single metric occuring as single entry under "metrics" in the 
    # key specified via "metric_key".
    # This should not be present / null, if more than one metric is present!
    "single_metric": "series",

    "queried_metrics": list[str] | None = None,  # Since not all queried metrics may have
    # data in the queries interval, it may be possible that a metric entirely is missing
    # in the dataset and depending on the providing adapter even from the "metrics"
    # metadata. Therefore it should be explicitely listed which metrics where requested.

    ... # see below!

  },
  "metrics": [
    {
      "id": "abcdef-1234",
      "name": "metric1",
      "value_dimensions": [
        {
          "column": "value", # actual column name in the multitsframe. This connects the
          # value_dimension to the actual column.
          "name": "temperature"
          "unit": "°C",
          ...
        }
      ]
      ...
    },
    ...
  ],
  "value_dimensions_shared": [ 
      # fallback / default information per value dimension or metadata for value dimensions
      # that actually have the same meaning for all metrics
      {
        "column": "value", # actual column name in the multitsframe. This connects the
        # value_dimension to the actual column.
        "name": "value",
        "unit": "UNKNOWN",
        ...
      }    
      ... 
  ]
}

{
  "dataset_metadata": {
    "single_metric": "my_series",
    "metric_key": "metric"
    ...
  },
  "metrics": [
    {
      "metric": "my_series",
      "unit": "kg",
      ...
    }
  ]
}

{
  "dataset_metadata": {
    "metric_key": "external_id", # key which identifies the metric
                                 # * is expected to be used in metric column of actual dataframe
                                 # * is expected to uniquely appear in "metrics" below.
    ...
  },
  "metrics": [
    {
      "external_id": "abc.pressure",
      "name": "ABC pressure",
      ...
    },
    {
      "external_id": "abc.temp",
      "name": "ABC temperature",
      ...
    },
    ...
  ]
}

    "dataset_metadata": {
        "metric_key": ..., # as described above!
        "single_metric": ..., # as described above!
        "queried_metrics": ..., # as described above!

        # Whether the ref dataset should be considered as discrete, i.e. isolated datapoints,
        # not an interval.
        “ref_dataset_discrete“: false,
        # if set, this has higher priority than all interval settings for the ref dataset.

        # Start / End timestamps of the queried time interval in explicit UTC isoformat:
        "ref_interval_start_timestamp": "2023-01-01T00:00:00+00:00", 
        "ref_interval_end_timestamp": "2023-01-02T00:00:00+00:00",

        # Type of queried time interval (one of
        # "left_closed", "right_open", "right_closed", "left_open", "closed", or "open"):
        "ref_interval_type": "closed",

        # Define an invalidation dataset, separate from the ref dataset.
        "invalidation_interval_start": "2023-01-01T00:00:00+00:00",
        "invalidation_interval_end": "2023-01-02T00:00:00+00:00",
        # one of "left_closed", "right_open", "right_closed", "left_open", "closed", or "open":   
        "invalidation_interval_type": "closed"

        # Whether invalidation should occur. If no extra invalidation dataset is specified,
        # existing data in the time domain of the ref dataset is invalidated, else
        # existing data in the invalidation dataset is invalidated instead.
        # If no dataset is specified and there is at least one datapoint, a ref interval
        # is inferred from the provided datapoints (taking first and last and building
        # a closed interval from their timestamps, possibly with length 0). If no dataset is
        # specified and no datapoints provided, no invalidation can occur.
        "invalidate_dataset": true # Optional[bool]. Should be handled as null if missing.
        # What null means depends on the adapter: It can decide to default to invalidation or not.

        "delete_invalidated": null, # Optional[bool]. Whether invalidated data should be 
        # deleted instead. What null means depends on the adapter: It can decide to default to
        # deletion or not. If this is true or the adapter interprets null or missing as true,
        # then instead of invalidating, all data that is to be invalidated should be actually deleted.
        # If false or the adapter interprets null or missing as false, then invalidation should 
        # be applied.
        # Note that an adapter is of course allowed to simply not support deletion.

        # A common invalidation_timestamp can be specified to be applied to all invalidated
        # datapoints if invalidation occurs. If no invalidation_timestamp is send (missing or null)
        # the execution_timestamp provided as query parameter to generic rest adapter should be used
        # or if that is also not present, the adapter should calculate "now" as utc timestamp
        # when receiving the request.
        # "invalidation_timestamp": null # or valid UTC timestamp "2025-08-01T00:00:00+00:00"

        # If the following flag is true, only invalidation should occur, but new data should
        # not be stored.:
        "only_invalidate": false # should be considered false if missing.
        # Cannot be true if "invalidate_dataset" is false

        # optionally new data provided with the ref dataset can be given a
        # (for all datapoints common) invalidation date in advance:
        "new_data_invalidation_date": null # or valid UTC timestamp "2026-01-01T00:00:00+00:00"
        # if unset or null, this should be ignored. If set to a valid utc isoformat timestamp
        # it should be stored together with the new data points.
      }

  {
    "id": "some id", 
    "name": "Long name of metric",
    "display_name": "My metric", # A shorter name for labels / captions / plot titles
    "short_display_name": "my_met", # For legends in plots
    "description": "A one sentence description"
    "external_id": "unique id/key in external source systems", # often one would like
              # to use this as the identifying column entry in "metric" column of the dataframe
    "channel_id": "abc123-..." # actual platform channel id

    "inherited": { # metadata inherited from a hierarchy
      # Is there a unique parent? In der hetida.platform ja. Im virtuellen Strukturadapter: nein.
      # DEEPEST WINS LOGIC!!
      # keine ids, name, description!
      # nur dynamische Properties

      # Konventionen:
      "longitude": 42.12345, # später mal im Frontend übersetzen!
      "latitude": 66:12345,
      "elevation": 125.2
      # Wenn eine Komponente hier ein Feld erwartet was nicht auftaucht muss sie diesen
      # Fall selbstständig handeln (z.B. Default Wert nutzen!)
    },
    "hierarchy": {
      # ERSTMAL NICHT!
      # (komplette Hierarchie durchgeben)
    },
    "comments": [
      { # comments attached to metric.
        # Typicaly timestamped somehow, describing situations in the timeseries data.
        ...
      },
      ...
    ],
    "value_dimensions": [
      {
        "column": "value", # actual column name in the multitsframe. This connects the
        # value_dimension to the actual column.
        "name": "value", # or "latitude", "pressure", ... # can of course be same as column
        "short_display_name": "val", # can be missing
        "display_name": "The Value", # can be missing
        # for a SERIES or generally the case where there is only one
        # value dimension:
        # if name, display_name, short_display_name are not present here,
        # the ones from the metric itself can/should be used
        "description": "Blubbeldiblubb und so" # default: empty String ""
        "unit": "m/s",
        "value_data_type": "float",
      },
      ...
    ]
  }