{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://boston-energy-atlas.org/schema/decision.schema.json",
  "title": "Decision entry",
  "description": "A dated act by a named body that accommodated a load. This is the atlas's original entry type: it is what converts 'here is data about energy' into 'here is how the energy system gets decided'. The required fields enforce one discipline in particular — a decision may not be published without saying who paid.",
  "type": "object",
  "required": ["type", "id", "title", "date", "body", "what_was_decided", "what_it_enabled", "who_paid", "citation", "eras", "tier", "sources"],
  "properties": {
    "type": { "const": "decision" },
    "id": { "$ref": "common.schema.json#/$defs/id" },
    "title": { "type": "string" },
    "status": { "$ref": "common.schema.json#/$defs/status" },

    "date": {
      "type": "string",
      "description": "The operative date or dates, as free text because real instruments have several — filed, ordered, effective, superseded. Machine-readable extremes go in date_start and date_end."
    },
    "date_start": { "type": "string", "description": "ISO year or date, for sorting and for the time axis." },
    "date_end": { "type": "string" },

    "body": {
      "type": "string",
      "description": "The body that acted, named — and where the individuals are on the instrument, the individuals. A decision made by 'the state' is not yet a decision entry."
    },
    "instrument": {
      "type": "string",
      "enum": ["statute", "order", "tariff", "franchise", "rate-schedule", "agreement", "regulation", "settlement", "executive-order", "none"],
      "description": "What kind of act it was. 'none' is reserved for the case the atlas most wants to record: a decision that was never written down. See absence."
    },

    "what_was_decided": { "type": "string" },
    "what_it_enabled": { "type": "string" },
    "who_paid": {
      "type": "string",
      "description": "Required, and the point of the entry type. Where the instrument does not allocate the cost, say so — an unallocated cost is a finding, not a blank."
    },
    "absence": {
      "type": "string",
      "description": "Where the decision consists of something NOT being decided — no allowance formula, no obligation, no rule for a class of customer — describe the absence and what was searched to establish it. An absence claim requires the search to be stated."
    },

    "citation": {
      "type": "string",
      "description": "Full legal citation, sufficient to retrieve the instrument without this atlas."
    },
    "primary_text_url": { "type": "string" },
    "primary_text_read": {
      "type": "boolean",
      "description": "Whether the primary instrument itself was opened and read. This is the difference between verified and secondary and is recorded separately so it cannot be blurred."
    },

    "eras": { "$ref": "common.schema.json#/$defs/eras" },
    "tier": { "$ref": "common.schema.json#/$defs/tier" },
    "geography": {
      "type": "string",
      "description": "Where it applied: the Commonwealth, the City of Boston, one service territory, one rate class."
    },

    "sources": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "common.schema.json#/$defs/source" }
    },
    "open_items": {
      "type": "array",
      "items": { "type": "string" },
      "description": "What is not yet established about this decision, specifically enough for someone else to close it."
    },
    "related": {
      "type": "array",
      "items": { "$ref": "common.schema.json#/$defs/entry_ref" }
    },
    "reading": {
      "type": "string",
      "description": "Where this decision appears in a narrative reading, e.g. 'loads#ch7'."
    }
  },
  "additionalProperties": false
}