Validate Reference Data with JSON Schema

Reference data can be valid JSON and still have the wrong shape. One row may omit a required identifier, another may encode a number as text, and a third may contain an unexpected field. JSON Schema makes those structural expectations explicit before the data enters a prompt, application, or build.

Separate structural validity from factual validity. A schema can require an integer code and a nonempty description; it cannot prove that the description is true. Use schema validation as one layer, followed by domain checks and source review where the application needs them.

A contract for a small table

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "minItems": 1,
  "items": {
    "type": "object",
    "required": ["code", "meaning"],
    "properties": {
      "code": {"type": "integer", "minimum": 100},
      "meaning": {"type": "string", "minLength": 1}
    },
    "additionalProperties": false
  }
}

The properties keyword describes allowed fields; required says which must be present. Neither the field name nor the example value creates a type automatically. A string containing 200 remains a string and fails the integer rule. Likewise, a required meaning can still be empty unless a length constraint rules that out.

Test rejected examples deliberately

Keep a valid row and several small invalid cases: a missing meaning, a string code, an empty array, and an extra unexpected property. Confirm the validator rejects each for the intended reason. Pin the schema dialect and validator configuration, especially when using composition or format annotations.

A date-time format may be an annotation rather than an enforced assertion in the selected setup. If the application relies on it for rejection, test that behavior explicitly. When schemas combine branches, unevaluatedProperties can be more appropriate than assuming additionalProperties sees properties declared in every branch.

Add the checks the schema cannot express simply

For a lookup table, verify that identifiers are unique, related slugs exist, and row counts agree with published metadata. Compare generated JSON, YAML, and TOON after decoding when a trustworthy decoder is available. Preserve original source data and explain any normalization. A build that rejects one duplicate key with a useful file and row location is more valuable than a green badge that only says the document parsed.

Finally, decide compatibility policy. Adding an optional field, adding a new enum value, and renaming a required field have different effects on consumers. Version the contract when necessary and test a real downstream client before publishing a breaking change.

Reference tables to keep nearby

• JSON Schema 2020-12 Keyword Reference — Core validation and composition keywords in JSON Schema 2020-12, with compact examples and traps.

Primary sources

These are the specifications and project documentation behind the examples. Check the relevant implementation and version before applying a pattern.

• JSON Schema validation specification
• JSON Schema reference