JSON Node Visualizer Logo - Interactive Graph & Tree Visualization
JSON Visualizer
Visualizer
Data Contracts & Specifications

JSON Schema Validation: Draft 2020-12, $ref & Visual Mapping

How to design rock-solid API contracts, resolve dynamic $ref hierarchies, validate payloads with Ajv, and audit complex schemas using spatial 2D graphs.

JV
JSON Visualizer Engineering Team
Published:
Draft 2020-12 Verified • OpenAPI 3.1 Aligned
JSON Schema Validation and Visual Graph Guide Diagram
Figure 1: Resolving nested JSON Schema Draft 2020-12 definitions and mapping constraints to a 2D directed graph.
âš¡ Direct Answer: How to Validate JSON with JSON Schema

To validate JSON against a JSON Schema, define a schema object with "$schema": "https://json-schema.org/draft/2020-12/schema", declare allowable types ("type": "object"), specify "required" properties, and pass both files to an RFC-compliant validator such as Ajv (in Node.js/TypeScript) or jsonschema (in Python). To audit complex contracts visually, load the schema into our JSON Validator and graph viewer to inspect inheritance hierarchies and constraints spatially.

Table of Contents

1. Anatomy of a Modern JSON Schema

A JSON Schema is itself a valid JSON object conforming to RFC 8259. It annotates and asserts rules about the shape of another JSON document. Here is an authentic Draft 2020-12 customer payload contract:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://api.example.com/schemas/user.json",
"type": "object",
"properties": {
"userId": { "type": "integer", "minimum": 1 },
"email": { "type": "string", "format": "email" },
"address": { "$ref": "#/$defs/Address" }
},
"required": ["userId", "email"],
"additionalProperties": false
}

2. Key Changes: Draft-07 vs Draft 2020-12

Capability Draft-07 (Legacy) Draft 2020-12 (Modern)
Definitions Keyword "definitions": {} "$defs": {} (Standardized)
$ref Sibling Keywords Ignored (all siblings dropped) Evaluated alongside $ref (Description, etc.)
Array Item Validation "items": [...] (Array of schemas) "prefixItems" for tuple checking
OpenAPI Compatibility Partial divergence in OAS 3.0 100% full alignment in OAS 3.1

3. Reusable Subschemas with $ref & $defs

In large enterprise systems, defining duplicate types leads to schema drift. Using "$defs" creates modular definitions that can be referenced internally via URI fragment JSON Pointers ("#/$defs/MyType") or across separate external schemas.

4. Production Validation with Ajv (TypeScript/Node.js)

import Ajv, { ValidateFunction } from "ajv/dist/2020";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true, strict: true });
addFormats(ajv);

const validate: ValidateFunction = ajv.compile(schema);
const isValid = validate(incomingData);

if (!isValid) {
console.error("Contract Violations:", validate.errors);
}

5. Visualizing Schemas as 2D Directed Graphs

When schemas exceed 300 lines or feature deep polymorphic inheritance (oneOf, anyOf, allOf), text editors fail to convey the overall architecture. Visualizing the schema as a 2D directed graph maps parent containers to children, highlights required keys in distinct colors, and traces $ref links instantly.

6. Five Costly Schema Mistakes to Avoid

  • Forgetting "additionalProperties": false: By default, JSON Schema allows unknown properties. Attackers or buggy clients can send unauthorized keys unless explicitly forbidden.
  • Confusing "required" location: "required" must be an array on the enclosing parent object, not a boolean inside individual property definitions.
  • String/Number Type Ambiguity: Using "type": "string" for numbers like "42" creates type coercion bugs downstream in database engines.
  • Overusing anyOf instead of oneOf: anyOf matches if one OR MORE schemas pass, creating silent bugs when payloads partially match multiple models.
  • Unescaped JSON Pointers: When writing references like #/$defs/user~1profile, the tilde (~1) must escape forward slashes according to RFC 6901.

Validate & Visualize Your JSON Schema Online

Test your schemas and API payloads with our 100% client-side validator and interactive graph generator.

Launch JSON Validator âž” Open Graph Visualizer

References, Specifications & Primary Citations

In accordance with our strict Editorial Research & Citation Policy, every technical assertion is substantiated by primary standards, peer-reviewed computer science literature, or verified empirical benchmarks.

  1. [1] JSON Schema: A Media Type for Describing JSON Documents (Draft 2020-12)
    Primary Standard Specification
    Author(s): Austin Wright, Henry Andrews, Ben Hutton, Julian Sanchez Publisher / Org: Internet Engineering Task Force (IETF) Date: December 2020

    “Normative core specification defining structural validation vocabularies, dialect mechanisms, and meta-schema references.”

    Source: https://json-schema.org/draft/2020-12/json-schema-core.html
  2. [2] OpenAPI Specification v3.1.0: Full JSON Schema Alignment
    Primary Standard Specification
    Author(s): OpenAPI Initiative Publisher / Org: Linux Foundation Date: February 2021

    “Documents the convergence of OpenAPI and JSON Schema Draft 2020-12 for standardized REST API contract definition.”

    Source: https://spec.openapis.org/oas/v3.1.0
  3. [3] RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
    Primary Standard Specification
    Author(s): Tim Bray (Ed.) Publisher / Org: Internet Engineering Task Force (IETF) Date: December 2017 Version/Rev: Internet Standard (STD 90)

    “Foundational specification for valid JSON syntax and RFC 8259 value types.”

    Source: https://datatracker.ietf.org/doc/html/rfc8259