@@ -1,7 +1,7 @@
 name: Dataset release
 
 # A versioned snapshot of the catalog a tool can pin: tag vYYYY.MM.DD and
-# attach data.json, catalog.csv, the two feeds and llms.txt. Monthly, and on
+# attach data.json and its schema, catalog.csv, the two feeds and llms.txt. Monthly, and on
 # demand from the Actions tab. The release notes are the newest section of
 # docs/review-ledger.md. A tag that already exists is left alone.
 #
@@ -97,12 +97,12 @@ jobs:
           fi
           {
             echo
-            echo "Attached: \`data.json\` (full catalog), \`catalog.csv\`, \`feed.xml\` (new sources), \`reverified.xml\` (recent licence re-reads), \`llms.txt\`."
+            echo "Attached: \`data.json\` (full catalog), \`data.schema.json\` (its JSON Schema), \`catalog.csv\`, \`feed.xml\` (new sources), \`reverified.xml\` (recent licence re-reads), \`llms.txt\`."
             echo "\`data.json\` carries \`\"version\": \"$CATALOG_VERSION\"\`; CITATION.cff on this tag cites the same version."
             echo "Field reference: https://github.com/${GITHUB_REPOSITORY}/blob/main/site/README.md"
           } >> release-notes.md
           gh release create "$CATALOG_VERSION" \
             --target "$(git rev-parse HEAD)" \
             --title "Catalog $CATALOG_VERSION" \
             --notes-file release-notes.md \
-            site/dist/data.json site/dist/catalog.csv site/dist/feed.xml site/dist/reverified.xml site/dist/llms.txt
+            site/dist/data.json site/dist/data.schema.json site/dist/catalog.csv site/dist/feed.xml site/dist/reverified.xml site/dist/llms.txt
@@ -9,6 +9,7 @@ The catalog is published as machine-readable files on every deploy. The metadata
 | File | What it is |
 | --- | --- |
 | [`data.json`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.json) | The whole catalog: every entry with its licence fields, plus categories, guides and counts |
+| [`data.schema.json`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.schema.json) | JSON Schema (draft 2020-12) for `data.json`. The build fails if `data.json` does not match it |
 | [`catalog.csv`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/catalog.csv) | One row per entry, for spreadsheets. Lists are joined with `; ` |
 | [`feed.xml`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/feed.xml) | Atom feed of newly added sources |
 | [`reverified.xml`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/reverified.xml) | Atom feed of entries whose licence was most recently re-read |
