implement runtime validation for parking citations response

Author: glenflorendo

apps/web/package.json

@@ -33,6 +33,7 @@
 		"react-map-gl": "^8.1.0",
 		"use-sync-external-store": "^1.6.0",
 		"wellknown": "^0.5.0",
+		"zod": "^3.24.2",
 		"zustand": "^5.0.9"
 	},
 	"devDependencies": {

apps/web/src/lib/geojson/geojson.schema.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/* ——————————————— Schemas ——————————————— */
+
+export const PointGeometrySchema = z.object({
+	type: z.literal("Point"),
+	coordinates: z.tuple([z.number(), z.number()]),
+});
+
+export const FeatureSchema = <T extends z.ZodTypeAny>(properties: T) =>
+	z.object({
+		type: z.literal("Feature"),
+		geometry: PointGeometrySchema,
+		properties,
+	});
+
+export const FeatureCollectionSchema = <T extends z.ZodTypeAny>(featureSchema: T) =>
+	z.object({
+		type: z.literal("FeatureCollection"),
+		features: z.array(featureSchema),
+	});

apps/web/src/lib/socrata/parking-citations.schema.ts

@@ -0,0 +1,42 @@
+import { Feature, FeatureCollection, Point } from "geojson";
+import { z } from "zod";
+import { FeatureSchema, FeatureCollectionSchema } from "../geojson/geojson.schema";
+
+/* ——————————————— Schemas ——————————————— */
+
+export const ParkingCitationPropertiesSchema = z.object({
+	ticket_number: z.string(),
+	issue_date: z.string(), // ISO-like datetime string
+	issue_time: z.string(), // HHMM as string (e.g. "846")
+	meter_id: z.string().nullable(),
+	marked_time: z.string(),
+	rp_state_plate: z.string(),
+	plate_expiry_date: z.string(), // YYYYMM
+	vin: z.string().nullable(),
+	make: z.string(),
+	body_style: z.string(),
+	color: z.string(),
+	location: z.string(),
+	route: z.string().nullable(),
+	agency: z.string(),
+	violation_code: z.string(),
+	violation_description: z.string(),
+	fine_amount: z.string(),
+	agency_desc: z.string(),
+	color_desc: z.string(),
+	body_style_desc: z.string(),
+	loc_lat: z.string(),
+	loc_long: z.string(),
+});
+
+export const ParkingCitationFeatureSchema = FeatureSchema(ParkingCitationPropertiesSchema);
+
+export const ParkingCitationFeatureCollectionSchema = FeatureCollectionSchema(ParkingCitationFeatureSchema);
+
+/* ——————————————— Types ——————————————— */
+
+export type ParkingCitationProperties = z.infer<typeof ParkingCitationPropertiesSchema>;
+
+export type ParkingCitationFeature = Feature<Point, ParkingCitationProperties>;
+
+export type ParkingCitationFeatureCollection = FeatureCollection<Point, ParkingCitationProperties>;

apps/web/src/lib/socrata/parking-citations.ts

@@ -1,7 +1,7 @@
 import { multiPolygon } from "@turf/turf";
 import _ from "lodash";
 import { type GeoJSONGeometry, stringify } from "wellknown";
-import { ParkingCitationFeatureCollection, ParkingCitationProperties } from "@/types";
+import { ParkingCitationFeatureCollection, ParkingCitationFeatureCollectionSchema } from "./parking-citations.schema";
 
 type FetchParkingCitationsInput = {
 	token?: string;
@@ -24,7 +24,7 @@ const ISSUE_DATE_COLUMN = "issue_date";
 
 const EMPTY_PARKING_CITATION_FEATURE_COLLECTION = {
 	type: "FeatureCollection",
-	features: [] satisfies ParkingCitationProperties[],
+	features: [],
 } satisfies ParkingCitationFeatureCollection;
 
 const toSocrataDate = (date: Date) => date.toISOString().split("T")[0];
@@ -82,5 +82,13 @@ export const fetchParkingCitations = async ({
 		return EMPTY_PARKING_CITATION_FEATURE_COLLECTION;
 	}
 
-	return response.json();
+	const json: unknown = await response.json();
+	const parsed = ParkingCitationFeatureCollectionSchema.safeParse(json);
+
+	if (!parsed.success) {
+		console.error("Invalid parking citations response", parsed.error);
+		return EMPTY_PARKING_CITATION_FEATURE_COLLECTION;
+	}
+
+	return parsed.data;
 };

apps/web/src/types.ts

@@ -13,44 +13,6 @@ export type AnyRef<T> = RefObject<T | null>;
  */
 export type NonNullableProperties<T> = { [P in keyof T]: NonNullable<T[P]> };
 
-/**
- * Properties for a parking citation feature
- */
-export type ParkingCitationProperties = {
-	ticket_number: string;
-	issue_date: string; // ISO-like datetime string
-	issue_time: string; // HHMM as string (e.g. "846")
-	meter_id: string | null;
-	marked_time: string;
-	rp_state_plate: string;
-	plate_expiry_date: string; // YYYYMM
-	vin: string | null;
-	make: string;
-	body_style: string;
-	color: string;
-	location: string;
-	route: string | null;
-	agency: string;
-	violation_code: string;
-	violation_description: string;
-	fine_amount: string; // stored as string in source data
-	agency_desc: string;
-	color_desc: string;
-	body_style_desc: string;
-	loc_lat: string;
-	loc_long: string;
-};
-
-/**
- * A single parking citation feature
- */
-export type ParkingCitationFeature = Feature<Point, ParkingCitationProperties>;
-
-/**
- * Collection of parking citation features
- */
-export type ParkingCitationFeatureCollection = FeatureCollection<Point, ParkingCitationProperties>;
-
 export type NeighborhoodCouncilProperties = (typeof neighborhoodCouncilCollection)["features"][0]["properties"];
 
 export type NeighborhoodCouncilFeature = Feature<Polygon, NeighborhoodCouncilProperties>;