@vepler/sdk 3.3.0 → 6.0.0

package/dist/esm/sdk/models/operations/queryschools.d.ts

@@ -4,33 +4,39 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as shared from "../shared/index.js";
 /**
- * Fields/blocks to return per school. Default (omitted): the full flat record, no blocks. Aggregate blocks (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) are additive — requesting only block names keeps the full flat record and adds the blocks. List scalar field names to trim.
+ * The fields and blocks to return for each school, as a comma-separated string or an array. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims each school to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored.
  */
 export type QuerySchoolsAttributes = string | Array<string>;
 /**
- * Radius search around a point. Adds `distance` field to each result. Mutually exclusive with `within`.
+ * Search within a radius of a point. Results carry a `distance` field and come back nearest first. Cannot be combined with `within`.
  */
 export type Near = {
     /**
-     * WGS84 latitude
+     * Latitude of the centre point, in WGS84 decimal degrees.
      */
     lat: number;
     /**
-     * WGS84 longitude
+     * Longitude of the centre point, in WGS84 decimal degrees.
      */
     lng: number;
     /**
-     * Search radius in metres (max 50km)
+     * How far from the centre point to search, in metres. Defaults to 5000. Maximum 50000.
      */
     radiusM?: number | undefined;
 };
+/**
+ * Direction to sort in. Defaults to ascending.
+ */
 export declare const QuerySchoolsOrder: {
     readonly Asc: "asc";
     readonly Desc: "desc";
 };
