{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://boston-energy-atlas.org/schema/dataset.schema.json",
  "title": "Dataset entry",
  "description": "A documented table or layer. The atom of the atlas's data layer. A dataset entry is not the data — it is the account of the data, and it is required before the data is publishable.",
  "type": "object",
  "required": [
    "type",
    "id",
    "title",
    "summary",
    "grain",
    "eras",
    "tier",
    "sources",
    "provenance",
    "rights",
    "limitations",
    "domain"
  ],
  "properties": {
    "type": {
      "const": "dataset"
    },
    "id": {
      "$ref": "common.schema.json#/$defs/id"
    },
    "title": {
      "type": "string"
    },
    "summary": {
      "type": "string",
      "description": "One or two sentences. What it is and why it is in the atlas."
    },
    "status": {
      "$ref": "common.schema.json#/$defs/status"
    },
    "grain": {
      "$ref": "common.schema.json#/$defs/grain"
    },
    "grain_note": {
      "type": "string",
      "description": "Anything the grain enum flattens — e.g. that a feeder layer reports at the circuit but the constraint is enforced at the substation."
    },
    "geometry": {
      "$ref": "common.schema.json#/$defs/geometry_type"
    },
    "coverage": {
      "type": "string",
      "description": "The spatial extent actually present in the file, not the extent the source offers."
    },
    "temporal": {
      "type": "string",
      "description": "The period the data describes, e.g. '2000–2023' or 'snapshot, September 2026'."
    },
    "eras": {
      "$ref": "common.schema.json#/$defs/eras"
    },
    "tier": {
      "$ref": "common.schema.json#/$defs/tier"
    },
    "file": {
      "type": "string",
      "description": "Path to the published file, relative to the site root — a stable URL anyone may fetch. Omitted for a dataset the atlas documents but does not serve."
    },
    "repo_path": {
      "type": "string",
      "description": "Path within the repository for material held in the research record but not served as an atlas layer — typically because the rights position is 'unclear' and the charter treats that as 'no'. The entry then carries the source URL and the fetch method so the file can be rebuilt rather than redistributed."
    },
    "format": {
      "type": "string",
      "enum": [
        "geojson",
        "csv",
        "json",
        "none"
      ]
    },
    "record_count": {
      "type": "integer",
      "description": "Filled by the build from the file itself. Never hand-entered."
    },
    "bytes": {
      "type": "integer",
      "description": "Filled by the build."
    },
    "fields": {
      "type": "array",
      "description": "Every column in the published file, with its unit. A field without a unit is a field nobody can use.",
      "items": {
        "type": "object",
        "required": [
          "name",
          "description"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "tier": {
            "$ref": "common.schema.json#/$defs/tier"
          },
          "derived": {
            "type": "boolean",
            "description": "True where this project computed the field rather than receiving it."
          }
        },
        "additionalProperties": false
      }
    },
    "sources": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "common.schema.json#/$defs/source"
      }
    },
    "provenance": {
      "$ref": "common.schema.json#/$defs/provenance"
    },
    "rights": {
      "$ref": "common.schema.json#/$defs/rights"
    },
    "limitations": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "common.schema.json#/$defs/limitation"
      },
      "description": "At least one. A dataset with no stated limitation has not been examined."
    },
    "related": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/entry_ref"
      }
    },
    "crosswalks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Crosswalk files that join this dataset to another grain."
    },
    "domain": {
      "type": "string",
      "description": "The catalogue domain the dataset belongs to — exactly one, from site/atlas/domains.json.",
      "enum": [
        "wires",
        "regional-system",
        "buildings",
        "distributed-energy",
        "compute",
        "people-jurisdictions",
        "historical-record"
      ]
    }
  },
  "additionalProperties": false
}