{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schoolsnearme.co.nz/api/schema.json",
  "title": "Schoolsnearme — per-school facts.json",
  "description": "JSON contract for /api/school/{slug}/facts.json. Free-tier surface: identity + latest-point ERO + latest audited financial + active intervention + tags + suburb link + international programme. Multi-year trajectory + diff narratives are Pro tier.",
  "type": "object",
  "required": [
    "schema_version",
    "school"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "1.0"
    },
    "school": {
      "type": "object",
      "required": [
        "id",
        "slug",
        "name",
        "type",
        "authority"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "NZ Ministry of Education school ID"
        },
        "slug": {
          "type": "string",
          "description": "URL-safe school identifier"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "description": "e.g. Composite, Contributing, Secondary (Year 9-15)"
        },
        "authority": {
          "type": "string",
          "enum": [
            "State",
            "State Integrated",
            "Private",
            "Partnership Schools Kura Hourua"
          ]
        },
        "gender": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "Co-Educational",
            "Boys",
            "Girls",
            null
          ]
        },
        "address": {
          "type": [
            "string",
            "null"
          ]
        },
        "suburb": {
          "type": [
            "string",
            "null"
          ]
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "description": "Region name in English"
        },
        "region_mi": {
          "type": [
            "string",
            "null"
          ],
          "description": "Region name in te reo Māori"
        },
        "region_raw": {
          "type": [
            "string",
            "null"
          ],
          "description": "Raw region label from source data"
        },
        "latitude": {
          "type": [
            "number",
            "null"
          ]
        },
        "longitude": {
          "type": [
            "number",
            "null"
          ]
        },
        "website": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "total_roll": {
          "type": [
            "integer",
            "null"
          ]
        },
        "eqi": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Equity Index — higher = more socio-economic disadvantage"
        },
        "open_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "ethnicity_breakdown": {
          "type": "object",
          "description": "Percentage of total roll. Sums to ~100.",
          "properties": {
            "european_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "maori_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "pacific_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "asian_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "other_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "international_pct": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        }
      }
    },
    "latest_ero_review": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "review_date": {
          "type": "string",
          "format": "date"
        },
        "report_type": {
          "type": "string"
        },
        "author": {
          "type": [
            "string",
            "null"
          ]
        },
        "regional_office": {
          "type": [
            "string",
            "null"
          ]
        },
        "composite_score": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "maximum": 100
        },
        "key_findings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 5
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "latest_financial": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "year_ended": {
          "type": "string",
          "format": "date"
        },
        "audit_opinion": {
          "type": [
            "string",
            "null"
          ]
        },
        "total_revenue_nzd": {
          "type": [
            "number",
            "null"
          ]
        },
        "surplus_deficit_nzd": {
          "type": [
            "number",
            "null"
          ]
        },
        "net_assets_equity_nzd": {
          "type": [
            "number",
            "null"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "active_intervention": {
      "type": [
        "object",
        "null"
      ],
      "description": "MoE statutory intervention currently in force (Limited Statutory Manager, Commissioner, etc.).",
      "properties": {
        "intervention_type": {
          "type": "string"
        },
        "appointed_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tag": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "cohort",
              "curriculum",
              "leadership",
              "outcomes",
              "specialty",
              "character"
            ]
          },
          "label": {
            "type": "string"
          }
        }
      }
    },
    "international_program": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "accepts_international": {
          "type": "boolean"
        },
        "sieba_member": {
          "type": "boolean"
        },
        "tuition_annual_nzd": {
          "type": [
            "integer",
            "null"
          ]
        },
        "esol_support_level": {
          "type": [
            "string",
            "null"
          ]
        },
        "boarding_available": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "year_groups": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      }
    },
    "suburb_link": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "suburb_id": {
          "type": "integer"
        },
        "live_data_url": {
          "type": "string",
          "format": "uri"
        },
        "crimestats_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "machine_readable_siblings": {
      "type": "object",
      "properties": {
        "markdown": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "licensing": {
      "type": "object",
      "properties": {
        "free_tier_disclaimer": {
          "type": "string"
        },
        "pro_tier_url": {
          "type": "string",
          "format": "uri"
        },
        "provenance_rule": {
          "type": "string"
        }
      }
    }
  }
}