@vepler/sdk 3.3.0 → 5.28.1

package/src/sdk/models/shared/planningapplication.ts

@@ -4,6 +4,8 @@
 
 import * as z from "zod/v3";
 import { safeParse } from "../../../lib/schemas.js";
+import * as discriminatedUnionTypes from "../../types/discriminatedUnion.js";
+import { discriminatedUnion } from "../../types/discriminatedUnion.js";
 import * as openEnums from "../../types/enums.js";
 import { ClosedEnum, OpenEnum } from "../../types/enums.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
@@ -64,15 +66,15 @@ import {
 } from "./planningstatushistory.js";
 
 /**
- * Structured address of the application site, as scraped from the planning authority. Field availability varies by council — some provide full structured addresses whilst others provide only a raw string. Null if no address data was available.
+ * Address of the application site as the planning authority publishes it. Which lines are filled in varies by council: some publish a fully structured address, others only a single line in formattedAddress. Null when the council published no address.
  */
 export type PlanningApplicationAddress = {
   /**
-   * County.
+   * County the site sits in.
    */
   county?: string | null | undefined;
   /**
-   * Full formatted address as a single string, when available.
+   * The whole site address on one line, where the planning authority publishes it that way.
    */
   formattedAddress?: string | null | undefined;
   /**
@@ -92,159 +94,160 @@ export type PlanningApplicationAddress = {
    */
   line4?: string | null | undefined;
   /**
-   * UK postcode.
+   * Postcode of the site.
    */
   postcode?: string | null | undefined;
   /**
-   * Town or city.
+   * Town or city the site sits in.
    */
   town?: string | null | undefined;
   /**
-   * Electoral ward in which the site is located.
+   * Electoral ward the site falls in.
    */
   ward?: string | null | undefined;
 };
 
 /**
- * AI reasoning and processing artefacts behind the application: how it was classified (with confidence and uncertainty) and how its documents were segmented and summarised. Only present when 'enrichment' is requested via the include parameter. Sub-arrays may be empty when the relevant pipeline has not run for this application.
+ * How the application was classified and how its documents were segmented and summarised. Present only when 'enrichment' is requested through the include parameter. Either part is empty when that step has not run for the application.
  */
 export type Enrichment = {
   /**
-   * AI classification reasoning runs for the application (most recent first). Shows how our pipeline determined the application's type, status and development category, with confidence and uncertainty. May be empty when no audit was recorded.
+   * How the application's type, status and development category were decided, most recent run first, with the certainty and the doubts recorded at the time. Empty when no run was recorded for the application.
    */
   classification: Array<PlanningClassificationReasoning>;
   /**
-   * Section-level structure and AI context summaries derived from the application's documents (no embeddings or full text). Conveys how the documents were segmented and understood. May be empty when semantic processing has not run.
+   * How the application's documents were divided into sections, with a written summary of each. Carries structure and summaries only, not the document text. Empty when the application's documents have not been segmented.
    */
   semanticChunks: Array<PlanningSemanticChunk>;
 };
 
 /**
- * Structured, citation-backed data extracted from the application's documents — decision outcome and refusal reasons, development specifics, section 106 obligations, the officer's assessment, and consultee responses. Only present when 'extractions' is requested via the include parameter (GET) or the include array (POST /query); omitted entirely otherwise. Each sub-extraction may itself be null when that schema has not been extracted for this application. Coverage and per-extraction verification status are reported so consumers can degrade honestly when data is partial or unverified.
+ * Structured, quote-backed data read out of the application's documents: the decision and any refusal reasons, what is being built, section 106 obligations, the case officer's assessment and the consultee responses. Present only when 'extractions' is requested through the include parameter on GET or the include array on POST /query. Each part is null when that extraction is not available, and coverage reports how many parts are present and how many have been verified.
  */
 export type Extractions = {
   /**
-   * Statutory consultee positions and the public-representations breakdown. Null when not available.
+   * Where each consultee stood and how the public representations broke down. Null when no consultee extraction is available for this application.
    */
   consulteeResponses: PlanningConsulteeResponsesExtractionEnvelope | null;
   coverage: PlanningExtractionCoverage;
   /**
-   * Decision outcome, conditions, and refusal reasons from the decision notice. Null when not available.
+   * The outcome, the conditions and any refusal reasons, read from the decision notice. Null when no decision extraction is available for this application.
    */
   decision: PlanningDecisionExtractionEnvelope | null;
   /**
-   * What is being built or changed — type, units, storeys, floor area. Null when not available.
+   * What is being built or changed: the kind of work, the unit counts, the storeys and the floor areas. Null when no development extraction is available for this application.
    */
   development: PlanningDevelopmentExtractionEnvelope | null;
   /**
-   * The case officer's recommendation, key issues, policy refs, and CIL/s106 flags. Null when not available.
+   * The case officer's recommendation, the key issues, the policies cited and the levy and section 106 findings. Null when no officer assessment extraction is available for this application.
    */
   officerAssessment: PlanningOfficerAssessmentExtractionEnvelope | null;
   /**
-   * Section 106 financial and non-financial obligations. Null when not available.
+   * The obligations in the section 106 agreement, financial and otherwise. Null when no section 106 extraction is available for this application.
    */
   s106: PlanningS106ExtractionEnvelope | null;
 };
 
 /**
- * People associated with the application including applicants and planning agents. Contact details (phone, email) are redacted; only names and organisations are included. Null if no applicant or agent data was available.
+ * The applicants and planning agents named on the application. Only names and organisations are returned; contact details such as telephone numbers and email addresses are removed. Null when the council named nobody.
  */
 export type People = {
   /**
-   * Planning agents or consultants acting on behalf of the applicant.
+   * The planning agents or consultants acting for the applicant.
    */
   agents?: Array<PlanningAgent> | undefined;
   /**
-   * People or organisations who submitted the application.
+   * The people or organisations that submitted the application.
    */
   applicants?: Array<PlanningApplicant> | undefined;
 };
 
 /**
- * GeoJSON geometry type, always 'Point' for application site centroids.
+ * Geometry type discriminator. Always `Point`.
  */
 export const PlanningApplicationType = {
   Point: "Point",
 } as const;
 /**
- * GeoJSON geometry type, always 'Point' for application site centroids.
+ * Geometry type discriminator. Always `Point`.
  */
 export type PlanningApplicationType = ClosedEnum<
   typeof PlanningApplicationType
 >;
 
 /**
- * Application site centroid as a GeoJSON Point geometry (RFC 7946). Coordinates are in [longitude, latitude] order using the WGS84 datum (EPSG:4326). This point represents the approximate centre of the application site, derived from the planning authority's spatial data or geocoded from the site address. Null if no spatial data was available from the source. For the full site boundary, see spatialFeatures.
+ * Centre point of the application site, as a GeoJSON Point (RFC 7946). Not present when no point is held for the application. For the site boundary rather than its centre, see spatialFeatures.
  */
 export type PlanningApplicationSpatial = {
   /**
-   * Coordinate pair in GeoJSON [longitude, latitude] order. Uses the WGS84 coordinate reference system (EPSG:4326). Example: [-0.1278, 51.5074] represents a point in central London.
+   * A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).
    */
   coordinates: Array<number>;
   /**
-   * GeoJSON geometry type, always 'Point' for application site centroids.
+   * Geometry type discriminator. Always `Point`.
    */
   type: PlanningApplicationType;
 };
 
 /**
- * GeoJSON MultiPolygon geometry
+ * Several separate areas expressed as a single GeoJSON MultiPolygon geometry.
  */
 export type PlanningApplicationGeoJSONMultiPolygon = {
   /**
-   * Array of polygon coordinate arrays
+   * One entry per polygon, each holding that polygon's rings in the same form as a Polygon geometry.
    */
   coordinates: Array<Array<Array<Array<number>>>>;
   /**
-   * GeoJSON geometry type
+   * Geometry type discriminator. Always `MultiPolygon`.
    */
   type: "MultiPolygon";
 };
 
 /**
- * GeoJSON Polygon geometry
+ * An area expressed as a GeoJSON Polygon geometry.
  */
 export type PlanningApplicationGeoJSONPolygon = {
   /**
-   * Array of linear rings
+   * The rings that make up the polygon. The first ring is the outer boundary and any further rings are holes inside it. Each ring needs at least four positions and closes by repeating its first position as the last.
    */
   coordinates: Array<Array<Array<number>>>;
   /**
-   * GeoJSON geometry type
+   * Geometry type discriminator. Always `Polygon`.
    */
   type: "Polygon";
 };
 
 /**
- * GeoJSON Point geometry
+ * A single location expressed as a GeoJSON Point geometry.
  */
 export type GeoJSONPoint = {
   /**
-   * Coordinate pair [longitude, latitude]
+   * A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).
    */
   coordinates: Array<number>;
   /**
-   * GeoJSON geometry type
+   * Geometry type discriminator. Always `Point`.
    */
   type: "Point";
 };
 
 /**
- * The geometry of this feature. May be a Point (site centroid), Polygon (single boundary), or MultiPolygon (disjoint site areas). Null if the geometry could not be parsed from the source data. Coordinates are in [longitude, latitude] order (WGS84, EPSG:4326).
+ * Shape of this feature: a Point for a site centre, a Polygon for a single boundary, or a MultiPolygon where the site is in several separate parts. Null when the source geometry could not be read.
  */
 export type PlanningApplicationGeometry =
   | GeoJSONPoint
   | PlanningApplicationGeoJSONPolygon
