{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://boston-energy-atlas.org/schema/gap.schema.json",
  "title": "Gap entry",
  "description": "A documented thing that is not published. Every atlas has these; almost none of them publish them, so the next person repeats the search. A gap entry is only worth its place if it says what was tried — an untested assumption that something is missing is not a gap, it is a guess. Read together, the gap register is a statement about what the public cannot know about its own grid.",
  "type": "object",
  "required": ["type", "id", "title", "what_is_missing", "why_it_matters", "what_was_tried", "state", "eras"],
  "properties": {
    "type": { "const": "gap" },
    "id": { "$ref": "common.schema.json#/$defs/id" },
    "title": { "type": "string" },
    "status": { "$ref": "common.schema.json#/$defs/status" },

    "what_is_missing": {
      "type": "string",
      "description": "The specific fact, field, series or layer that does not exist in public form. Specific enough that its arrival would be unambiguous."
    },
    "why_it_matters": {
      "type": "string",
      "description": "What cannot be decided, mapped or argued without it."
    },
    "what_was_tried": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string" },
      "description": "Every route attempted, named — endpoint, archive, docket, agency — and what each returned. This is the part that saves the next person the week."
    },
    "state": {
      "type": "string",
      "enum": [
        "not-published",
        "published-but-coarser",
        "access-blocked",
        "behind-paywall",
        "needs-a-person",
        "closed"
      ],
      "description": "not-published — the fact is not collected or not released in any form. published-but-coarser — it exists, at a grain too blunt for the question. access-blocked — it exists and is public but machine access is refused. behind-paywall. needs-a-person — a human action would close it. closed — it has since been closed; kept so the record shows how."
    },
    "closes_if": {
      "type": "string",
      "description": "The single action that would close this gap, addressed to whoever could take it."
    },
    "who_could_close_it": { "type": "string" },
    "workaround": {
      "type": "string",
      "description": "What the atlas uses instead, and what that substitution costs in accuracy. Where the answer is 'nothing', say so."
    },

    "eras": { "$ref": "common.schema.json#/$defs/eras" },
    "grain_wanted": { "$ref": "common.schema.json#/$defs/grain" },
    "grain_available": { "$ref": "common.schema.json#/$defs/grain" },
    "severity": {
      "type": "string",
      "enum": ["blocks-a-claim", "weakens-a-claim", "limits-resolution", "inconvenient"],
      "description": "What this gap actually costs the atlas. Ranked honestly, most gaps are the last two."
    },

    "first_recorded": { "type": "string", "format": "date" },
    "last_checked": { "type": "string", "format": "date" },
    "sources": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/source" } },
    "related": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/entry_ref" } }
  },
  "additionalProperties": false
}