{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uwmd.org/schemas/section-gaps.schema.json",
  "title": "UW Markdown Gaps Section",
  "description": "Content payload for the `gaps` standard section (UW_FORMAT_SPEC.md \u00a74.22). Enumerates open data gaps blocking stage advancement or carrying provisional defaults.",
  "type": "object",
  "required": [
    "items"
  ],
  "additionalProperties": true,
  "properties": {
    "_role": {
      "enum": [
        "primary",
        "senior",
        "junior",
        "summary",
        "detail",
        "component"
      ],
      "description": "Optional signed scalar block annotation (RFC 0040)."
    },
    "items": {
      "type": "array",
      "description": "Open gap inventory. Each entry names a missing or low-quality field, optionally with the stage it blocks and an owner.",
      "items": {
        "type": "object",
        "required": [
          "section",
          "reason"
        ],
        "additionalProperties": true,
        "properties": {
          "section": {
            "type": "string",
            "description": "Section ID where the gap lives."
          },
          "field_path": {
            "type": "string",
            "description": "Optional dot-notated path within the section's content. When omitted, the gap applies to the whole section."
          },
          "reason": {
            "enum": [
              "missing",
              "illegible",
              "out_of_scope",
              "deferred",
              "blocked_by_dependency",
              "awaiting_external"
            ],
            "description": "Why this gap exists. `missing` and `illegible` typically come from L0 ingestion; `awaiting_external` is used for third-party reports."
          },
          "blocks_stage": {
            "enum": [
              "scope",
              "screening",
              "term_sheet",
              "full_underwrite",
              "credit_approval",
              "closing",
              "monitoring"
            ],
            "description": "Lowest stage that cannot advance until this gap closes."
          },
          "first_seen": {
            "type": "string",
            "format": "date-time",
            "description": "When this gap was first recorded."
          },
          "last_checked": {
            "type": "string",
            "description": "RFC 0122: DQ-05 reads a calendar-valid YYYY-MM-DD at UTC midnight or YYYY-MM-DDTHH:mm[:ss[.1-3 digits]] with uppercase Z or signed HH:mm offset. Years 0001-9999, hours/offset hours 00-23, minutes/seconds 00-59. Invalid strings do not establish staleness; no host-local parsing.",
            "pattern": "^(?!0000)(?:[0-9]{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12][0-9]|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-8]))|(?:[0-9]{2}(?:0[48]|[2468][048]|[13579][26])|(?:[02468][048]|[13579][26])00)-02-29)(?:T(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\\.[0-9]{1,3})?)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9]))?$(?![\\s\\S])"
          },
          "owner": {
            "type": "string",
            "description": "Actor or agent responsible for resolving the gap."
          },
          "note": {
            "type": "string",
            "description": "Free-text context."
          }
        }
      }
    },
    "summary": {
      "type": "object",
      "description": "Aggregate counts for fast pipeline routing. Recomputed on every gap maintenance write.",
      "additionalProperties": false,
      "properties": {
        "total_open": {
          "type": "integer",
          "minimum": 0
        },
        "blocking_current_stage": {
          "type": "integer",
          "minimum": 0
        },
        "blocking_next_stage": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "examples": [
    {
      "items": [
        {
          "section": "rent_roll",
          "reason": "missing",
          "blocks_stage": "screening",
          "first_seen": "2026-04-25T10:00:00Z",
          "last_checked": "2026-04-27T09:00:00Z",
          "owner": "agent/scope-reviewer",
          "note": "Awaiting unit-level rent roll from broker."
        },
        {
          "section": "noi_model",
          "field_path": "expense_ratio",
          "reason": "deferred",
          "blocks_stage": "full_underwrite",
          "owner": "manual",
          "note": "Using asset-class default until T-12 arrives."
        }
      ],
      "summary": {
        "total_open": 2,
        "blocking_current_stage": 1,
        "blocking_next_stage": 1
      }
    }
  ]
}
