{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://oceanmetrics.io/schemas/values-provenance/v1.0.0/schema.json",
  "title": "Provenance of one contract values file (contract 1.2.0)",
  "description": "Contract 1.2.0. JSON stored in the Parquet key-value metadata of every values file under the key `om:provenance`: where the values came from, how they were derived, by which code and when. From contract 1.2 `dataset` (the original dataset) is required, every source may name the STAC item that describes it (`item`) and its `role`, and at least one source has the role `data` (a rule om_extract.contract checks). A 1.1.x file stays valid without them.",
  "type": "object",
  "required": [
    "contract",
    "indicator",
    "coll",
    "producer",
    "sources",
    "method",
    "code",
    "created",
    "license",
    "rows"
  ],
  "properties": {
    "contract": {
      "description": "Version of the value contract the file follows (semver; this schema is 1.x). Files of 1.2.x and later must carry `dataset`.",
      "type": "string",
      "pattern": "^1\\.\\d+\\.\\d+$"
    },
    "indicator": {
      "type": "string"
    },
    "coll": {
      "type": "string"
    },
    "producer": {
      "description": "The producer whose published output the values come from.",
      "type": "object",
      "required": [
        "name",
        "url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "examples": [
            "erddap-places",
            "obisindicators",
            "places/proto/eez_indicators"
          ]
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "version": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "sources": {
      "description": "The published inputs read, one entry per input (a STAC item, a parquet, a JSON). Enough to fetch exactly what was read.",
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated": {
            "type": [
              "string",
              "null"
            ],
            "description": "The input's own updated/created stamp, when it has one."
          },
          "end_datetime": {
            "type": [
              "string",
              "null"
            ],
            "description": "Last time step the input covers."
          },
          "checksum": {
            "type": [
              "string",
              "null"
            ],
            "description": "multihash or sha256 of the input, when known."
          },
          "item": {
            "description": "Contract 1.2. URL of the STAC Item that describes this source file, or null when none exists.",
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "description": "Contract 1.2. What the source is: `data` (values read; the default when absent), `geometry` (the place polygon), `product` (the upstream product page) or `manifest` (a release listing). At least one source has the role `data`.",
            "enum": [
              "data",
              "geometry",
              "product",
              "manifest"
            ],
            "default": "data"
          }
        },
        "additionalProperties": false
      }
    },
    "source_version": {
      "description": "One line naming the upstream snapshot or release (e.g. 'OBIS snapshot 2026-10-11', 'gazetteer/stats updated 2026-10-19T20:59:51Z').",
      "type": [
        "string",
        "null"
      ]
    },
    "method": {
      "description": "How the rows were derived from the sources, in one or two sentences.",
      "type": "string",
      "minLength": 10
    },
    "code": {
      "type": "object",
      "required": [
        "name",
        "version",
        "adapter"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "commit": {
          "type": [
            "string",
            "null"
          ]
        },
        "adapter": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "created": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
    },
    "license": {
      "description": "SPDX licence of the values (the derived product), e.g. CC-BY-4.0. Upstream credit is carried in the manifest.",
      "type": "string"
    },
    "rows": {
      "type": "integer",
      "minimum": 0
    },
    "dataset": {
      "description": "The original dataset the values were derived from, as the producer states it (contract 1.2: required on every file; 1.1: optional, for producers without a STAC collection to read it from). The manifest prefers it over any lookup.",
      "type": "object",
      "required": [
        "id",
        "title",
        "providers",
        "license"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "via": {
          "type": [
            "string",
            "null"
          ]
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "roles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "url": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "license": {
          "type": "string"
        },
        "citation": {
          "type": [
            "string",
            "null"
          ]
        },
        "doi": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "if": {
    "properties": {
      "contract": {
        "type": "string",
        "pattern": "^1\\.[2-9]\\."
      }
    },
    "required": [
      "contract"
    ]
  },
  "then": {
    "required": [
      "dataset"
    ]
  }
}
