The JSON Schema allows for the validation of JSON objects, and is used by OpenAPI & AsyncAPI. JSON Schema is a fundamental building block of the enterprise, and is ubiquitous across operations, whether teams are aware of it or not. JSON Schema is essential to standardizing and streamlining API operations across REST, GraphQL, and event-driven APis.

Also known as: JSON Schema, JSON Schema Draft

Standards

• IETF (JSON Schema WG) JSON Schema Draft 2020-12 (Core)
• IETF (JSON Schema WG) JSON Schema Draft 2020-12 (Validation)
• IETF (JSON Schema WG) JSON Schema Draft 2019-09
• IETF (JSON Schema WG) JSON Schema Draft 07
• IETF (JSON Schema WG) JSON Hyper-Schema (Draft 2019-09)
• IETF RFC 8259 — JSON
• IETF RFC 6901 — JSON Pointer
• IETF RFC 6902 — JSON Patch
• OpenAPI Initiative OpenAPI 3.1 (full alignment with JSON Schema 2020-12)

HTTP Headers

Media Types

• application/schema+json — Proposed media type for JSON Schema documents.
• application/schema-instance+json — Proposed media type for instances validated by a JSON Schema.
• application/json — Default transport for both schemas and instances.

OpenAPI Expression

• components.schemas (OpenAPI 3.x) — Reusable schema definitions; OAS 3.1 uses JSON Schema 2020-12 vocabulary, OAS 3.0 uses a subset.
• schema (OpenAPI 3.x) — Inline schema on a parameter, request body, response, or header.
• $schema (JSON Schema 2020-12) — Optional dialect identifier supported in OAS 3.1 schemas.
• $ref (JSON Schema / OAS) — Reference to another schema by URI.

Link Relations

• describedby — RFC 8288 — Associates an instance document with its JSON Schema.
• profile — RFC 6906 — Identifies the schema/profile an instance conforms to.

Governance Rules

• oas3-valid-media-example (Spectral built-in) — Example values must validate against the declared schema.
• oas3-schema (Spectral built-in) — Inline schemas must validate against the JSON Schema dialect declared by the OAS version.
• no-$ref-siblings (Spectral built-in) — Properties alongside $ref are ignored in OAS 3.0 (allowed in 3.1 / JSON Schema 2020-12).

Risk & Compliance

OWASP:

• OWASP API Security Top 10: API6:2023 Unrestricted Access to Sensitive Business Flows — missing schemas allow over-posting / mass assignment
• OWASP API Security Top 10: API3:2023 Broken Object Property Level Authorization — schemas without additionalProperties:false leak fields

Compliance:

• PCI DSS v4 Req. 6.2 — input validation against documented contracts
• HIPAA 45 CFR §164.312(c)(1) — integrity controls require validated data shapes
• GDPR Art. 5 — data minimization benefits from explicit schemas

Security: Loose schemas (no additionalProperties:false, missing format/pattern, unbounded strings/arrays) cause injection, ReDoS, and mass-assignment bugs. Pin a $schema dialect, validate at the edge, and fail closed on unknown properties.

Tools

• Ajv — Validator (JS) (MIT)
• jsonschema (Python) — Validator (Python) (MIT)
• JSON Schema Store — Registry of schemas (Apache-2.0)
• quicktype — Schema-to-type codegen (Apache-2.0)
• json-schema-faker — Mock data generator (MIT)
• Hyperjump JSV — Validator / playground (MIT)

Suggested Metrics

• schema_validation_failure_rate — Share of requests/responses rejected by schema validation at the edge.
• schema_coverage — Share of API operations whose request and response bodies have a defined schema.
• schema_strictness_score — Composite score for additionalProperties:false, required arrays, and bounded types.
• schema_drift_events — Count of breaking changes detected between schema versions.

Example Implementations

• Stripe — JSON Schema embedded inside the OpenAPI document for every object.
• GitHub — REST API description uses JSON Schema throughout; webhook payloads also schema-described.
• Kubernetes — OpenAPI / CRD schemas drive validation and codegen across the ecosystem.

Related Properties

• Openapi
• Asyncapi
• Graphql schema
• Webhooks

Tags

• Machine-Readable
• Schema
• Validation

All Community Properties