{
 "openapi": "3.1.0",
 "info": {
  "title": "Deep Almanac: Victorian government school performance",
  "version": "1.0.0",
  "summary": "Performance Summary measures for every Victorian government secondary school, keyed on school number, with the Department of Education's own Similar Schools comparison.",
  "description": "Every Victorian government school publishes an Annual Report to the School Community whose Performance Summary is generated by the Department of Education: SFOE band, enrolment profile, NAPLAN proficiency and relative growth, VCE completion and mean study score, real retention, exits to further study or full-time work, attendance and the parent, staff and student survey measures. Each measure is published for the School, for the Department's Similar Schools group and for the State, so a school can be compared with schools of similar intake rather than with the whole state.\n\nSchools: 1575. Report years: 2023, 2024, 2025.\n\nEvery file is static JSON; no authentication, no rate limits beyond ordinary CDN behaviour, CORS open. This is reference data, not advice about where to enrol a child.",
  "termsOfService": "https://deepalmanac.com/terms",
  "contact": {
   "name": "Deep Almanac",
   "url": "https://deepalmanac.com"
  },
  "license": {
   "name": "School Locations is published by the Victorian Department of Education on DataVic under the Creative Commons Attribution 4.0 International licence. The Performance Summary measures are reproduced from each school's Annual Report to the School Community, published by the school and the Department of Education through the VRQA State Register, with the school number, report year and source document recorded on every record. Figures are the Department's own published values and are not recalculated here, beyond the stated averages of a school's gap to its Similar Schools group. A school's results reflect its students and circumstances; this is reference data, not advice about where to enrol a child.",
   "url": "https://deepalmanac.com/terms"
  }
 },
 "servers": [
  {
   "url": "https://deepalmanac.com"
  }
 ],
 "security": [],
 "tags": [
  {
   "name": "vic-schools",
   "description": "Victorian government school performance",
   "externalDocs": {
    "description": "Page",
    "url": "https://deepalmanac.com/au/education/vic-schools/"
   }
  }
 ],
 "paths": {
  "/au/education/vic-schools/v1/index.json": {
   "get": {
    "tags": [
     "vic-schools"
    ],
    "operationId": "getVicSchoolsIndex",
    "summary": "Dataset index",
    "description": "Lists the dataset files, every school with its page and JSON URL, the measures published and the source documents.",
    "responses": {
     "200": {
      "description": "Dataset index.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VicSchoolsIndex"
        }
       }
      }
     },
     "404": {
      "description": "The file has not been published yet or the path is wrong; static hosting returns the site's 404 page (HTML)."
     }
    }
   }
  },
  "/au/education/vic-schools/v1/schools.json": {
   "get": {
    "tags": [
     "vic-schools"
    ],
    "operationId": "getVicSchools",
    "summary": "Every school",
    "description": "Every school with its register identity, enrolment profile and all Performance Summary measures.",
    "responses": {
     "200": {
      "description": "Every school.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VicSchools"
        }
       }
      }
     },
     "404": {
      "description": "The file has not been published yet or the path is wrong; static hosting returns the site's 404 page (HTML)."
     }
    }
   }
  },
  "/au/education/vic-schools/v1/rankings.json": {
   "get": {
    "tags": [
     "vic-schools"
    ],
    "operationId": "getVicSchoolRankings",
    "summary": "Every ranking",
    "description": "Rankings under `tables.secondary` and `tables.primary`, each an ordered list of schools. Secondary: similar_schools_adjusted, similar_schools_index, study_score, vce_completion, retention, exits, naplan_year_9, wellbeing, attendance, enrolment_growth, study_scores_40_plus, median_study_score, parent_satisfaction, staff_climate, similar_schools_advantage. Primary: similar_schools_adjusted, similar_schools_index, naplan_year_5, naplan_year_3, naplan_growth_3_5, teacher_judgement_primary, wellbeing, attendance, enrolment_growth, parent_satisfaction, staff_climate, similar_schools_advantage. A combined (P-12) school appears in both.",
    "responses": {
     "200": {
      "description": "Every ranking.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VicSchoolRankings"
        }
       }
      }
     },
     "404": {
      "description": "The file has not been published yet or the path is wrong; static hosting returns the site's 404 page (HTML)."
     }
    }
   }
  },
  "/au/education/vic-schools/v1/schools/{school_no}.json": {
   "get": {
    "tags": [
     "vic-schools"
    ],
    "operationId": "getVicSchool",
    "summary": "One school",
    "description": "One school's full record under `school`, addressed by its Department of Education school number, with the dataset's provenance alongside it.",
    "responses": {
     "200": {
      "description": "One school.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VicSchoolFile"
        }
       }
      }
     },
     "404": {
      "description": "The file has not been published yet or the path is wrong; static hosting returns the site's 404 page (HTML)."
     }
    },
    "parameters": [
     {
      "name": "school_no",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Department of Education school number, as listed in index.json.",
      "example": "1886"
     }
    ]
   }
  },
  "/au/education/vic-schools/v1/openapi.json": {
   "get": {
    "tags": [
     "vic-schools"
    ],
    "operationId": "getVicSchoolsOpenapi",
    "summary": "This document",
    "description": "OpenAPI 3.1 description of this dataset's files (https://deepalmanac.com/openapi.json lists every dataset's document).",
    "responses": {
     "200": {
      "description": "This document.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VicSchoolsIndex"
        }
       }
      }
     },
     "404": {
      "description": "The file has not been published yet or the path is wrong; static hosting returns the site's 404 page (HTML)."
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "VicSchoolSeniorSecondary": {
    "type": "object",
    "description": "One year of VCAA senior secondary results for a school, with the evidence for the link.",
    "properties": {
     "median_study_score": {
      "type": [
       "number",
       "null"
      ],
      "description": "Median VCE study score; the state-wide average is 30."
     },
     "study_scores_40_plus_percent": {
      "type": [
       "number",
       "null"
      ],
      "description": "Share of this school's study scores at 40 or above."
     },
     "satisfactory_vce_completions_percent": {
      "type": [
       "number",
       "null"
      ]
     },
     "vtac_applications_percent": {
      "type": [
       "number",
       "null"
      ],
      "description": "Share of VCE students applying for tertiary places through VTAC; a low figure marks a school whose senior students mostly take vocational pathways."
     },
     "vce_students": {
      "type": [
       "number",
       "null"
      ]
     },
     "vcaa_school": {
      "type": "string",
      "description": "The school's name as SSCAI writes it."
     },
     "match_score": {
      "type": "number",
      "description": "0-1 confidence of the name match to VCAA's provider list; the step from there to the school number is an exact phone match."
     },
     "completion_agreement": {
      "type": [
       "number",
       "null"
      ],
      "description": "SSCAI's satisfactory-completion percentage minus the Annual Report's completion rate for the same year, as a check on the link. Null when either is suppressed or the report covers another year. Small values confirm the link; the two measures are defined slightly differently, so they are close, not identical."
     }
    }
   },
   "VicSchoolReading": {
    "type": "object",
    "description": "One reading of a measure: the school's value and, where the Department publishes them, its Similar Schools group and the state. `suppressed` explains a withheld school value.",
    "properties": {
     "school": {
      "type": "number"
     },
     "similar_schools": {
      "type": "number"
     },
     "state": {
      "type": "number"
     },
     "suppressed": {
      "type": "string"
     }
    }
   },
   "VicSchool": {
    "type": "object",
    "description": "One Victorian school: register identity, enrolment profile and the Performance Summary measures from its Annual Report, each with the school's, its Similar Schools group's and the state's value.",
    "properties": {
     "school_no": {
      "type": "string",
      "description": "Department of Education school number; the key for this dataset."
     },
     "school_name": {
      "type": "string"
     },
     "slug": {
      "type": "string",
      "description": "URL segment used by this school's page."
     },
     "sector": {
      "type": "string",
      "enum": [
       "Government",
       "Catholic",
       "Independent"
      ]
     },
     "school_type": {
      "type": "string",
      "description": "Secondary, Pri/Sec, Primary, Special or Language."
     },
     "suburb": {
      "type": "string"
     },
     "postcode": {
      "type": "string"
     },
     "state": {
      "type": "string"
     },
     "address": {
      "type": "string"
     },
     "phone": {
      "type": "string"
     },
     "region": {
      "type": "string"
     },
     "area": {
      "type": "string"
     },
     "lga": {
      "type": "string"
     },
     "metro": {
      "type": "boolean",
      "description": "True when the school's local government area is metropolitan."
     },
     "latitude": {
      "type": [
       "number",
       "null"
      ]
     },
     "longitude": {
      "type": [
       "number",
       "null"
      ]
     },
     "report_year": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Year of the Annual Report these measures come from."
     },
     "website": {
      "type": [
       "string",
       "null"
      ],
      "format": "uri",
      "description": "The school's own website, as given in its Annual Report. Null where the report does not name one; it is not in the school register."
     },
     "profile": {
      "type": "object",
      "properties": {
       "sfoe_band": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "Low",
         "Low-Medium",
         "Medium",
         "High",
         null
        ],
        "description": "Student Family Occupation and Education band: the Department's measure of socio-educational disadvantage, Low (least) to High (most)."
       },
       "enrolments": {
        "type": [
         "integer",
         "null"
        ]
       },
       "enrolment_year": {
        "type": [
         "integer",
         "null"
        ]
       },
       "enrolments_female": {
        "type": [
         "integer",
         "null"
        ]
       },
       "enrolments_male": {
        "type": [
         "integer",
         "null"
        ]
       },
       "english_additional_language_percent": {
        "type": [
         "number",
         "null"
        ]
       },
       "aboriginal_torres_strait_islander_percent": {
        "type": [
         "number",
         "null"
        ]
       },
       "single_sex": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "girls",
         "boys",
         null
        ],
        "description": "Read from the enrolment counts, not from the school's wording."
       }
      }
     },
     "measures": {
      "type": "object",
      "description": "Keyed by measure (see `measures` in index.json). Each holds `year`, `average_years` and the `latest` and `average` readings; each reading carries `school`, `similar_schools` and `state` where the Department publishes them, or `suppressed` with the reason when a school's value is withheld.",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "year": {
         "type": [
          "integer",
          "null"
         ]
        },
        "average_years": {
         "type": [
          "integer",
          "null"
         ]
        },
        "latest": {
         "$ref": "#/components/schemas/VicSchoolReading"
        },
        "average": {
         "$ref": "#/components/schemas/VicSchoolReading"
        }
       }
      }
     },
     "attendance_rate": {
      "type": "object",
      "description": "Attendance rate by year level (percent), keyed prep, year_7 ... year_12.",
      "additionalProperties": {
       "type": "number"
      }
     },
     "similar_schools_advantage": {
      "type": [
       "number",
       "null"
      ],
      "description": "Mean gap in percentage points between this school and its Similar Schools group across the comparable measures; null when fewer than 6 are published."
     },
     "similar_schools_adjusted": {
      "type": [
       "number",
       "null"
      ],
      "description": "similar_schools_advantage scaled by similar_schools_reliability, so a small school's figure is pulled towards 0. This is the default ranking."
     },
     "similar_schools_reliability": {
      "type": [
       "number",
       "null"
      ],
      "description": "Share of this school's gap that is signal rather than sampling noise, from its enrolment: about 0.36 at 25 students and 0.95 at 800."
     },
     "similar_schools_index": {
      "type": [
       "number",
       "null"
      ],
      "description": "The same gaps, each divided by the standard deviation of that measure's gaps across all schools before averaging, so a measure with a naturally wide spread does not dominate. 0 is level with the Similar Schools group; 1 is one standard deviation above it. This is the ranking the page defaults to."
     },
     "similar_schools_advantage_measures": {
      "type": "array",
      "description": "The measures that contributed, with each gap, the standard deviation used to standardise it and the resulting standardised gap.",
      "items": {
       "type": "object",
       "properties": {
        "measure": {
         "type": "string"
        },
        "basis": {
         "type": "string",
         "enum": [
          "latest",
          "average"
         ]
        },
        "school": {
         "type": "number"
        },
        "similar_schools": {
         "type": "number"
        },
        "gap": {
         "type": "number"
        },
        "gap_sd": {
         "type": "number",
         "description": "Standard deviation of this measure's gaps across all schools."
        },
        "gap_standardised": {
         "type": "number",
         "description": "gap divided by gap_sd."
        }
       }
      }
     },
     "source_document": {
      "type": "object",
      "description": "The Annual Report this school's measures were read from. `url` is the PDF, which is what to link a reader to; `parsed_url` is the .docx the figures were actually read from, and `sha256` and `bytes` describe that file.",
      "properties": {
       "url": {
        "type": "string",
        "format": "uri"
       },
       "format": {
        "type": "string"
       },
       "parsed_format": {
        "type": "string"
       },
       "parsed_url": {
        "type": "string",
        "format": "uri"
       },
       "file": {
        "type": "string"
       },
       "sha256": {
        "type": "string"
       },
       "bytes": {
        "type": "integer"
       },
       "fetched_at": {
        "type": "string",
        "format": "date-time"
       }
      }
     },
     "enrolment_history": {
      "type": "object",
      "description": "Total enrolments at each February census, from the Department of Education's All Schools FTE Enrolments files on DataVic, with the change over 5 and 10 years.",
      "properties": {
       "latest_year": {
        "type": "integer"
       },
       "enrolments": {
        "type": [
         "number",
         "null"
        ]
       },
       "change_5y": {
        "type": [
         "number",
         "null"
        ]
       },
       "change_5y_percent": {
        "type": [
         "number",
         "null"
        ]
       },
       "change_10y": {
        "type": [
         "number",
         "null"
        ]
       },
       "change_10y_percent": {
        "type": [
         "number",
         "null"
        ]
       },
       "year_7_change_5y_percent": {
        "type": [
         "number",
         "null"
        ],
        "description": "Change in the Year 7 intake over five years: the clearest sign of whether families are choosing the school."
       },
       "series": {
        "type": "array",
        "description": "One entry per census year.",
        "items": {
         "type": "object",
         "properties": {
          "year": {
           "type": "integer"
          },
          "enrolments": {
           "type": "number"
          },
          "primary": {
           "type": "number"
          },
          "secondary": {
           "type": "number"
          },
          "year_7": {
           "type": "number"
          },
          "year_12": {
           "type": "number"
          }
         }
        }
       }
      }
     },
     "senior_secondary": {
      "type": "object",
      "description": "VCAA's Senior Secondary Completion and Achievement Information for this school, one entry per year under `years`, with the newest repeated under `latest`. SSCAI names no school number, so each year is linked through VCAA's VCE provider list (which shares its suburbs with SSCAI and publishes a phone number the school register also carries), then checked against the school's own Annual Report.",
      "properties": {
       "latest_year": {
        "type": "integer"
       },
       "latest": {
        "$ref": "#/components/schemas/VicSchoolSeniorSecondary"
       },
       "years": {
        "type": "object",
        "additionalProperties": {
         "$ref": "#/components/schemas/VicSchoolSeniorSecondary"
        }
       }
      }
     },
     "focus": {
      "type": [
       "string",
       "null"
      ],
      "description": "A sentence or two from the school's own Annual Report naming what is particular about it -- a bilingual stream, a selective programme, a deaf facility. Null for most schools, which describe nothing that sets them apart from other government schools."
     },
     "designated_bilingual": {
      "type": [
       "string",
       "null"
      ],
      "description": "The language this school teaches under the Department's Designated Bilingual Program, which funds 30-50% of the week in the target language. Null for every school outside the program, including schools running a bilingual program of their own. Source: https://www.bilingualschools.vic.edu.au/"
     },
     "designated_purpose": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The Department's designated purpose categories for this school, which cut across the register's school types: autism, deaf, intellectual_mild, intellectual_mild_profound, intellectual_moderate_profound, physical, high_ability, community, vocational, english_language, virtual. Source: https://www2.education.vic.gov.au/pal/designated-purpose-settings/guidance/designated-purpose-schools"
     },
     "focus_tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "bilingual, selective, ib, pedagogy, inclusion, unique or academy from the school's own wording; girls_school or boys_school from its enrolment profile; specialist_school or english_language_school from the register's school type."
     },
     "page": {
      "type": "string",
      "format": "uri"
     },
     "json": {
      "type": "string",
      "format": "uri"
     }
    },
    "required": [
     "school_no",
     "school_name"
    ]
   },
   "VicSchoolFile": {
    "type": "object",
    "description": "One file under schools/: the dataset's provenance and the one school it covers. It carries no timestamp -- index.json holds the generation and fetch times for the dataset, so this file changes only when the school's own data does.",
    "properties": {
     "dataset": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "licence_note": {
      "type": "string"
     },
     "school": {
      "$ref": "#/components/schemas/VicSchool"
     }
    },
    "required": [
     "school"
    ]
   },
   "VicSchools": {
    "type": "object",
    "properties": {
     "dataset": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "licence_note": {
      "type": "string"
     },
     "school_count": {
      "type": "integer"
     },
     "schools": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/VicSchool"
      }
     }
    }
   },
   "VicSchoolRanking": {
    "type": "object",
    "properties": {
     "title": {
      "type": "string"
     },
     "description": {
      "type": "string"
     },
     "measure": {
      "type": "string"
     },
     "basis": {
      "type": "string"
     },
     "unit": {
      "type": "string"
     },
     "higher_is_better": {
      "type": "boolean"
     },
     "requires": {
      "type": [
       "string",
       "null"
      ],
      "description": "A measure a school must have published before it appears in this ranking."
     },
     "school_count": {
      "type": "integer"
     },
     "entries": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "rank": {
         "type": "integer",
         "description": "Shared by schools with equal values."
        },
        "school_no": {
         "type": "string"
        },
        "school_name": {
         "type": "string"
        },
        "slug": {
         "type": "string"
        },
        "suburb": {
         "type": "string"
        },
        "lga": {
         "type": "string"
        },
        "metro": {
         "type": "boolean"
        },
        "school_type": {
         "type": "string"
        },
        "sfoe_band": {
         "type": [
          "string",
          "null"
         ]
        },
        "enrolments": {
         "type": [
          "integer",
          "null"
         ]
        },
        "value": {
         "type": "number"
        },
        "similar_schools_advantage": {
         "type": [
          "number",
          "null"
         ]
        },
        "similar_schools_index": {
         "type": [
          "number",
          "null"
         ]
        },
        "similar_schools_adjusted": {
         "type": [
          "number",
          "null"
         ]
        },
        "similar_schools_reliability": {
         "type": [
          "number",
          "null"
         ]
        },
        "page": {
         "type": "string",
         "format": "uri"
        }
       }
      }
     }
    }
   },
   "VicSchoolRankings": {
    "type": "object",
    "properties": {
     "dataset": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "licence_note": {
      "type": "string"
     },
     "tables": {
      "type": "object",
      "description": "One entry per level: `secondary` and `primary`. A combined (P-12) school is ranked in both, on the measures that level reports.",
      "additionalProperties": {
       "type": "object",
       "additionalProperties": {
        "$ref": "#/components/schemas/VicSchoolRanking"
       }
      }
     },
     "table_levels": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     }
    }
   },
   "VicSchoolsIndex": {
    "type": "object",
    "description": "The dataset index, and the only published file carrying the generation and fetch times. Every other file changes only when its own data does.",
    "properties": {
     "generated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this build ran (UTC)."
     },
     "fetched_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the Annual Reports and register were downloaded (UTC)."
     },
     "dataset": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "licence_note": {
      "type": "string"
     },
     "page": {
      "type": "string",
      "format": "uri"
     },
     "report_years": {
      "type": "array",
      "items": {
       "type": "integer"
      },
      "description": "The Annual Report years present across the dataset."
     },
     "school_count": {
      "type": "integer",
      "description": "Schools published."
     },
     "files": {
      "type": "array",
      "items": {
       "type": "object"
      },
      "description": "Each file in this dataset, with its URL and what it holds."
     },
     "measures": {
      "type": "array",
      "items": {
       "type": "object"
      },
      "description": "Every Performance Summary measure published, with its units and which tiers carry it."
     },
     "tables": {
      "type": "object",
      "description": "One entry per level -- `secondary`, `primary` and `specialist` -- each with the levels it draws on, its school count and its rankings.",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "levels": {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        "school_count": {
         "type": "integer"
        },
        "rankings": {
         "type": "array",
         "items": {
          "type": "object"
         }
        }
       }
      }
     },
     "schools_dir": {
      "type": "object",
      "description": "Where the per-school files live, with a URL template and every school's number, slug, page and JSON URL."
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "name": {
         "type": "string"
        },
        "url": {
         "type": "string",
         "format": "uri"
        },
        "description": {
         "type": "string"
        }
       }
      },
      "description": "The published sources this dataset is built from."
     },
     "register": {
      "type": "object",
      "description": "The School Locations register file used, with its URL, licence, size and SHA-256."
     },
     "report_url_template": {
      "type": "string",
      "description": "VRQA URL for a school's Annual Report; substitute `{school_no}`."
     },
     "similar_schools_advantage": {
      "type": "object",
      "description": "How the mean gap to a school's Similar Schools group is built: the measures averaged and the minimum number a school needs to be ranked."
     },
     "size_adjustment": {
      "type": "object",
      "description": "The per-table variance fit that shrinks a small school's gap towards zero, and the minimum schools needed to fit it."
     }
    }
   }
  }
 }
}