Proposal for creating specification for metadata property embedded in observation

metadata-v2.js

const observation = {
  metadata: {
    // add version property to support backwards compatibility in the UI
    version: 2,
    xyz: "valid tms url or url that resolves to a valid tms url",
    // sometimes an observation is a rolled up average of nearby sensors.
    // In this case, we need access to each of those sensors and sometimes we need access to hourly readings from
    // those sensors to power interactive charts. we should keep all nearby sensor readings flat
    // and use sensor_id property in order to group them when we // want to render a time series chart
    composites: {
      // sometimes we want to customize the tooltip that is activated by hovering individual
      // readings ( rendered on map ) in the readings array. how do we create a specification for what to show
      // in the tooltip for arbitrary readings in the readings array?
      hightlights: [
        {
          field_name: "Emission rate",
          value_field: "value", // value key/value pair MUST exist on every reading in readings array,
          field_units: "kg/hr",
        },
        {
          field_name: "Sensor distance",
          value_field: "distance_from_site_centroid", // "distance_from_site_centroid" key/value pair MUST exist on every reading in readings array,
          field_units: "kilometers",
        },
      ],
      readings: [
        {
          sensor_name: "goonyella sensor #2",
          sensor_id: 12345,
          timestamp: "ISO timestamp",
          value: 123,
          distance_from_site_centroid: 2,
          units: "kg/hr",
        },
      ],
    },
    // sometimes we use metadata property to include meta information about the value itself.
    // like how certain we are about the value... should we create a new property called
    // "calculation" where we group such meta value properties?
    calculation: {
      uncertainty: 25,
      uncertainty_percentage: 5,
    },
    // sometimes we want to create a hovered observation tooltip containing arbitray number of lines of stats
    // that are loosely related to an observation's value. we should create an array of fields and values
    // with their titles, values, and optional units so a UI developer can loop through them and create a line <br />
    // in the tooltip programatically
    minimum_reading: 45,
    maximum_reading: 500,
    highlights: [
      {
        field_name: "mininum reading",
        // minimum_reading key/value pair MUST exist on root level of metadata
        value_field: "minimum_reading",
        field_units: "kg/hr",
      },
      {
        field_name: "maximum reading",
        value_field: "maximum_reading", // maximum key/value pair MUST exist on root level of metadata,
        field_units: "kg/hr",
      },
    ],
  },
};