Contracts & knowledge · Specification
JSON Schema
Describe which JSON values have the structure and constraints your application expects.
What it helps you do
Make machine-consumed output requirements explicit rather than relying on examples or informal prose alone.
Starting knowledge: Understand JSON objects, arrays, strings, numbers, and booleans.
- Declare the schema dialect.
- Separate required presence from the allowed type and value.
- Check actual instances with a validator that supports the chosen dialect.
The problem it came from
JSON Schema developed as a declarative language for describing and validating JSON documents. The project maintains a family of specification drafts and implementation guidance.
This entry uses the 2020-12 dialect in its example. Choosing a dialect matters because validator behavior and available keywords depend on it.
Work through an example
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"document_id": {"type": "string", "minLength": 1},
"allowed": {"type": "boolean"}
},
"required": ["document_id", "allowed"],
"additionalProperties": false
}- The boolean must be a JSON boolean, not the string "true".
- The identifier must be present and nonempty.
- The schema cannot tell whether the permission decision was justified.
Where it helps. Where it stops.
Use it when
- An AI answer or API payload must have a predictable structure.
- Several consumers disagree about which fields are required or optional.
Potential benefits
- Schemas can produce actionable structural validation failures.
- Explicit constraints reduce accidental format drift between producers and consumers.
Limits and common mistakes
- A structurally valid claim can be false or unsupported.
- Some format checks require explicit validator configuration; field presence alone does not establish semantic meaning.
The prompt below asks for this structure. It does not guarantee accuracy, complete coverage, better learning, or conformance to a standard. Treat those outcomes as separate checks.
Practise the judgment
Try a choice, inspect a boundary, then explain a case yourself. Hints and answers are available whenever you need them.
Which value satisfies a JSON boolean constraint?
Hint
Look at the value’s type, not its apparent meaning.
Explained answer
Best answer for this case: false
JSON distinguishes booleans from strings and numbers.
A permission object validates. What has been established?
Hint
A schema checks specified constraints.
Explained answer
Best answer for this case: The instance satisfies the checked schema constraints
Structural conformance does not establish the truth or authority of a decision.
Add an invalid example for the supplied schema and explain the failure.
Hint
Change only one field to isolate the failure.
Explained answer & self-review rubric
{"document_id":"d1","allowed":"yes"} fails because allowed is a string rather than a boolean. A separate example without document_id would fail the required-presence constraint.
- Give a concrete instance
- Identify the exact violated constraint
- Separate structural from semantic errors
Take it into your own work
Manual template
Use this structure yourself, with a colleague, or in your preferred writing tool.
# JSON output contract
Dialect:
Purpose:
Required fields:
Property types and allowed values:
Unknown-property policy:
Valid example:
Invalid examples and expected failures:
Validator and configuration:
Semantic checks outside the schema:
Review the result
- Are required fields actually listed as required?
- Does the validator support the dialect?
- Which truth or permission checks remain outside validation?
Use this approach with your own AI tool
Help me apply JSON Schema to the material below.
Reader and existing knowledge: [describe]
Task and desired outcome: [describe]
Use these principles: Declare the schema dialect.; Separate required presence from the allowed type and value.; Check actual instances with a validator that supports the chosen dialect..
Preserve source facts, identifiers, quantities, conditions, exceptions, and uncertainty.
Separate supplied facts from assumptions. Ask for missing information instead of inventing it.
Explain your representation choices and provide a review checklist. Do not claim formal compliance or correctness from formatting alone.
Material: [paste only information you are permitted to share]Go to the source
History and the underlying approach are grounded in these references. Examples, prompts, and practice cases here are original educational adaptations. Edition-specific details should be checked against the referenced publication.
Last editorial review: 2026-10-24. An overview is not certification, and this guide is not a reproduction of a standard.