{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://buildability.us/schema/104.json",
  "title": "Section 104 Public Undeveloped-Land Database",
  "description": "One document per CDBG grantee (entitlement city, urban county, or state program). A reading of 42 U.S.C. § 5304(b)(7) as amended by Public Law 119-101, published so grantees can meet the October 1, 2026 certification without inventing a format. This is not a HUD standard; adopt, narrow, or reject as your counsel advises. Released under CC0 1.0 (public domain).",
  "type": "object",
  "required": ["schemaVersion", "grantee", "methodology", "parcels"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": {
      "description": "Semantic version of this document's schema. Consumers should refuse to parse a document whose major version they do not recognise.",
      "const": "1.0.0"
    },
    "documentUrl": {
      "description": "The canonical URL where this document is published — the URL a member of the public would visit to find it. Present on the served document so consumers can detect mirroring or staleness.",
      "type": "string",
      "format": "uri"
    },
    "lastUpdatedIso": {
      "description": "ISO 8601 date this document was last generated. Grantees should regenerate whenever a parcel row changes.",
      "type": "string",
      "format": "date"
    },
    "grantee": {
      "type": "object",
      "required": ["name", "state", "granteeType"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "Public-facing grantee name, e.g. \"City of Provo\", \"Salt Lake County\", \"State of Utah\".",
          "type": "string",
          "minLength": 1
        },
        "state": {
          "description": "Two-letter USPS state code (upper-case).",
          "type": "string",
          "pattern": "^[A-Z]{2}$"
        },
        "granteeType": {
          "description": "The CDBG grantee class this document describes. Matches HUD's formula-grant categorisation.",
          "enum": ["entitlement-city", "urban-county", "state-program"]
        },
        "hudGranteeId": {
          "description": "HUD's internal grantee identifier if the grantee has published one. Optional — omit if unknown.",
          "type": "string"
        },
        "contactEmail": {
          "description": "Public contact for corrections and questions about this database. Optional — grantees may direct to a web form instead.",
          "type": "string",
          "format": "email"
        },
        "contactUrl": {
          "description": "Public URL where corrections may be submitted.",
          "type": "string",
          "format": "uri"
        }
      }
    },
    "methodology": {
      "description": "How the grantee decided what to include. Section 104 does not define \"undeveloped\"; HUD has not issued implementing guidance. Grantees publish their own definition here so a reader can check the work.",
      "type": "object",
      "required": ["undevelopedDefinition", "ownershipSource", "parcelSource"],
      "additionalProperties": false,
      "properties": {
        "undevelopedDefinition": {
          "description": "The grantee's operational definition of \"undeveloped\". Free text; be specific about use codes, footprint thresholds, or other rules applied.",
          "type": "string",
          "minLength": 20
        },
        "ownershipSource": {
          "description": "How the grantee determined which parcels it owns. Typically: assessor records attributed by owner name.",
          "type": "string",
          "minLength": 3
        },
        "parcelSource": {
          "description": "Provenance of the underlying parcel data. Typically: county assessor, state cadastral system.",
          "type": "string",
          "minLength": 3
        },
        "excludedEntities": {
          "description": "Adjacent entities whose holdings sit in the same footprint but are NOT included here — the redevelopment authority, dependent housing authority, or land bank. Named so a reader sees them next to the grantee inventory rather than silently rolled in.",
          "type": "array",
          "items": {
            "type": "object",
            "required": ["name", "relationship"],
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "relationship": { "type": "string", "minLength": 3 }
            }
          }
        },
        "certifiedBy": {
          "description": "The grantee official who certified this database. Optional — recommended for the file.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": { "type": "string" },
            "title": { "type": "string" },
            "signedIso": { "type": "string", "format": "date" }
          }
        }
      }
    },
    "parcels": {
      "description": "The undeveloped parcels the grantee owns. Order is not significant to conformance; grantees may sort by acreage, score, or ID.",
      "type": "array",
      "items": { "$ref": "#/$defs/parcel" }
    }
  },
  "$defs": {
    "parcel": {
      "type": "object",
      "required": ["parcelId", "location", "acres", "ownershipEntity", "sourceUrl", "lastVerifiedIso"],
      "additionalProperties": true,
      "properties": {
        "parcelId": {
          "description": "The assessor's parcel identifier — APN, PIN, or equivalent. MUST be unique within the document.",
          "type": "string",
          "minLength": 1
        },
        "location": {
          "description": "Where the parcel sits. Address if the parcel has one; otherwise centroid latitude/longitude. At least one addressing form is required.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "address": {
              "type": "string",
              "description": "USPS-formatted street address, if the parcel has one."
            },
            "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
            "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
          },
          "anyOf": [
            { "required": ["address"] },
            { "required": ["latitude", "longitude"] }
          ]
        },
        "acres": {
          "description": "Parcel acreage. Must be a positive number.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "ownershipEntity": {
          "description": "The exact grantee-owned entity of record on the parcel — matches the owner-name string on the assessor record. Used so a reader can verify the attribution.",
          "type": "string",
          "minLength": 1
        },
        "useCode": {
          "description": "The assessor's use-code or classification (e.g. \"vacant land\", \"exempt\", \"agricultural\"). Optional but recommended — it is often the primary evidence the parcel is undeveloped.",
          "type": "string"
        },
        "zoning": {
          "description": "Current zoning designation, as the grantee's own maps show it.",
          "type": "string"
        },
        "dispositionStatus": {
          "description": "The grantee's own status for this parcel. Optional but useful for downstream readers.",
          "enum": [
            "available",
            "under-review",
            "planned-use",
            "encumbered",
            "not-for-disposition"
          ]
        },
        "buildabilityScore": {
          "description": "Optional third-party score. If present, MUST cite the scoring system and version so consumers can distinguish scores from different providers.",
          "type": "object",
          "required": ["system", "version", "score"],
          "additionalProperties": false,
          "properties": {
            "system": {
              "description": "The scoring system. e.g. \"buildability.us\" for the Buildability Score™.",
              "type": "string"
            },
            "version": { "type": "string" },
            "score": { "type": "number", "minimum": 0, "maximum": 100 },
            "grade": {
              "type": "string",
              "pattern": "^(A|B|C|D|F)[+−-]?$"
            }
          }
        },
        "sourceUrl": {
          "description": "URL of the primary record this row derives from — usually the county assessor's parcel page. Every row MUST link back to a public record a reader can verify against.",
          "type": "string",
          "format": "uri"
        },
        "lastVerifiedIso": {
          "description": "ISO 8601 date the grantee (or its designee) last verified this row against the primary source.",
          "type": "string",
          "format": "date"
        },
        "notes": {
          "description": "Free-text notes for a specific parcel — e.g. easement complications, hazard flags. Optional.",
          "type": "string"
        }
      }
    }
  }
}