+/**
+ * Direction to sort in. Defaults to ascending.
+ */
 export type QuerySchoolsOrder = ClosedEnum<typeof QuerySchoolsOrder>;
 /**
- * Sort field. 'distance' is only valid when `near` is set; defaults to 'name' otherwise.
+ * Field to sort by, applied when the request has no geographic filter. Defaults to `name`. A `near` search always returns the closest schools first, whatever this is set to.
  */
 export declare const QuerySchoolsOrderBy: {
     readonly Name: "name";
@@ -39,11 +45,11 @@ export declare const QuerySchoolsOrderBy: {
     readonly Distance: "distance";
 };
 /**
- * Sort field. 'distance' is only valid when `near` is set; defaults to 'name' otherwise.
+ * Field to sort by, applied when the request has no geographic filter. Defaults to `name`. A `near` search always returns the closest schools first, whatever this is set to.
  */
 export type QuerySchoolsOrderBy = ClosedEnum<typeof QuerySchoolsOrderBy>;
 /**
- * Source register identifier. 'dfe': UK DfE GIAS (England + cross-border Welsh URNs). 'welshgov': Welsh Government School Number. 'seed': Scottish SEED code. 'deni': NI DE Reference. 'dept_edu_ie': Irish Roll Number.
+ * Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.
  */
 export declare const Providers: {
     readonly Dfe: "dfe";
@@ -53,11 +59,11 @@ export declare const Providers: {
     readonly DeptEduIe: "dept_edu_ie";
 };
 /**
- * Source register identifier. 'dfe': UK DfE GIAS (England + cross-border Welsh URNs). 'welshgov': Welsh Government School Number. 'seed': Scottish SEED code. 'deni': NI DE Reference. 'dept_edu_ie': Irish Roll Number.
+ * Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.
  */
 export type Providers = ClosedEnum<typeof Providers>;
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export declare const Two: {
     readonly Outstanding: "outstanding";
@@ -81,11 +87,11 @@ export declare const Two: {
     readonly Fair: "fair";
 };
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export type Two = ClosedEnum<typeof Two>;
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export declare const One: {
     readonly Outstanding: "outstanding";
@@ -109,15 +115,15 @@ export declare const One: {
     readonly Fair: "fair";
 };
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export type One = ClosedEnum<typeof One>;
 /**
- * Filter by current inspection rating — single value or array (OR logic)
+ * Return only schools on this inspection rating. Pass an array to match any one of several ratings.
  */
 export type Rating = One | Array<Two>;
 /**
- * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+ * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
  */
 export declare const QuerySchoolsStatus: {
     readonly Open: "open";
@@ -125,11 +131,11 @@ export declare const QuerySchoolsStatus: {
     readonly PendingClosure: "pending_closure";
 };
 /**
- * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+ * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
  */
 export type QuerySchoolsStatus = ClosedEnum<typeof QuerySchoolsStatus>;
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export declare const QuerySchools2: {
     readonly Nursery: "nursery";
@@ -143,11 +149,11 @@ export declare const QuerySchools2: {
     readonly Other: "other";
 };
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export type QuerySchools2 = ClosedEnum<typeof QuerySchools2>;
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export declare const QuerySchools1: {
     readonly Nursery: "nursery";
@@ -161,205 +167,226 @@ export declare const QuerySchools1: {
     readonly Other: "other";
 };
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export type QuerySchools1 = ClosedEnum<typeof QuerySchools1>;
 /**
- * Filter by school type — single value or array (OR logic)
+ * Return only schools of this type. Pass an array to match any one of several types.
  */
 export type Type = QuerySchools1 | Array<QuerySchools2>;
 /**
- * Bounding box search. Mutually exclusive with `near`.
+ * Search inside a bounding box, in WGS84 decimal degrees. Cannot be combined with `near`.
  */
 export type Within = {
+    /**
+     * Longitude of the eastern edge.
+     */
     east: number;
+    /**
+     * Latitude of the northern edge.
+     */
     north: number;
+    /**
+     * Latitude of the southern edge.
+     */
     south: number;
+    /**
+     * Longitude of the western edge.
+     */
     west: number;
 };
 /**
- * Flexible school query. Filter by country/region/provider, categorical fields, free-text, or geography (radius or bounding box). Pagination via limit/offset, ordering via orderBy/order.
+ * Filters for a school search. Narrow by country, region and source register, by type, status, rating, authority, postcode or free text, or by geography with `near` or `within`. Page through the results with `limit` and `offset`.
  */
 export type QuerySchoolsRequestBody = {
     /**
-     * Fields/blocks to return per school. Default (omitted): the full flat record, no blocks. Aggregate blocks (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) are additive — requesting only block names keeps the full flat record and adds the blocks. List scalar field names to trim.
+     * The fields and blocks to return for each school, as a comma-separated string or an array. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims each school to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored.
      */
     attributes?: string | Array<string> | undefined;
     /**
-     * Filter by local authority name
+     * Return only schools under this local authority. The name must match exactly.
      */
     authority?: string | undefined;
     /**
-     * Marks the request as a catchment-enriched query. When set, every school in the response gains a `catchment` block and the response-level `meta.catchment` block describes coverage.
+     * The property to test the returned schools against, given as either a `uprn` or a `point`. Supplying it adds a `catchment` block to every school in the response and a `meta.catchment` block describing how the match was made.
      */
     catchmentReference?: shared.CatchmentReference | undefined;
     /**
-     * ISO 3166-1 alpha-2 country filter
+     * Return only schools in this country, given as an ISO 3166-1 alpha-2 code.
      */
     country?: string | undefined;
+    /**
+     * Maximum number of schools to return. Defaults to 25. Minimum 1, maximum 100.
+     */
     limit?: number | undefined;
     /**
-     * Radius search around a point. Adds `distance` field to each result. Mutually exclusive with `within`.
+     * Search within a radius of a point. Results carry a `distance` field and come back nearest first. Cannot be combined with `within`.
      */
     near?: Near | undefined;
+    /**
+     * Number of results to skip before the first one returned. Defaults to 0.
+     */
     offset?: number | undefined;
+    /**
+     * Direction to sort in. Defaults to ascending.
+     */
     order?: QuerySchoolsOrder | undefined;
     /**
-     * Sort field. 'distance' is only valid when `near` is set; defaults to 'name' otherwise.
+     * Field to sort by, applied when the request has no geographic filter. Defaults to `name`. A `near` search always returns the closest schools first, whatever this is set to.
      */
     orderBy?: QuerySchoolsOrderBy | undefined;
     /**
-     * Filter by postcode prefix (e.g. 'SW1' matches all SW1 postcodes)
+     * Return only schools whose postcode starts with this text, so `SW1` matches every SW1 postcode.
      */
     postcode?: string | undefined;
     /**
-     * Filter by source register code (e.g. ['dfe'] or ['seed','deni'])
+     * Return only schools sourced from these registers. A school matches if it came from any of them.
      */
     providers?: Array<Providers> | undefined;
     /**
-     * Free-text search
+     * Free-text search. Matches schools whose name or postcode contains this text, or whose `key` is exactly this value.
      */
     query?: string | undefined;
     /**
-     * Filter by current inspection rating — single value or array (OR logic)
+     * Return only schools on this inspection rating. Pass an array to match any one of several ratings.
      */
     rating?: One | Array<Two> | undefined;
     /**
-     * ISO 3166-2 region filter (GB-ENG | GB-WLS | GB-SCT | GB-NIR | IE)
+     * Return only schools in this education system, given as an ISO 3166-2 region code such as `GB-ENG` or `GB-SCT`.
      */
     region?: string | undefined;
     /**
-     * Exact slug match
+     * Return the school with exactly this `slug`.
      */
     slug?: string | undefined;
     /**
-     * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+     * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
      */
     status?: QuerySchoolsStatus | undefined;
     /**
-     * Filter by school type — single value or array (OR logic)
+     * Return only schools of this type. Pass an array to match any one of several types.
      */
     type?: QuerySchools1 | Array<QuerySchools2> | undefined;
     /**
-     * Bounding box search. Mutually exclusive with `near`.
+     * Search inside a bounding box, in WGS84 decimal degrees. Cannot be combined with `near`.
      */
     within?: Within | undefined;
 };
 /**
- * Institutional narrative (ethos, welcome, term dates …). Opt-in via `attributes=about`.
+ * What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed.
  */
 export type QuerySchoolsAbout = {
     /**
-     * General 'about the school' narrative.
+     * The school's general description of itself.
      */
     aboutDescription?: string | null | undefined;
     /**
-     * Whether after-school / wraparound care is offered.
+     * True when the school states that it offers after-school or wraparound care.
      */
     afterSchoolCare?: boolean | null | undefined;
     /**
-     * Whether a breakfast club is offered.
+     * True when the school states that it runs a breakfast club.
      */
     breakfastClub?: boolean | null | undefined;
     /**
-     * Extra-curricular clubs description.
+     * What the school publishes about its extra-curricular clubs.
      */
     clubsDescription?: string | null | undefined;
     /**
-     * Curriculum narrative.
+     * What the school publishes about its curriculum.
      */
     curriculumDescription?: string | null | undefined;
     /**
-     * The school's stated ethos / values.
+     * The school's stated ethos and values.
      */
     ethos?: string | null | undefined;
     /**
-     * Facilities description.
+     * What the school publishes about its facilities.
      */
     facilitiesDescription?: string | null | undefined;
     /**
-     * Headteacher's welcome message.
+     * The headteacher's published welcome message.
      */
     headteacherWelcome?: string | null | undefined;
     /**
-     * School history narrative.
+     * The school's account of its own history.
      */
     historyDescription?: string | null | undefined;
     /**
-     * Link to the school prospectus.
+     * Address of the school's prospectus.
      */
     prospectusUrl?: string | null | undefined;
     /**
-     * Results / outcomes summary as published.
+     * The school's own summary of its results, in the wording it published.
      */
     resultsSummary?: string | null | undefined;
     /**
-     * SEND / inclusion statement.
+     * The school's statement on special educational needs and disabilities (SEND), and on inclusion.
      */
     sendStatement?: string | null | undefined;
     /**
-     * Published term dates.
+     * Term and holiday dates as the school publishes them.
      */
     termDates?: Array<shared.SchoolTermDate> | undefined;
     /**
-     * Named uniform supplier, where stated.
+     * Name of the uniform supplier, where the school names one.
      */
     uniformSupplier?: string | null | undefined;
 };
 /**
- * Award / kitemark / partner badges. Opt-in via `attributes=accreditations`.
+ * Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication.
  */
 export type QuerySchoolsAccreditations = {
     /**
-     * Cleared accreditation / award badges.
+     * Award, kitemark and partner badges shown on the school's own website, newest first. Only badges cleared for publication appear here, so the list can be empty.
      */
     accreditations?: Array<shared.SchoolAccreditation> | undefined;
 };
 /**
- * Postal address of the school
+ * Postal address of the school.
  */
 export type QuerySchoolsAddress = {
     /**
-     * County or region
+     * County or equivalent wider area.
      */
     county?: string | undefined;
     /**
-     * Locality / district
+     * District or locality the school sits in.
      */
     locality?: string | undefined;
     /**
-     * Postcode (UK / Eircode / etc — country-specific format)
+     * Postcode in the format used by the school's own country, such as a UK postcode or an Eircode.
      */
     postcode?: string | undefined;
     /**
-     * Street and number
+     * Building number and street.
      */
     street?: string | undefined;
     /**
-     * Town or city
+     * Town or city.
      */
     town?: string | undefined;
 };
 /**
- * School branding — logo/crest, colours, social handles. Opt-in via `attributes=branding`.
+ * The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication.
  */
 export type QuerySchoolsBranding = {
     /**
-     * Public URL to the entity's logo / crest.
+     * Public URL of the logo or crest.
      */
     logoUrl?: string | undefined;
     /**
-     * Primary brand colour (hex).
+     * Primary brand colour, as a hex code.
      */
     primaryColour?: string | undefined;
     /**
-     * Secondary brand colour (hex).
+     * Secondary brand colour, as a hex code.
      */
     secondaryColour?: string | undefined;
     socialMedia?: shared.SocialMediaLinks | undefined;
 };
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export declare const QuerySchoolsCurrentRating: {
     readonly Outstanding: "outstanding";
@@ -383,77 +410,77 @@ export declare const QuerySchoolsCurrentRating: {
     readonly Fair: "fair";
 };
 /**
- * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+ * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
  */
 export type QuerySchoolsCurrentRating = OpenEnum<typeof QuerySchoolsCurrentRating>;
 /**
- * Cross-register identifiers. Present only when requested via `attributes=identifiers`.
+ * The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`.
  */
 export type QuerySchoolsIdentifiers = {
     /**
-     * Estyn provider id (Wales).
+     * The school's provider identifier with Estyn, the Welsh inspectorate.
      */
     estynId?: string | null | undefined;
     /**
-     * Ofsted provider id (England).
+     * The school's provider identifier with Ofsted, the English inspectorate.
      */
     ofstedProviderId?: string | null | undefined;
     /**
-     * Predecessor URNs this school was previously known by (re-identification lineage).
+     * Unique Reference Numbers (URNs) this school was known by before. Empty when there are none.
      */
     oldUrns?: Array<string> | undefined;
     /**
-     * UK Provider Reference Number (UKPRN).
+     * The school's UK Provider Reference Number (UKPRN).
      */
     ukprn?: string | null | undefined;
 };
 /**
- * Facility / building photography, tagged. Opt-in via `attributes=images`.
+ * Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication.
  */
 export type QuerySchoolsImages = {
     /**
-     * Cleared facility / building photography, newest first.
+     * Photographs of the school's buildings and facilities, newest first. Only images cleared for publication appear here, so the list can be empty.
      */
     images?: Array<shared.SchoolImage> | undefined;
 };
 /**
- * Inspection history. Present only when requested via `attributes=inspections`.
+ * The current inspection and the full history behind it. Present only when requested via `attributes=inspections`.
  */
 export type QuerySchoolsInspections = {
     /**
-     * Most recent inspection event, or null if never inspected.
+     * The most recent inspection. Null when the school has no recorded inspection.
      */
     current: shared.SchoolInspectionEvent | null;
     /**
-     * Every inspection event, newest first (includes `current`).
+     * Every recorded inspection, newest first. The first entry is the same event as `current`.
      */
     history?: Array<shared.SchoolInspectionEvent | null> | undefined;
 };
 /**
- * Geographic coordinates of the school
+ * Point location of the school.
  */
 export type QuerySchoolsLocation = {
     /**
-     * WGS84 latitude in decimal degrees
+     * Latitude of the school, in WGS84 decimal degrees.
      */
     lat: number;
     /**
-     * WGS84 longitude in decimal degrees
+     * Longitude of the school, in WGS84 decimal degrees.
      */
     lng: number;
 };
 /**
- * Object type discriminator. Always 'school' for school responses.
+ * Object type discriminator. Always `school`.
  */
 export declare const QuerySchoolsSchoolsObject: {
     readonly School: "school";
 };
 /**
- * Object type discriminator. Always 'school' for school responses.
+ * Object type discriminator. Always `school`.
  */
 export type QuerySchoolsSchoolsObject = ClosedEnum<typeof QuerySchoolsSchoolsObject>;
 /**
- * Source register identifier. 'dfe': UK DfE GIAS (England + cross-border Welsh URNs). 'welshgov': Welsh Government School Number. 'seed': Scottish SEED code. 'deni': NI DE Reference. 'dept_edu_ie': Irish Roll Number.
+ * Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.
  */
 export declare const QuerySchoolsProvider: {
     readonly Dfe: "dfe";
@@ -463,11 +490,11 @@ export declare const QuerySchoolsProvider: {
     readonly DeptEduIe: "dept_edu_ie";
 };
 /**
- * Source register identifier. 'dfe': UK DfE GIAS (England + cross-border Welsh URNs). 'welshgov': Welsh Government School Number. 'seed': Scottish SEED code. 'deni': NI DE Reference. 'dept_edu_ie': Irish Roll Number.
+ * Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.
  */
 export type QuerySchoolsProvider = OpenEnum<typeof QuerySchoolsProvider>;
 /**
- * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+ * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
  */
 export declare const QuerySchoolsSchoolsStatus: {
     readonly Open: "open";
@@ -475,20 +502,20 @@ export declare const QuerySchoolsSchoolsStatus: {
     readonly PendingClosure: "pending_closure";
 };
 /**
- * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+ * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
  */
 export type QuerySchoolsSchoolsStatus = OpenEnum<typeof QuerySchoolsSchoolsStatus>;
 /**
- * Trust / organisation memberships. Present only when requested via `attributes=trust`.
+ * The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`.
  */
 export type QuerySchoolsTrust = {
     /**
-     * Active organisation memberships, lead/trust roles first.
+     * The organisations the school currently belongs to, governance-leadership roles first.
      */
     memberships?: Array<shared.SchoolTrustMembership> | undefined;
 };
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export declare const QuerySchoolsType: {
     readonly Nursery: "nursery";
@@ -502,195 +529,240 @@ export declare const QuerySchoolsType: {
     readonly Other: "other";
 };
 /**
- * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+ * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
  */
 export type QuerySchoolsType = OpenEnum<typeof QuerySchoolsType>;
 /**
- * Video embeds (metadata only, by reference). Opt-in via `attributes=videos`.
+ * References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication.
  */
 export type QuerySchoolsVideos = {
     /**
-     * Cleared video embeds.
+     * Videos published on the school's own website. Only videos cleared for publication appear here, so the list can be empty.
      */
     videos?: Array<shared.SchoolVideo> | undefined;
 };
 /**
- * A single school record. Combines identity (country, region, provider+key) with descriptive details, location, the latest inspection rating, and source-register metadata. Use the `provider`+`key` pair as a cross-jurisdiction alternate key, and `id` as the durable internal identifier.
+ * A single school: who it is (country, region, provider and key), where it is, what it teaches, and how it was last inspected. Use `provider` with `key` to match the school against a national register, and `id` to refer to it in later calls to this API.
  */
 export type QuerySchoolsData = {
     /**
-     * Institutional narrative (ethos, welcome, term dates …). Opt-in via `attributes=about`.
+     * What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed.
      */
     about?: QuerySchoolsAbout | null | undefined;
     /**
-     * Award / kitemark / partner badges. Opt-in via `attributes=accreditations`.
+     * Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication.
      */
     accreditations?: QuerySchoolsAccreditations | null | undefined;
     /**
-     * Postal address of the school
+     * Postal address of the school.
      */
     address?: QuerySchoolsAddress | undefined;
+    /**
+     * Admissions policy the source register records for the school.
+     */
     admissionsPolicy?: string | undefined;
+    /**
+     * Age range the school covers, as the youngest and oldest age separated by a hyphen.
+     */
     ageRange?: string | undefined;
     /**
-     * School branding — logo/crest, colours, social handles. Opt-in via `attributes=branding`.
+     * The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication.
      */
     branding?: QuerySchoolsBranding | null | undefined;
+    /**
+     * Number of pupil places the source register records for the school.
+     */
     capacity?: number | undefined;
     /**
-     * Catchment match block. Present only when the request included `catchmentReference`. `matchBasis` is empty when the school is only in range (Tier 5 distance fallback); `verdict` is always populated.
+     * Why this school matched the property named by `catchmentReference`, and how firm the match is. Present only when the request supplied `catchmentReference`. `verdict` is always populated; `matchBasis` is empty when the school is merely one of the nearest, with no catchment evidence behind it.
      */
     catchment?: shared.SchoolCatchmentBlock | undefined;
     /**
-     * ISO 3166-1 alpha-2 country code
+     * Country the school is in, as an ISO 3166-1 alpha-2 code.
      */
     country: string;
     /**
-     * ISO 8601 datetime when this record was first created
+     * When this school first appeared in the API, as an ISO 8601 timestamp.
      */
     createdAt: string;
     /**
-     * Latest published inspection rating. Native rating from the inspector body that issued it (England: Ofsted; Wales: Estyn; Scotland: Education Scotland; NI: ETI; IE: DES Inspectorate). Rating scales differ by inspector body — do not assume cross-body equivalence.
+     * The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.
      */
     currentRating?: QuerySchoolsCurrentRating | null | undefined;
     /**
-     * Distance from search point in metres (only present when searching by `near`)
+     * Distance from the search point, in metres. Present only on results from a `near` search.
      */
     distance?: number | undefined;
+    /**
+     * Establishment number the source register assigns the school.
+     */
     establishmentNumber?: number | undefined;
+    /**
+     * Whether the school admits boys, girls or both, in the source register's own wording.
+     */
     gender?: string | undefined;
+    /**
+     * Name of the headteacher, where the source register records one.
+     */
     headteacher?: string | undefined;
     /**
-     * System-generated identifier. Stable across updates.
+     * Identifier for the school within this API. Stable across updates.
      */
     id: number;
     /**
-     * Cross-register identifiers. Present only when requested via `attributes=identifiers`.
+     * The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`.
      */
     identifiers?: QuerySchoolsIdentifiers | null | undefined;
     /**
-     * Facility / building photography, tagged. Opt-in via `attributes=images`.
+     * Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication.
      */
     images?: QuerySchoolsImages | null | undefined;
     /**
-     * Inspection history. Present only when requested via `attributes=inspections`.
+     * The current inspection and the full history behind it. Present only when requested via `attributes=inspections`.
      */
     inspections?: QuerySchoolsInspections | null | undefined;
     /**
-     * Provider-scoped identifier. URN for `dfe`, SEED for `seed`, etc. Combined with `provider` this is a globally unique alternate key for the school.
+     * The identifier the source register uses for this school, such as a URN under `dfe` or a SEED code under `seed`. Together with `provider` it identifies the school across jurisdictions.
      */
     key: string;
+    /**
+     * Code of the local authority the school falls under.
+     */
     laCode?: string | undefined;
+    /**
+     * Name of the local authority the school falls under.
+     */
     laName?: string | undefined;
     /**
-     * ISO 8601 date of the most recent inspection
+     * When the most recent inspection took place, as an ISO 8601 date.
      */
     lastInspectionDate?: string | undefined;
     /**
-     * ISO 8601 datetime of the most recent source-data refresh
+     * When the source register data behind this record was last refreshed, as an ISO 8601 timestamp.
      */
     lastUpdated: string;
     /**
-     * Geographic coordinates of the school
+     * Point location of the school.
      */
     location?: QuerySchoolsLocation | null | undefined;
     /**
-     * Lower Layer Super Output Area code (2021 ONS Census, England + Wales). Use to join with Area Reference / Safety / Prosperity APIs. Null for non-UK or unmapped schools.
+     * Lower Layer Super Output Area (LSOA) code covering the school, for joining to area-level datasets. Null when no LSOA has been mapped to the school.
      */
     lsoaCode?: string | null | undefined;
     /**
-     * Official school name
+     * Name of the school as its source register publishes it.
      */
     name: string;
+    /**
+     * Number of pupils the source register records for the school.
+     */
     numberOfPupils?: number | undefined;
     /**
-     * Object type discriminator. Always 'school' for school responses.
+     * Object type discriminator. Always `school`.
      */
     object: QuerySchoolsSchoolsObject;
+    /**
+     * Phase of education the source register assigns the school, in the register's own wording.
+     */
     phase?: string | undefined;
     /**
-     * Source register identifier. 'dfe': UK DfE GIAS (England + cross-border Welsh URNs). 'welshgov': Welsh Government School Number. 'seed': Scottish SEED code. 'deni': NI DE Reference. 'dept_edu_ie': Irish Roll Number.
+     * Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.
      */
     provider: QuerySchoolsProvider;
     /**
-     * ISO 3166-2 region code identifying the education-system jurisdiction. GB-ENG (England), GB-WLS (Wales), GB-SCT (Scotland), GB-NIR (Northern Ireland), IE (Ireland), …
+     * Education system the school belongs to, as an ISO 3166-2 region code. `GB-ENG` is England, `GB-WLS` Wales, `GB-SCT` Scotland and `GB-NIR` Northern Ireland.
      */
     region: string;
+    /**
+     * Religious character the source register records for the school.
+     */
     religiousCharacter?: string | undefined;
     /**
-     * URL-friendly slug derived from the school name
+     * URL-friendly form of the school name, safe to use in a path. Null when none has been generated.
      */
     slug?: string | null | undefined;
     specialClasses?: string | undefined;
     specialistResource?: string | undefined;
     /**
-     * Operational status of the school (sourced from official registers e.g. DfE GIAS for England). 'open': actively operating. 'closed': permanently closed. 'pending_closure': scheduled to close — still operational but may not be admitting new pupils. Most consumers should filter on 'open'.
+     * Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.
      */
     status: QuerySchoolsSchoolsStatus;
     /**
-     * Provider sub-type (e.g. 'Voluntary Aided School', 'Academy Converter')
+     * Finer-grained establishment type as the source register classifies it, for example 'Voluntary Aided School' or 'Academy Converter'.
      */
     subType?: string | undefined;
+    /**
+     * Contact telephone number for the school.
+     */
     telephone?: string | undefined;
     /**
-     * Trust / organisation memberships. Present only when requested via `attributes=trust`.
+     * The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`.
      */
     trust?: QuerySchoolsTrust | null | undefined;
+    /**
+     * Identifier of that trust in the source register.
+     */
     trustId?: string | undefined;
+    /**
+     * Name of the trust the school belongs to, where the source register records one.
+     */
     trustName?: string | undefined;
     /**
-     * Educational institution type. 'nursery': early years. 'primary': key stages 1-2 / ISCED 1. 'secondary': key stages 3-4 / ISCED 2-3. 'all-through': combined primary + secondary. 'sixth-form': post-16. 'special': special educational needs. 'independent': fee-paying. 'academy': state-funded, independently run. 'other': alternative provision / pupil referral / unclassified.
+     * The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.
      */
     type: QuerySchoolsType;
     /**
-     * ISO 8601 datetime of the most recent update to this record
+     * When this record was last changed, as an ISO 8601 timestamp.
      */
     updatedAt: string;
     /**
-     * Video embeds (metadata only, by reference). Opt-in via `attributes=videos`.
+     * References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication.
      */
     videos?: QuerySchoolsVideos | null | undefined;
+    /**
+     * URL of the school's own website.
+     */
     website?: string | undefined;
 };
 export type Meta = {
     /**
-     * Catchment match metadata — only present when the request supplied `catchmentReference`.
+     * How the catchment match was arrived at: which tiers were used, which were not, and why. Present only when the request supplied `catchmentReference`.
      */
     catchment?: shared.CatchmentMeta | undefined;
 };
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export declare const QuerySchoolsObject: {
     readonly List: "list";
 };
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export type QuerySchoolsObject = ClosedEnum<typeof QuerySchoolsObject>;
 /**
- * Paginated list of schools with an optional `meta.catchment` block.
+ * One page of school records, carrying a `meta.catchment` block when the request supplied `catchmentReference`.
  */
 export type QuerySchoolsResponseBody = {
     /**
-     * Array of items
+     * The items on this page.
      */
     data: Array<QuerySchoolsData>;
     /**
-     * Whether more items exist
+     * True when further items exist beyond this page.
      */
     hasMore: boolean;
     meta?: Meta | undefined;
     /**
-     * Object type identifier
+     * Object type discriminator. Always `list`.
      */
     object: QuerySchoolsObject;
     /**
-     * Total number of items available
+     * Total number of items matching the request across all pages.
      */
     totalCount?: number | undefined;
     /**
-     * URL of the request
+     * Path this list was requested from.
      */
     url: string;
 };