-  | PlanningApplicationGeoJSONMultiPolygon;
+  | PlanningApplicationGeoJSONMultiPolygon
+  | discriminatedUnionTypes.Unknown<"type">;
 
 /**
- * GeoJSON feature type, always 'Feature'.
+ * Object type discriminator. Always `Feature`.
  */
 export const PlanningApplicationSchemasSpatialFeaturesType = {
   Feature: "Feature",
 } as const;
 /**
- * GeoJSON feature type, always 'Feature'.
+ * Object type discriminator. Always `Feature`.
  */
 export type PlanningApplicationSchemasSpatialFeaturesType = ClosedEnum<
   typeof PlanningApplicationSchemasSpatialFeaturesType
@@ -252,52 +255,53 @@ export type PlanningApplicationSchemasSpatialFeaturesType = ClosedEnum<
 
 export type PlanningApplicationFeatures = {
   /**
-   * The geometry of this feature. May be a Point (site centroid), Polygon (single boundary), or MultiPolygon (disjoint site areas). Null if the geometry could not be parsed from the source data. Coordinates are in [longitude, latitude] order (WGS84, EPSG:4326).
+   * Shape of this feature: a Point for a site centre, a Polygon for a single boundary, or a MultiPolygon where the site is in several separate parts. Null when the source geometry could not be read.
    */
   geometry:
     | GeoJSONPoint
     | PlanningApplicationGeoJSONPolygon
     | PlanningApplicationGeoJSONMultiPolygon
+    | discriminatedUnionTypes.Unknown<"type">
     | null;
   /**
-   * Key-value metadata associated with this geometry feature. Content varies by source and may include area measurements, boundary descriptions, or source attribution.
+   * Whatever the planning authority published alongside the geometry, such as an area measurement, a boundary description or a source attribution. The keys vary by council.
    */
   properties?: { [k: string]: any } | undefined;
   /**
-   * GeoJSON feature type, always 'Feature'.
+   * Object type discriminator. Always `Feature`.
    */
   type: PlanningApplicationSchemasSpatialFeaturesType;
 };
 
 /**
- * GeoJSON object type, always 'FeatureCollection'.
+ * Object type discriminator. Always `FeatureCollection`.
  */
 export const PlanningApplicationSchemasType = {
   FeatureCollection: "FeatureCollection",
 } as const;
 /**
- * GeoJSON object type, always 'FeatureCollection'.
+ * Object type discriminator. Always `FeatureCollection`.
  */
 export type PlanningApplicationSchemasType = ClosedEnum<
   typeof PlanningApplicationSchemasType
 >;
 
 /**
- * Full application site geometry as a GeoJSON FeatureCollection (RFC 7946). May contain Point, Polygon, or MultiPolygon geometries representing the application site boundary or boundaries. Coordinates are in [longitude, latitude] order using the WGS84 datum (EPSG:4326). Polygon rings follow the right-hand rule (exterior rings are counterclockwise). This field provides the detailed site boundary when available, whereas the spatial field provides only the centroid point. Null if no geometry data was available from the planning authority.
+ * Boundary of the application site, as a GeoJSON FeatureCollection (RFC 7946). Not present when the planning authority published no boundary; spatial still gives the centre point where one is held.
  */
 export type SpatialFeatures = {
   /**
-   * Array of GeoJSON Feature objects representing the application site geometry. Most applications have a single feature, but sites spanning multiple parcels may have several.
+   * The features making up the site geometry. A site in several separate parts arrives as one MultiPolygon feature rather than as several features.
    */
   features: Array<PlanningApplicationFeatures>;
   /**
-   * GeoJSON object type, always 'FeatureCollection'.
+   * Object type discriminator. Always `FeatureCollection`.
    */
   type: PlanningApplicationSchemasType;
 };
 
 /**
- * Normalised status of the planning application. The typical lifecycle flows: received -> pending_validation -> valid -> under_consideration -> consultation -> pending_decision -> approved/rejected. Values: 'received' -- application submitted to the planning authority. 'pending_validation' -- awaiting initial administrative checks (fee payment, correct forms, ownership certificates). 'invalid' -- failed validation checks; the applicant must resubmit or provide missing information. 'valid' -- passed validation and registered; the application now proceeds to assessment. 'under_consideration' -- actively being assessed by planning officers, including site visits and policy review. 'consultation' -- in the statutory or public consultation period where neighbours and consultees may comment. 'pending_decision' -- officer assessment is complete; awaiting committee hearing or delegated decision. 'approved' -- planning permission has been granted (may be subject to conditions). 'rejected' -- planning permission has been refused by the authority. 'withdrawn' -- the applicant withdrew the application before a decision was made. 'appeal' -- the applicant has appealed the decision to the Planning Inspectorate. 'on_hold' -- processing has been temporarily paused by the authority (e.g. pending further information). 'expired' -- the application lapsed without a formal decision being issued. 'unknown' -- the original status text could not be mapped to a normalised value; check statusExternal for the raw text.
+ * How far the application has progressed, normalised so the same value means the same thing at every council. An application is 'received' once the council holds it, 'pending_validation' while the administrative checks are outstanding, then either 'invalid' when those checks fail or 'valid' once it is registered. Assessment runs through 'under_consideration', 'consultation' while neighbours and consultees may comment, and 'pending_decision' once the officer's assessment is finished. It ends at 'approved' (permission granted, possibly with conditions), 'rejected' (permission refused), 'withdrawn' (pulled by the applicant), 'appeal' (taken to the Planning Inspectorate), 'expired' (lapsed with no decision issued) or 'on_hold' (paused by the council). 'unknown' means no status could be established; read statusExternal for the council's own wording where there is any.
  */
 export const PlanningApplicationStatus = {
   Received: "received",
@@ -316,7 +320,7 @@ export const PlanningApplicationStatus = {
   Unknown: "unknown",
 } as const;
 /**
- * Normalised status of the planning application. The typical lifecycle flows: received -> pending_validation -> valid -> under_consideration -> consultation -> pending_decision -> approved/rejected. Values: 'received' -- application submitted to the planning authority. 'pending_validation' -- awaiting initial administrative checks (fee payment, correct forms, ownership certificates). 'invalid' -- failed validation checks; the applicant must resubmit or provide missing information. 'valid' -- passed validation and registered; the application now proceeds to assessment. 'under_consideration' -- actively being assessed by planning officers, including site visits and policy review. 'consultation' -- in the statutory or public consultation period where neighbours and consultees may comment. 'pending_decision' -- officer assessment is complete; awaiting committee hearing or delegated decision. 'approved' -- planning permission has been granted (may be subject to conditions). 'rejected' -- planning permission has been refused by the authority. 'withdrawn' -- the applicant withdrew the application before a decision was made. 'appeal' -- the applicant has appealed the decision to the Planning Inspectorate. 'on_hold' -- processing has been temporarily paused by the authority (e.g. pending further information). 'expired' -- the application lapsed without a formal decision being issued. 'unknown' -- the original status text could not be mapped to a normalised value; check statusExternal for the raw text.
+ * How far the application has progressed, normalised so the same value means the same thing at every council. An application is 'received' once the council holds it, 'pending_validation' while the administrative checks are outstanding, then either 'invalid' when those checks fail or 'valid' once it is registered. Assessment runs through 'under_consideration', 'consultation' while neighbours and consultees may comment, and 'pending_decision' once the officer's assessment is finished. It ends at 'approved' (permission granted, possibly with conditions), 'rejected' (permission refused), 'withdrawn' (pulled by the applicant), 'appeal' (taken to the Planning Inspectorate), 'expired' (lapsed with no decision issued) or 'on_hold' (paused by the council). 'unknown' means no status could be established; read statusExternal for the council's own wording where there is any.
  */
 export type PlanningApplicationStatus = OpenEnum<
   typeof PlanningApplicationStatus
@@ -324,143 +328,143 @@ export type PlanningApplicationStatus = OpenEnum<
 
 export type PlanningApplication = {
   /**
-   * Structured address of the application site, as scraped from the planning authority. Field availability varies by council — some provide full structured addresses whilst others provide only a raw string. Null if no address data was available.
+   * Address of the application site as the planning authority publishes it. Which lines are filled in varies by council: some publish a fully structured address, others only a single line in formattedAddress. Null when the council published no address.
    */
   address?: PlanningApplicationAddress | null | undefined;
   /**
-   * The date on which an appeal was lodged with the Planning Inspectorate, formatted as an ISO 8601 datetime string. An appeal may be lodged when an application is refused or when the authority fails to determine the application within the statutory time limit. Null if no appeal has been lodged.
+   * When an appeal was lodged with the Planning Inspectorate, as an ISO 8601 timestamp. Null when no appeal has been lodged.
    */
   appealedDate?: string | null | undefined;
   /**
-   * The current status of an appeal, if one has been lodged. Values are not normalised and reflect the terminology used by the Planning Inspectorate or the source council (e.g. 'Appeal Lodged', 'Appeal Dismissed', 'Appeal Allowed', 'Appeal Withdrawn'). Null if no appeal has been lodged or if the status is not available.
+   * Where the appeal has got to, in the wording used by the Planning Inspectorate or the council, for example 'Appeal Lodged' or 'Appeal Dismissed'. These values are not normalised. Null when no appeal has been lodged or no status was published.
    */
   appealedStatus?: string | null | undefined;
   /**
-   * Name of the planning officer assigned to assess the application. Null if the case officer was not recorded by the source council.
+   * Name of the planning officer handling the assessment. Null when the council did not publish one.
    */
   caseOfficer?: string | null | undefined;
   /**
-   * Planning constraints affecting the application site, such as conservation areas, listed buildings, tree preservation orders, or green belt designations. Null if no constraint data was available from the source.
+   * Designations recorded against the site, such as a conservation area, a listed building, a tree preservation order or green belt. Null when the council published none.
    */
   constraints?: Array<PlanningConstraint> | null | undefined;
   /**
-   * The date on which the public consultation period closed, formatted as an ISO 8601 datetime string. Comments received after this date may not be considered. Null if the date was not recorded.
+   * When the public consultation period closed, as an ISO 8601 timestamp. Null when the council did not publish the date.
    */
   consultationEndDate?: string | null | undefined;
   /**
-   * The date on which the public consultation period opened, formatted as an ISO 8601 datetime string. During this period, neighbours and statutory consultees may submit comments on the application. Null if the date was not recorded.
+   * When the public consultation period opened, as an ISO 8601 timestamp. Null when the council did not publish the date.
    */
   consultationStartDate?: string | null | undefined;
   /**
-   * ISO 8601 datetime string indicating when this record was first created in our system. This is not the date the application was submitted to the council; see receivedDate for that. Example: '2024-06-01T14:30:00.000Z'.
+   * When this application first appeared in the API, as an ISO 8601 timestamp. This is not the date the council received it; see receivedDate for that.
    */
   createdAt: string;
   /**
-   * The date on which the planning authority issued its formal decision (approval or refusal), formatted as an ISO 8601 datetime string. Null if the application has not yet been decided or the date was not recorded.
+   * When the planning authority issued its decision, as an ISO 8601 timestamp. Null while the application is undecided, or when the council did not publish the date.
    */
   decidedDate?: string | null | undefined;
   /**
-   * Free-text description of the proposed development as provided by the applicant or planning authority. Typically summarises the works being proposed (e.g. 'Erection of a two-storey rear extension and loft conversion with rear dormer'). The level of detail varies by council. Null if no description was available from the source data.
+   * The proposed works in the applicant's or the council's own words, for example 'Erection of a two-storey rear extension and loft conversion with rear dormer'. How much detail this carries varies by council. Null when the source published no description.
    */
   description?: string | null | undefined;
   /**
-   * High-level classification of the proposed development, derived from the application description and type using AI. Common values include: 'Residential' (new homes, conversions to dwellings), 'Commercial' (offices, retail, hospitality), 'Industrial' (manufacturing, warehousing), 'Mixed Use' (combination of residential and commercial), 'Infrastructure' (roads, utilities, telecommunications), 'Change of Use' (altering the permitted use class of a building). Null if the development could not be classified. This field is useful for filtering applications by broad development sector.
+   * Broad sector the proposed development falls into, worked out automatically from the description and the application type. Useful for grouping applications by the kind of development rather than the kind of consent. Null when the development could not be categorised.
    */
   developmentCategory?: string | null | undefined;
   /**
-   * Straight-line distance in metres from the application site centroid to the centre supplied in a spatial (`near`) query. Present and ordered ascending (closest first) only when the request used the `near` filter; null when this application has no site point, and omitted/null for non-spatial lookups.
+   * How far the application site is from the centre given in a `near` filter, in metres. Results carrying it are ordered closest first. Null when the request did not use `near`.
    */
   distance?: number | null | undefined;
   /**
-   * Documents associated with the planning application, including submitted plans, decision notices, consultation responses, and supporting material. May be empty if no documents have been collected from the source.
+   * Documents the planning authority published for the application: submitted plans, decision notices, consultation responses and supporting material. Empty when none have been collected.
    */
   documents?: Array<PlanningDocument> | undefined;
   /**
-   * AI reasoning and processing artefacts behind the application: how it was classified (with confidence and uncertainty) and how its documents were segmented and summarised. Only present when 'enrichment' is requested via the include parameter. Sub-arrays may be empty when the relevant pipeline has not run for this application.
+   * How the application was classified and how its documents were segmented and summarised. Present only when 'enrichment' is requested through the include parameter. Either part is empty when that step has not run for the application.
    */
   enrichment?: Enrichment | null | undefined;
   /**
-   * The date on which the planning permission expires if not implemented, formatted as an ISO 8601 datetime string. Most permissions must be commenced within three years of approval. Null if not applicable or not recorded.
+   * When the permission lapses if the development has not begun, as an ISO 8601 timestamp. Null when no expiry applies or the council did not publish one.
    */
   expiryDate?: string | null | undefined;
   /**
-   * Structured, citation-backed data extracted from the application's documents — decision outcome and refusal reasons, development specifics, section 106 obligations, the officer's assessment, and consultee responses. Only present when 'extractions' is requested via the include parameter (GET) or the include array (POST /query); omitted entirely otherwise. Each sub-extraction may itself be null when that schema has not been extracted for this application. Coverage and per-extraction verification status are reported so consumers can degrade honestly when data is partial or unverified.
+   * Structured, quote-backed data read out of the application's documents: the decision and any refusal reasons, what is being built, section 106 obligations, the case officer's assessment and the consultee responses. Present only when 'extractions' is requested through the include parameter on GET or the include array on POST /query. Each part is null when that extraction is not available, and coverage reports how many parts are present and how many have been verified.
    */
   extractions?: Extractions | null | undefined;
   /**
-   * Unique identifier for the planning application record. Use this UUID to retrieve the application via the GET /{applicationIds} endpoint.
+   * Identifier for this planning application. Pass it to GET /{applicationIds} to fetch it again.
    */
   id: string;
   /**
-   * Deduplicated gallery of images (plans, elevations, photographs) extracted from the application's documents, each with a directly-renderable CDN URL. Only present when 'images' is requested via the include parameter. May be empty when no images have been extracted — image coverage is sparse, so expect this for most applications and render an honest empty state.
+   * Plans, elevations and photographs taken from the application's documents, deduplicated, each with an address that can be rendered directly. Present only when 'images' is requested through the include parameter. Empty when no images have been extracted for the application.
    */
   images?: Array<PlanningImage> | undefined;
   /**
-   * The planning application reference number as assigned by the local planning authority. Format varies by council (e.g. 'APP/2024/0001', '24/00123/FUL', 'DC/24/0456'). This is the reference number a member of the public would use when contacting the council about the application.
+   * Reference number the local planning authority assigned to the application. The format varies by council, for example '24/00123/FUL' or 'APP/2024/0001'. This is the reference to quote when contacting the council about the application.
    */
   key: string;
   /**
-   * People associated with the application including applicants and planning agents. Contact details (phone, email) are redacted; only names and organisations are included. Null if no applicant or agent data was available.
+   * The applicants and planning agents named on the application. Only names and organisations are returned; contact details such as telephone numbers and email addresses are removed. Null when the council named nobody.
    */
   people?: People | null | undefined;
   /**
-   * Identifier for the local planning authority (LPA) or council that received the application. This is a normalised slug derived from the council name (e.g. 'lambeth', 'manchester', 'st-albans'). Use this value in the query endpoint's councils filter to retrieve all applications from a specific authority.
+   * Identifier for the local planning authority that received the application, as a slug of the council name such as 'lambeth' or 'st-albans'. Use the same value in the councils filter on POST /query.
    */
   provider: string;
   /**
-   * The date on which the planning authority received the application, formatted as an ISO 8601 datetime string (e.g. '2024-03-15T00:00:00.000Z'). This is the official submission date and is typically the earliest date in the application timeline. Null if the date was not recorded by the source. Use receivedDateFrom/receivedDateTo in the query endpoint to filter by this date.
+   * When the planning authority received the application, as an ISO 8601 timestamp. This is the submission date and usually the earliest date on the application. Filter on it with receivedDateFrom and receivedDateTo. Null when the council did not publish the date.
    */
   receivedDate?: string | null | undefined;
   /**
-   * Other planning applications related to this one, such as appeals, amendments, or linked applications at the same site. Null if no related cases were recorded.
+   * Other planning cases tied to this one, such as an appeal, an amendment, or another application at the same site. Null when none were recorded.
    */
   relatedCases?: Array<PlanningRelatedCase> | null | undefined;
   /**
-   * Composite identifier combining provider and key in the format 'provider::key' (e.g. 'lambeth::24/00123/FUL'). This provides a globally unique, human-readable identifier for the application. Use this value with the GET /sources/{sourceIds} endpoint to look up applications by their council reference.
+   * Council slug and council reference joined as `provider::key`, for example 'lambeth::24/00123/FUL'. It identifies the application across every council, and is what GET /sources/{sourceIds} accepts.
    */
   sourceId: string;
   /**
-   * Application site centroid as a GeoJSON Point geometry (RFC 7946). Coordinates are in [longitude, latitude] order using the WGS84 datum (EPSG:4326). This point represents the approximate centre of the application site, derived from the planning authority's spatial data or geocoded from the site address. Null if no spatial data was available from the source. For the full site boundary, see spatialFeatures.
+   * Centre point of the application site, as a GeoJSON Point (RFC 7946). Not present when no point is held for the application. For the site boundary rather than its centre, see spatialFeatures.
    */
   spatial?: PlanningApplicationSpatial | null | undefined;
   /**
-   * Full application site geometry as a GeoJSON FeatureCollection (RFC 7946). May contain Point, Polygon, or MultiPolygon geometries representing the application site boundary or boundaries. Coordinates are in [longitude, latitude] order using the WGS84 datum (EPSG:4326). Polygon rings follow the right-hand rule (exterior rings are counterclockwise). This field provides the detailed site boundary when available, whereas the spatial field provides only the centroid point. Null if no geometry data was available from the planning authority.
+   * Boundary of the application site, as a GeoJSON FeatureCollection (RFC 7946). Not present when the planning authority published no boundary; spatial still gives the centre point where one is held.
    */
   spatialFeatures?: SpatialFeatures | null | undefined;
   /**
-   * Normalised status of the planning application. The typical lifecycle flows: received -> pending_validation -> valid -> under_consideration -> consultation -> pending_decision -> approved/rejected. Values: 'received' -- application submitted to the planning authority. 'pending_validation' -- awaiting initial administrative checks (fee payment, correct forms, ownership certificates). 'invalid' -- failed validation checks; the applicant must resubmit or provide missing information. 'valid' -- passed validation and registered; the application now proceeds to assessment. 'under_consideration' -- actively being assessed by planning officers, including site visits and policy review. 'consultation' -- in the statutory or public consultation period where neighbours and consultees may comment. 'pending_decision' -- officer assessment is complete; awaiting committee hearing or delegated decision. 'approved' -- planning permission has been granted (may be subject to conditions). 'rejected' -- planning permission has been refused by the authority. 'withdrawn' -- the applicant withdrew the application before a decision was made. 'appeal' -- the applicant has appealed the decision to the Planning Inspectorate. 'on_hold' -- processing has been temporarily paused by the authority (e.g. pending further information). 'expired' -- the application lapsed without a formal decision being issued. 'unknown' -- the original status text could not be mapped to a normalised value; check statusExternal for the raw text.
+   * How far the application has progressed, normalised so the same value means the same thing at every council. An application is 'received' once the council holds it, 'pending_validation' while the administrative checks are outstanding, then either 'invalid' when those checks fail or 'valid' once it is registered. Assessment runs through 'under_consideration', 'consultation' while neighbours and consultees may comment, and 'pending_decision' once the officer's assessment is finished. It ends at 'approved' (permission granted, possibly with conditions), 'rejected' (permission refused), 'withdrawn' (pulled by the applicant), 'appeal' (taken to the Planning Inspectorate), 'expired' (lapsed with no decision issued) or 'on_hold' (paused by the council). 'unknown' means no status could be established; read statusExternal for the council's own wording where there is any.
    */
   status: PlanningApplicationStatus;
   /**
-   * Confidence score for the AI-driven status normalisation, expressed as a decimal between 0 and 1. A score above 0.9 indicates high confidence that the normalised status accurately reflects the original text. A score between 0.7 and 0.9 suggests reasonable confidence but some ambiguity. A score below 0.7 indicates the original text was unclear or unusual -- in this case, check statusExternal for the raw value and treat the normalised status with caution. Null if no normalisation was performed.
+   * How certain the mapping from statusExternal to status is, from 0 to 1, with higher values meaning more certain. Null when no mapping was performed.
    */
   statusConfidence?: number | null | undefined;
   /**
-   * The original, unmodified status text as published by the planning authority. Each council uses its own terminology (e.g. 'Permitted Development', 'Application Registered', 'Awaiting Decision'). This field preserves the raw value before normalisation. Useful for debugging when the normalised status is 'unknown' or when you need the exact wording used by the council.
+   * The council's own status wording, exactly as published and before normalisation, for example 'Application Permitted'. Terminology differs from council to council. Read it when status is 'unknown', or when the exact wording matters. Null when the council published no status text.
    */
   statusExternal?: string | null | undefined;
   /**
-   * Chronological history of status changes for the planning application. Provides an audit trail showing how the application progressed through the planning process. Entries are ordered by changedAt date, newest first. May be empty if status history tracking is not available for the source council.
+   * Every recorded status change for the application, newest change first, giving the trail of how it moved through the process. Empty when the source council publishes no history.
    */
   statusHistory?: Array<PlanningStatusHistory> | undefined;
   /**
-   * Normalised planning application type describing the category of development or consent being sought. Common values include: 'Full Planning' (full planning permission for new development), 'Householder' (extensions or alterations to a dwelling), 'Listed Building Consent' (works affecting a listed building), 'Prior Approval' (permitted development requiring prior approval from the authority), 'Outline Planning' (establishes the principle of development before detailed plans), 'Reserved Matters' (detailed plans following outline approval), 'Discharge of Conditions' (removing conditions attached to a previous permission), 'Tree Works' (works to protected trees or trees in conservation areas), 'Advertisement Consent' (displaying advertisements), 'Certificate of Lawfulness' (confirming existing or proposed use is lawful). Null if the type could not be determined from the source data. See typeExternal for the original text from the planning authority.
+   * Normalised type of consent the application seeks, such as a householder application, a listed building consent or a prior approval. Null when the type could not be determined. See typeExternal for the council's own wording.
    */
   type?: string | null | undefined;
   /**
-   * Confidence score for the AI-driven type normalisation, expressed as a decimal between 0 and 1. A score above 0.9 indicates high confidence that the normalised type accurately reflects the original text. A score below 0.7 suggests the original text was ambiguous or unusual -- check typeExternal for the raw value. Null if no normalisation was performed.
+   * How certain the mapping from typeExternal to type is, from 0 to 1, with higher values meaning more certain. Null when no mapping was performed.
    */
   typeConfidence?: number | null | undefined;
   /**
-   * The original, unmodified application type text as published by the planning authority. Councils use varied terminology for the same application types (e.g. 'Full Application', 'Full Planning Permission', 'FUL' may all map to the normalised type 'Full Planning'). This field preserves the raw classification. Useful when the normalised type is null or when you need the exact wording used by the council.
+   * The council's own wording for the application type, exactly as published and before normalisation. Councils name the same type differently, so this is the value to read when type is null or when the exact wording matters. Null when the council published no type text.
    */
   typeExternal?: string | null | undefined;
   /**
-   * ISO 8601 datetime string indicating when this record was last updated in our system. Changes occur when the planning authority publishes new information (status changes, new documents, amended descriptions). Example: '2024-08-15T09:00:00.000Z'.
+   * When this application was last updated, as an ISO 8601 timestamp. It moves when the planning authority publishes something new, such as a status change, a further document or an amended description.
    */
   updatedAt: string;
   /**
-   * The date on which the application was formally validated by the planning authority, formatted as an ISO 8601 datetime string (e.g. '2024-03-20T00:00:00.000Z'). Validation confirms that the application is complete (correct forms, fees paid, certificates provided) and can proceed to assessment. The statutory determination period typically begins from this date. Null if the date was not recorded by the source.
+   * When the planning authority confirmed the application was complete and registered it for assessment, as an ISO 8601 timestamp. Null when the council did not publish the date.
    */
   validatedDate?: string | null | undefined;
 };
@@ -648,11 +652,13 @@ export const PlanningApplicationGeometry$inboundSchema: z.ZodType<
   PlanningApplicationGeometry,
   z.ZodTypeDef,
   unknown
-> = z.union([
-  z.lazy(() => GeoJSONPoint$inboundSchema),
-  z.lazy(() => PlanningApplicationGeoJSONPolygon$inboundSchema),
-  z.lazy(() => PlanningApplicationGeoJSONMultiPolygon$inboundSchema),
-]);
+> = discriminatedUnion("type", {
+  Point: z.lazy(() => GeoJSONPoint$inboundSchema),
+  Polygon: z.lazy(() => PlanningApplicationGeoJSONPolygon$inboundSchema),
+  MultiPolygon: z.lazy(() =>
+    PlanningApplicationGeoJSONMultiPolygon$inboundSchema
+  ),
+});
 
 export function planningApplicationGeometryFromJSON(
   jsonString: string,
@@ -675,13 +681,13 @@ export const PlanningApplicationFeatures$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  geometry: z.nullable(
-    z.union([
-      z.lazy(() => GeoJSONPoint$inboundSchema),
-      z.lazy(() => PlanningApplicationGeoJSONPolygon$inboundSchema),
-      z.lazy(() => PlanningApplicationGeoJSONMultiPolygon$inboundSchema),
-    ]),
-  ),
+  geometry: z.nullable(discriminatedUnion("type", {
+    Point: z.lazy(() => GeoJSONPoint$inboundSchema),
+    Polygon: z.lazy(() => PlanningApplicationGeoJSONPolygon$inboundSchema),
+    MultiPolygon: z.lazy(() =>
+      PlanningApplicationGeoJSONMultiPolygon$inboundSchema
+    ),
+  })),
   properties: z.record(z.any()).optional(),
   type: PlanningApplicationSchemasSpatialFeaturesType$inboundSchema,
 });