@@ -48,7 +49,7 @@ Each entry in `data.json` has these fields. `catalog.csv` has the ones marked CS
 
 Top-level keys are `generatedAt`, `version`, `site`, `categories`, `guides`, `featured`, `stats` (counts of total, active, needs-review, deprecated and commercial entries), `filters` (`licenseFamilies` and `formatGroups`, the labels and groups behind the site's filters) and `entries`.
 
-Field names are stable. New optional fields may appear, so ignore keys you do not know rather than failing on them.
+Field names are stable, and [`data.schema.json`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.schema.json) states them as a JSON Schema the build enforces, so a field cannot be renamed or retyped without the schema changing too. New optional fields may appear, so ignore keys you do not know rather than failing on them (the schema itself rejects unknown keys, which is how the build catches drift).
 
 ## Examples
 
 
@@ -56,6 +56,7 @@ and tools that want the metadata without scraping the page. The page itself load
   (`{ path, width, height, credit? }` of the entry's preview image relative to the site root, with `credit` on CC-BY images, or `null`), `licenseFamily` (the
   coarse licence group the site filters on), and two derived sort fields, `attributionClass`
   and `licenseRank`.
+- Its shape is [`site/data.schema.json`](data.schema.json) (JSON Schema, published as `data.schema.json`); the build checks the payload against it with `lib/schema-check.mjs` and fails on any mismatch, so a renamed or retyped field must change the schema in the same commit.
 - It is regenerated from `catalog/` on every push to `main`. Field names are stable;
   new optional fields may appear. The licence facts are only as current as each entry's
   `verified` date: re-check the source before you ship on one.
 
@@ -25,6 +25,7 @@ import { listEntryFiles, idMatchesFile } from "./lib/entry-files.mjs";
 import { entryPageHtml, scriptJson } from "./lib/entry-page.mjs";
 import { LinkError, makeLinkResolver, caseMismatch } from "./lib/links.mjs";
 import { atomFeed, catalogCsv, homeJsonLd, sitemapXml } from "./lib/exports.mjs";
+import { schemaErrors } from "./lib/schema-check.mjs";
 import { llmsFullTxt, llmsTxt } from "./lib/llms.mjs";
 import { deprecationReason, MarkdownError, renderBlocks, renderInline, splitEntryBody } from "./lib/markdown.mjs";
 import { checkPage } from "./lib/page-checks.mjs";
@@ -611,6 +612,16 @@ function main() {
     entries,
   };
 
+  // data.json is held to its published schema (site/data.schema.json), so a
+  // renamed or retyped field fails here, before anything is written.
+  const schema = JSON.parse(fs.readFileSync(path.join(__dirname, "data.schema.json"), "utf8"));
+  const schemaProblems = schemaErrors(schema, JSON.parse(JSON.stringify(payload)));
+  if (schemaProblems.length) {
+    console.error(`Build failed: data.json does not match site/data.schema.json (${schemaProblems.length}); update the schema with the change:`);
+    for (const p of schemaProblems.slice(0, 20)) console.error(`  - ${p}`);
+    process.exit(1);
+  }
+
   // Empty dist rather than remove it: on Windows a server or editor holding the
   // folder open makes removing the folder itself fail with EPERM/EBUSY.
   ensureDir(DIST);
@@ -630,6 +641,7 @@ function main() {
   // data.json is the public machine-readable catalog (see site/README.md);
   // the page itself loads data.js.
   writeOut("data.json", JSON.stringify(payload, null, 2));
+  copyOut(path.join(__dirname, "data.schema.json"), "data.schema.json");
   writeOut("data.js", `window.__CATALOG__ = ${JSON.stringify(payload)};\n`);
   writeOut("catalog.csv", catalogCsv(entries, config.site.siteUrl));
   writeOut("feed.xml", atomFeed({ entries, site: config.site, generatedAt: payload.generatedAt, kind: "added" }));
 
@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.schema.json",
+  "title": "Free Game Dev Assets catalog (data.json)",
+  "description": "The shape of data.json. The build checks every payload against this file, so a renamed or retyped field fails the build until the schema changes with it. New optional fields may appear in later versions: consumers should ignore keys they do not know.",
+  "type": "object",
+  "required": ["generatedAt", "version", "site", "categories", "guides", "featured", "stats", "filters", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "generatedAt": { "type": "string", "description": "ISO 8601 build time" },
+    "version": { "type": "string", "pattern": "^v\\d{4}\\.\\d{2}\\.\\d{2}", "description": "Calendar version, vYYYY.MM.DD" },
+    "site": {
+      "type": "object",
+      "required": ["title", "tagline", "repo", "siteUrl"],
+      "properties": {
+        "title": { "type": "string" },
+        "tagline": { "type": "string" },
+        "repo": { "type": "string" },
+        "baseUrl": { "type": "string" },
+        "siteUrl": { "type": "string" }
+      }
+    },
+    "categories": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string" },
+          "blurb": { "type": "string" },
+          "view": { "enum": ["cards", "list"] }
+        }
+      }
+    },
+    "guides": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "path"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "path": { "type": "string" }
+        }
+      }
+    },
+    "featured": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/entryBase",
+        "properties": { "need": { "type": "string" } },
+        "unevaluatedProperties": false
+      }
+    },
+    "stats": {
+      "type": "object",
+      "required": ["total", "active", "needsReview", "deprecated", "commercialOk", "commercialVaries", "categories"],
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "filters": {
+      "type": "object",
+      "required": ["licenseFamilies", "formatGroups"],
+      "properties": {
+        "licenseFamilies": { "type": "object", "additionalProperties": { "type": "string" } },
+        "formatGroups": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["label", "formats"],
+            "properties": {
+              "label": { "type": "string" },
+              "formats": { "$ref": "#/$defs/stringList" }
+            }
+          }
+        }
+      }
+    },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entryBase", "unevaluatedProperties": false }
+    }
+  },
+  "$defs": {
+    "stringList": { "type": "array", "items": { "type": "string" } },
+    "entryBase": {
+      "type": "object",
+      "required": [
+        "id", "name", "url", "category", "subcategories", "license", "commercial", "attribution_required",
+        "formats", "tags", "added", "verified", "status", "path", "page", "summary", "thumb",
+        "licenseFamily", "attributionClass", "licenseRank"
+      ],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "name": { "type": "string" },
+        "url": { "type": "string" },
+        "category": { "type": "string" },
+        "subcategories": { "$ref": "#/$defs/stringList" },
+        "license": { "type": "string" },
+        "license_spdx": { "type": "string" },
+        "commercial": { "enum": [true, false, "varies", "unknown"] },
+        "attribution_required": { "enum": [true, false, "unknown"] },
+        "attribution_string": { "type": "string" },
+        "publisher": { "type": "string" },
+        "formats": { "$ref": "#/$defs/stringList" },
+        "tags": { "$ref": "#/$defs/stringList" },
+        "added": { "type": ["string", "null"], "description": "YYYY-MM-DD the entry joined the catalog" },
+        "verified": { "type": ["string", "null"], "description": "YYYY-MM-DD the licence was last read at the source" },
+        "status": { "enum": ["active", "needs-review", "deprecated"] },
+        "path": { "type": "string" },
+        "page": { "type": "string" },
+        "summary": { "type": "string" },
+        "thumb": {
+          "type": ["object", "null"],
+          "required": ["path", "width", "height"],
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string" },
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 },
+            "credit": { "type": "string" }
+          }
+        },
+        "grid_dimensions": { "type": "string" },
+        "camera_perspective": { "type": "string" },
+        "hardware_tags": { "$ref": "#/$defs/stringList" },
+        "maintenance": { "enum": ["archived", "inactive"] },
+        "engine_lock": { "type": "string" },
+        "ue_versions": { "type": "string" },
+        "licenseFamily": { "type": "string" },
+        "attributionClass": { "type": "string" },
+        "licenseRank": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}
@@ -1206,6 +1206,38 @@ eq("search: q from the URL is capped", readState(`?q=${"a".repeat(5000)}`, { q:
   has("guide: images refused", threw, "g.md:3: an image is not supported");
 }
 
+/* data.json schema (schema-check.mjs + site/data.schema.json) -------------- */
+{
+  const { schemaErrors } = await import("./schema-check.mjs");
+  const schema = JSON.parse(nodeFs.readFileSync(new URL("../data.schema.json", import.meta.url), "utf8"));
+  const entry = {
+    id: "a", name: "A", url: "https://a.example/", category: "2d", subcategories: ["x"], license: "CC0", commercial: true,
+    attribution_required: false, formats: ["PNG"], tags: [], added: "2026-01-01", verified: "2026-01-02", status: "active",
+    path: "catalog/2d/a.md", page: "entry/a/", summary: "", thumb: null, licenseFamily: "public-domain", attributionClass: "none", licenseRank: 0,
+  };
+  const payload = (over = {}) => ({
+    generatedAt: "2026-11-03T00:00:00.000Z", version: "v2026.11.03",
+    site: { title: "T", tagline: "t", repo: "r", siteUrl: "s" }, categories: { "2d": { label: "2D", view: "cards" } },
+    guides: [{ id: "g", title: "G", path: "docs/g.md" }], featured: [{ ...entry, need: "x" }],
+    stats: { total: 1, active: 1, needsReview: 0, deprecated: 0, commercialOk: 1, commercialVaries: 0, categories: 1 },
+    filters: { licenseFamilies: { cc0: "CC0" }, formatGroups: { image: { label: "Images", formats: ["PNG"] } } },
+    entries: [entry], ...over,
+  });
+  const errs = (p) => schemaErrors(schema, p).join(" | ");
+  eq("schema: a well-formed payload passes", errs(payload()), "");
+  eq("schema: a thumb object passes", errs(payload({ entries: [{ ...entry, thumb: { path: "thumbs/a.webp", width: 640, height: 360, credit: "c" } }] })), "");
+  has("schema: a renamed field fails", errs(payload({ entries: [{ ...entry, licence: "CC0", license: undefined }] })), 'unexpected key "licence"');
+  has("schema: a missing required field fails", errs(payload({ entries: [(({ summary, ...rest }) => rest)(entry)] })), 'missing required "summary"');
+  has("schema: a retyped field fails", errs(payload({ entries: [{ ...entry, licenseRank: "0" }] })), "$.entries[0].licenseRank: expected integer, got string");
+  has("schema: an unknown status fails", errs(payload({ entries: [{ ...entry, status: "retired" }] })), '"retired" is not one of');
+  has("schema: commercial outside its values fails", errs(payload({ entries: [{ ...entry, commercial: "yes" }] })), "$.entries[0].commercial");
+  has("schema: need is not an entry field", errs(payload({ entries: [{ ...entry, need: "x" }] })), 'unexpected key "need"');
+  has("schema: a bad id pattern fails", errs(payload({ entries: [{ ...entry, id: "Bad_ID" }] })), "does not match");
+  has("schema: a new top-level key fails", errs(payload({ extra: 1 })), 'unexpected key "extra"');
+  has("schema: a negative stat fails", errs(payload({ stats: { ...payload().stats, total: -1 } })), "is below 0");
+  throws("schema: an unsupported keyword is refused, not ignored", () => schemaErrors({ type: "string", maxLength: 3 }, "abcd"), 'unsupported keyword "maxLength"');
+}
+
 /* catalog ordering, grouping and chip counts (search.mjs, used by app.js) -- */
 {
   const { computeResults, sorterFor, shouldGroup, engineRank, SORTS } = await import("./search.mjs");
 
@@ -0,0 +1,92 @@
+/**
+ * A small JSON Schema (draft 2020-12) checker for the keywords
+ * site/data.schema.json uses, so the build can hold data.json to its
+ * published schema with no dependency: type, enum, required, properties,
+ * additionalProperties, unevaluatedProperties (false only, over properties
+ * and one local $ref), items, pattern, minimum and local "#/$defs/..." $ref.
+ * Any other keyword throws, so the schema cannot quietly use one this does
+ * not enforce. Pure.
+ */
+
+const KNOWN = new Set([
+  "$schema", "$id", "$defs", "$ref", "title", "description",
+  "type", "enum", "required", "properties", "additionalProperties", "unevaluatedProperties",
+  "items", "pattern", "minimum",
+]);
+
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number";
+  return typeof v;
+}
+
+function typeMatches(want, v) {
+  const t = typeOf(v);
+  return want === t || (want === "number" && t === "integer");
+}
+
+function resolve(root, ref) {
+  if (!ref.startsWith("#/")) throw new Error(`schema-check: only local $ref is supported, got ${ref}`);
+  let node = root;
+  for (const part of ref.slice(2).split("/")) {
+    node = node?.[part];
+    if (node === undefined) throw new Error(`schema-check: $ref ${ref} does not resolve`);
+  }
+  return node;
+}
+
+const show = (v) => (typeof v === "string" ? JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}…` : v) : JSON.stringify(v));
+
+/** Errors as "path: message" strings; empty when `value` matches `schema`. */
+export function schemaErrors(schema, value, { root = schema, path = "$" } = {}) {
+  const errors = [];
+  for (const key of Object.keys(schema)) {
+    if (!KNOWN.has(key)) throw new Error(`schema-check: unsupported keyword "${key}" at ${path}`);
+  }
+  if (schema.unevaluatedProperties !== undefined && schema.unevaluatedProperties !== false) {
+    throw new Error(`schema-check: unevaluatedProperties must be false at ${path}`);
+  }
+  const ref = schema.$ref ? resolve(root, schema.$ref) : null;
+  if (ref) errors.push(...schemaErrors(ref, value, { root, path }));
+
+  if (schema.type !== undefined) {
+    const types = [].concat(schema.type);
+    if (!types.some((t) => typeMatches(t, value))) {
+      errors.push(`${path}: expected ${types.join(" or ")}, got ${typeOf(value)}`);
+      return errors;
+    }
+  }
+  if (schema.enum && !schema.enum.some((e) => e === value)) {
+    errors.push(`${path}: ${show(value)} is not one of ${schema.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+  }
+  if (typeof value === "string" && schema.pattern && !new RegExp(schema.pattern, "u").test(value)) {
+    errors.push(`${path}: ${show(value)} does not match ${schema.pattern}`);
+  }
+  if (typeof value === "number" && schema.minimum !== undefined && value < schema.minimum) {
+    errors.push(`${path}: ${value} is below ${schema.minimum}`);
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => errors.push(...schemaErrors(schema.items, item, { root, path: `${path}[${i}]` })));
+  }
+  if (typeOf(value) === "object") {
+    for (const key of schema.required || []) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) errors.push(`${path}: missing required "${key}"`);
+    }
+    const props = schema.properties || {};
+    for (const [key, sub] of Object.entries(props)) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) errors.push(...schemaErrors(sub, value[key], { root, path: `${path}.${key}` }));
+    }
+    const extra = Object.keys(value).filter((k) => !Object.prototype.hasOwnProperty.call(props, k));
+    if (schema.additionalProperties === false) {
+      for (const k of extra) errors.push(`${path}: unexpected key "${k}"`);
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      for (const k of extra) errors.push(...schemaErrors(schema.additionalProperties, value[k], { root, path: `${path}.${k}` }));
+    }
+    if (schema.unevaluatedProperties === false) {
+      const evaluated = new Set([...Object.keys(props), ...Object.keys(ref?.properties || {})]);
+      for (const k of Object.keys(value)) if (!evaluated.has(k)) errors.push(`${path}: unexpected key "${k}"`);
+    }
+  }
+  return errors;
+}