{
 "note": "What a client has to establish before this dataset can answer a question about Victorian government schools, and which file answers it. Each question lists the inputs that change the answer; ask the reader for them first. Every count here is computed from the build it ships with.",
 "questions": [
  {
   "question": "What are the best government schools in <area>?",
   "also_asked_as": [
    "best schools in Boroondara",
    "top primary schools near Glen Waverley",
    "good secondary schools in my council",
    "which school should I look at in <suburb>"
   ],
   "has_no_single_answer": true,
   "ask_the_reader_first": [
    {
     "input": "level",
     "values": [
      "primary",
      "secondary",
      "specialist"
     ],
     "why": "Primary and secondary schools are ranked on different measures in separate tables: 1227 schools on the primary table, 338 on the secondary, 90 specialist and English language schools on their own. The 80 combined (P-12) schools are on both.",
     "how_much_it_moves_the_answer": "Completely: the two tables share no academic measure, so they are different lists."
    },
    {
     "input": "area",
     "values": [
      "a council (LGA)",
      "a suburb"
     ],
     "why": "Government schools are compared statewide; an area question is a filter. The dataset has 80 councils and 860 suburbs with at least one government school.",
     "how_much_it_moves_the_answer": "It decides which schools are on the list at all."
    },
    {
     "input": "what_best_means",
     "values": [
      "raw results (study score, NAPLAN)",
      "results against schools with a similar intake"
     ],
     "why": "The default ranking is value added relative to intake, not raw results. Of the 10 secondary schools with the highest mean study score, 1 is in the default ranking's top 10, and 6 of those 10 are selective-entry schools that choose their students by exam or audition.",
     "how_much_it_moves_the_answer": "9 of the secondary top ten change."
    }
   ],
   "then_read": {
    "url_template": "https://deepalmanac.com/au/education/vic-schools/v1/lga/{lga_slug}.json",
    "or": "https://deepalmanac.com/au/education/vic-schools/v1/suburb/{suburb_slug}.json",
    "find_the_slug_in": [
     "https://deepalmanac.com/au/education/vic-schools/v1/lga/index.json",
     "https://deepalmanac.com/au/education/vic-schools/v1/suburb/index.json"
    ],
    "field": "schools[].ranks[table][ranking].rank -- sort by it",
    "gives": "Every government school in the area with its statewide rank on every ranking, in one small file (the largest council, City of Casey, has 69 schools)."
   },
   "say_as_well": "A rank is statewide, not within the area. Name the ranking you sorted by, and say whether it is raw results or results against similar schools. Catholic and independent schools are not in this dataset, so in most areas this is not every school a family could choose."
  },
  {
   "question": "Which schools have the best VCE results?",
   "also_asked_as": [
    "highest ATAR schools",
    "best VCE results in Boroondara",
    "top government secondary schools by study score",
    "best VCE schools Melbourne"
   ],
   "has_no_single_answer": true,
   "ask_the_reader_first": [
    {
     "input": "area",
     "values": [
      "a council (LGA)",
      "a suburb"
     ],
     "why": "Government schools are compared statewide; an area question is a filter. The dataset has 80 councils and 860 suburbs with at least one government school.",
     "how_much_it_moves_the_answer": "It decides which schools are on the list at all."
    },
    {
     "input": "include_selective_entry",
     "values": [
      true,
      false
     ],
     "why": "The 7 selective-entry schools choose students by exam or audition and fill 6 of the top 10 places on mean study score. A family who will not sit the entry exam wants the list without them.",
     "how_much_it_moves_the_answer": "6 of the top 10 places statewide."
    }
   ],
   "then_read": {
    "file": "https://deepalmanac.com/au/education/vic-schools/v1/rankings.json",
    "field": "tables.secondary.study_score, tables.secondary.study_scores_40_plus, tables.secondary.median_study_score",
    "for_one_area": "https://deepalmanac.com/au/education/vic-schools/v1/lga/{lga_slug}.json, schools[].ranks.secondary.study_score",
    "page": "https://deepalmanac.com/au/education/vic-schools/secondary/?rank=study_score",
    "gives": "Mean VCE study score (Annual Report), share of study scores of 40 and over and median study score (VCAA, 2022, 2023, 2024, 2025)."
   },
   "say_as_well": "Raw results mostly sort intakes: the selective schools first, then the wealthiest suburbs. Say so, and offer the similar-schools ranking as the measure of how well a school does with the students it has. The mean study score is the Annual Report's; a school without a published VCE completion rate is not ranked on it. ATARs are not published per school."
  },
  {
   "question": "Which government schools are strongest in <subject>?",
   "also_asked_as": [
    "my kid loves French, where should he go",
    "best school for chemistry",
    "which schools get the top VCE maths results",
    "good drama school near me",
    "where do students get 40+ in <subject>"
   ],
   "has_no_single_answer": true,
   "ask_the_reader_first": [
    {
     "input": "subject",
     "values": [
      "one of the 114 VCE studies in subjects/index.json"
     ],
     "why": "Each study has its own file. A parent's word for a subject may be several studies: 'maths' is General Mathematics, Mathematical Methods and Specialist Mathematics; 'Chinese' is four studies; 'history' is Revolutions, Ancient, Australian and Modern. Offer the list and let the reader pick.",
     "how_much_it_moves_the_answer": "Completely: different studies have different schools at the top."
    },
    {
     "input": "area",
     "values": [
      "a council (LGA)",
      "a suburb"
     ],
     "why": "Government schools are compared statewide; an area question is a filter. The dataset has 80 councils and 860 suburbs with at least one government school.",
     "how_much_it_moves_the_answer": "It decides which schools are on the list at all."
    },
    {
     "input": "include_non_government",
     "values": [
      true,
      false
     ],
     "why": "Only government schools are ranked. Each subject file also lists the Catholic, independent and other providers on VCAA's roll for that study, by name and count, with no page here; at the top of most subjects they outnumber the government schools.",
     "how_much_it_moves_the_answer": "The top of the statewide list, in most subjects."
    }
   ],
   "then_read": {
    "url_template": "https://deepalmanac.com/au/education/vic-schools/v1/subjects/{slug}.json",
    "find_the_slug_in": "https://deepalmanac.com/au/education/vic-schools/v1/subjects/index.json",
    "field": "at_a_glance first (the leading schools and the statewide totals in a few kB, enough when the fetch stops short of the full file); schools[] in default order; strength_ratio and per_100_vce_students to re-sort; offered to list the schools that teach it; premiers_awards for the Premier's VCE Study Awards won in it, the very top of the subject",
    "gives": "For one study, every government school that offers it or had a study score of 40 or above published on VCAA's honour roll in 2020-2025, with the pooled count, each year's count, the count per 100 VCE students, and a strength ratio: the count against what the school's overall results would predict. French: 53 government schools offer it; 34 had a published 40+; MacRobertson Girls High School has the most (19) and Auburn High School the highest strength ratio (13.2)."
   },
   "say_as_well": "Every count is a lower bound: only students who consented to publication appear, and 13% of scores of 40 or above were withheld statewide. VCAA publishes no per-subject enrolments, so there is no pass rate; a raw count favours big schools and selective-entry schools, and per_100_vce_students favours schools where many take the subject. Say whether a school offers the study at all: a school with no published 40+ may still teach it well. A language can also be taken through the Victorian School of Languages from any school."
  },
  {
   "question": "Which primary schools have the best NAPLAN results?",
   "also_asked_as": [
    "best primary schools NAPLAN",
    "top primary school in <suburb>",
    "highest NAPLAN Year 5"
   ],
   "has_no_single_answer": true,
   "ask_the_reader_first": [
    {
     "input": "area",
     "values": [
      "a council (LGA)",
      "a suburb"
     ],
     "why": "Government schools are compared statewide; an area question is a filter. The dataset has 80 councils and 860 suburbs with at least one government school.",
     "how_much_it_moves_the_answer": "It decides which schools are on the list at all."
    },
    {
     "input": "year_level",
     "values": [
      "Year 3",
      "Year 5",
      "growth from Year 3 to 5"
     ],
     "why": "Each is its own ranking, and growth asks how far students moved rather than where they are.",
     "how_much_it_moves_the_answer": "Different rankings; the same school can sit far apart on them."
    },
    {
     "input": "what_best_means",
     "values": [
      "raw results (study score, NAPLAN)",
      "results against schools with a similar intake"
     ],
     "why": "The default ranking is value added relative to intake, not raw results. Of the 10 primary schools with the highest Year 5 NAPLAN, 0 are in the default ranking's top 10.",
     "how_much_it_moves_the_answer": "10 of the primary top ten change."
    }
   ],
   "then_read": {
    "file": "https://deepalmanac.com/au/education/vic-schools/v1/rankings.json",
    "field": "tables.primary.naplan_year_5, tables.primary.naplan_year_3, tables.primary.naplan_growth_3_5",
    "for_one_area": "https://deepalmanac.com/au/education/vic-schools/v1/lga/{lga_slug}.json, schools[].ranks.primary",
    "page": "https://deepalmanac.com/au/education/vic-schools/primary/?rank=naplan_year_5",
    "gives": "The mean of the reading and numeracy shares at Strong or Exceeding, multi-year average."
   },
   "say_as_well": "NAPLAN here is the share of students at Strong or Exceeding as the Department republishes it in each Annual Report, not scaled scores. A small school's share moves a long way on a few students."
  },
  {
   "question": "How good is <school>, and how does it compare with similar schools?",
   "also_asked_as": [
    "is Balwyn High any good",
    "how does my child's school compare",
    "what is this school's school number"
   ],
   "has_no_single_answer": false,
   "ask_the_reader_first": [
    {
     "input": "school",
     "values": [
      "name, and suburb if the name is common"
     ],
     "why": "The dataset is keyed on the Department of Education's school number, not the name. Several names are shared, and the same number can belong to a government and a Catholic school.",
     "how_much_it_moves_the_answer": "It picks the record."
    }
   ],
   "then_read": {
    "find_the_number_in": "https://deepalmanac.com/au/education/vic-schools/v1/names/{key}.json, key the first letter of the school's name lowercased; https://deepalmanac.com/au/education/vic-schools/v1/names/index.json lists the keys, and a crowded letter is split by its first two letters (such as 'mo')",
    "or_in": "https://deepalmanac.com/au/education/vic-schools/v1/suburb/{suburb_slug}.json, with every school in the suburb and its ranks",
    "url_template": "https://deepalmanac.com/au/education/vic-schools/v1/schools/{school_no}.json",
    "page_template": "https://deepalmanac.com/au/education/vic-schools/schools/{slug}/",
    "gives": "Every measure for the school, its Similar Schools group and the state, with the Annual Report it was read from."
   },
   "say_as_well": "A gap to similar schools is the Department's own like-for-like comparison. A figure missing from a school is suppressed, not zero: say it is not published."
  },
  {
   "question": "Is <school> a primary or a secondary school, and which table is it on?",
   "also_asked_as": [
    "is this a P-12 school",
    "why is this school on both lists"
   ],
   "has_no_single_answer": false,
   "ask_the_reader_first": [],
   "then_read": {
    "url_template": "https://deepalmanac.com/au/education/vic-schools/v1/schools/{school_no}.json",
    "field": "school.level",
    "values": {
     "primary": "primary table",
     "secondary": "secondary table",
     "combined": "both tables",
     "special": "specialist table",
     "language": "specialist table"
    }
   },
   "say_as_well": "80 combined schools are on both tables, ranked on each table's own measures, so the same school has two different ranks. Its similar-schools figure is built from the secondary measures."
  },
  {
   "question": "Which are the selective-entry schools, and where do they rank?",
   "also_asked_as": [
    "Melbourne High ranking",
    "selective schools Victoria",
    "Mac.Rob results"
   ],
   "has_no_single_answer": false,
   "ask_the_reader_first": [],
   "then_read": {
    "file": "https://deepalmanac.com/au/education/vic-schools/v1/schools.json",
    "field": "schools[] where designated_purpose contains high_ability (selective_entry in the area files)",
    "selective_entry_schools": [
     "Centre for Higher Education Studies",
     "John Monash Science School",
     "MacRobertson Girls High School",
     "Melbourne High School",
     "Nossal High School",
     "Suzanne Cory High School",
     "Victorian College Of The Arts Secondary School"
    ]
   },
   "say_as_well": "6 of the 7 have no rank on the default similar-schools table, because the Department publishes no Similar Schools group for them. The focus tag `selective` is different: it marks 22 ordinary schools that run an accelerated (SEAL) program for some students, and they are not selective-entry schools."
  }
 ],
 "commentary": [
  {
   "topic": "The default ranking is not raw results",
   "what_you_will_see": "1 of the 10 secondary schools with the highest mean study score is in the default ranking's top 10. Of the 6 government secondary schools in City of Boroondara, Balwyn High School has the highest mean study score, 8th statewide, and is 37th on the default ranking.",
   "what_it_actually_means": "The default, similar_schools_adjusted, is the mean gap between a school and the Department's Similar Schools group (schools with a similar intake) across the comparable measures, scaled back at small schools. It is value added relative to intake.",
   "say_this_as_well": "Name the ranking you used. If the reader asked about results, use study_score or the NAPLAN rankings.",
   "do_not": "Do not present the default order as the schools with the best VCE or NAPLAN results.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/rankings.json, table_notes"
  },
  {
   "topic": "Selective-entry schools sit in the secondary table",
   "what_you_will_see": "6 of the top 10 schools on mean study score are selective-entry schools, and 6 of the 7 are missing from the default ranking.",
   "why_it_is_correct": "They are ordinary Secondary schools in the register and are designated High Ability by the Department. They choose students by exam or audition, so their raw results reflect the intake; the Department publishes no Similar Schools figures for them, so there is no gap to rank.",
   "say_this_as_well": "Say entry is by exam, and give the list without them when the reader would not sit it.",
   "do_not": "Do not read their absence from the default ranking as a poor result.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/schools.json, designated_purpose (high_ability)"
  },
  {
   "topic": "Subject counts are consenting students only",
   "what_you_will_see": "A school's published_40_plus in a subject file, and its study_scores_40_plus_percent from SSCAI, do not reconcile. Statewide, 13% of scores of 40 or above were withheld in the years VCAA states it.",
   "why_it_is_correct": "VCAA's honour roll lists only students who agreed to publication, and the share who agree differs by school. SSCAI's percentage counts every score. The subject counts are therefore lower bounds and are not corrected: the correction would need each school's number of study scores, which VCAA does not publish.",
   "say_this_as_well": "Say 'at least N published scores of 40 or above', and give the school's overall 40+ share beside it.",
   "do_not": "Do not divide a subject count by the cohort and call it a pass rate, or read a zero as 'nobody did well'.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/subjects/index.json, notes"
  },
  {
   "topic": "Suppressed values are null, not zero",
   "what_you_will_see": "558 schools have at least one measure with no school figure: 680 readings marked NDA and 1614 marked NDP.",
   "why_it_is_correct": "The Department withholds a figure when a cohort is too small (NDA, no data available) or publishing it could identify students (NDP). The reading carries `suppressed` with the reason instead of `school`, ranking files and area files show null or leave the rank out, and the school is not ranked on that measure.",
   "say_this_as_well": "Say the figure is not published for this school.",
   "do_not": "Do not treat a missing value as zero, or a missing rank as last place.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/schools/{school_no}.json, school.measures.*.latest.suppressed"
  },
  {
   "topic": "Small schools are scaled back on the default ranking",
   "what_you_will_see": "A school with a larger raw gap can rank below one with a smaller gap. Of the 20 primary schools with the largest unadjusted gap, 12 are outside the adjusted top 20. 300 schools have under 100 students.",
   "why_it_is_correct": "A gap measured on a few students swings a long way on chance. The variance of the gaps is fitted as tau^2 + sigma^2/n per table and each gap multiplied by its reliability: on the secondary fit a 25-student school keeps 19% of its gap, a 100-student school 49% and a 400-student school 79%.",
   "say_this_as_well": "The unscaled gap is the similar_schools_advantage ranking.",
   "do_not": "Do not quote a tiny school's raw gap as proof it outperforms.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/index.json, size_adjustment"
  },
  {
   "topic": "A rank in an area file is the statewide rank",
   "what_you_will_see": "The best school in a council can carry a rank like 37.",
   "what_it_actually_means": "ranks[table][ranking].rank is the place among every Victorian government school on that table, out of rankings[table][ranking].ranked_out_of.",
   "say_this_as_well": "Give the area order and the statewide rank together.",
   "do_not": "Do not report the statewide rank as the place within the area.",
   "check_it_yourself": "https://deepalmanac.com/au/education/vic-schools/v1/lga/boroondara.json"
  }
 ],
 "commentary_note": "Figures here that a client will otherwise misread: the default ranking taken for raw results, selective schools that seem missing, suppressed values read as zero, small schools that seem to rank too low, and statewide ranks read as local ones.",
 "what_it_cannot_answer_yet": [
  {
   "question": "Which school zone am I in, or which school must take my child?",
   "why": "This dataset holds no school zones or catchments.",
   "where_to_send_the_reader": "https://www.findmyschool.vic.gov.au/"
  },
  {
   "question": "How does a Catholic or independent school compare?",
   "why": "Only government schools are here. The register lists 726 non-government schools in Victoria; the Department's Performance Summary covers government schools only.",
   "where_to_send_the_reader": "https://www.myschool.edu.au/"
  },
  {
   "question": "How do schools outside Victoria compare?",
   "why": "This dataset covers Victoria only.",
   "where_to_send_the_reader": "https://www.myschool.edu.au/"
  },
  {
   "question": "What does the school cost?",
   "why": "Government schools charge local students no tuition fee; voluntary contributions and charges for extras vary by school and are not held here.",
   "where_to_send_the_reader": "The school's own website (`website` on each school record)."
  },
  {
   "question": "How did this school do in an earlier year?",
   "why": "Each school's measures come from its latest Annual Report (2025 for most; 17 schools' latest is older), with a multi-year average where the Department gives one. Earlier reports are not held, and NAPLAN results before 2023 were reported on a different scale.",
   "where_to_send_the_reader": "The school's own past Annual Reports, on its website."
  }
 ],
 "context_this_dataset_does_not_hold": [
  "Non-government schools: Catholic (493) and independent (233) schools in the register are left out.",
  "Schools outside Victoria.",
  "School zones and catchments.",
  "Fees, voluntary contributions and other costs.",
  "Any year before a school's latest Annual Report, other than the multi-year averages it publishes. Report years present: 2023, 2024, 2025. VCAA senior secondary years: 2022, 2023, 2024, 2025.",
  "ATARs per school, which VCAA and VTAC do not publish.",
  "Waiting lists, enrolment caps and out-of-zone places."
 ],
 "not_advice": "Reference data, not advice about where to enrol a child."
}