Draft:JSON Schema

JSON Schema

Filename extension	.schema.json, .json
Internet media type	application/schema+json
Developed by	JSON Schema Working Group
Type of format	Data interchange format
Extended from	JSON
Standard	Draft 2020-12
Open format?	Yes
Website	json-schema.org

JSON Schema is a specification for defining the structure and constraints of JSON (JavaScript Object Notation) data. It allows for validation, documentation, and interaction control of JSON-based formats, making it widely used in API development, data validation, and configuration management.

Overview

JSON Schema provides a declarative way to describe JSON data. It enables validation by defining expected properties, types, formats, and constraints. JSON Schema is widely used to enforce consistency in data structures and improve interoperability between systems.

Example

A sample JSON document and its schema:

JSON Data:

{
  "productId": 1,
  "productName": "A green door",
  "price": 12.50,
  "tags": ["home", "green"]
}

JSON Schema:

{
  "$schema": "http://json-schema.org/draft/2020-12/schema",
  "title": "Product",
  "type": "object",
  "properties": {
    "productId": { "type": "integer" },
    "productName": { "type": "string" },
    "price": { "type": "number", "minimum": 0 },
    "tags": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["productId", "productName", "price"]
}

Features

Data Validation

JSON Schema validates data against predefined rules:

{
"type": "string",
"minLength": 5,
"pattern": "^[A-Z][a-z]+$"
}

This schema ensures a string starts with a capital letter, followed by lowercase letters, with minimum length of 5 characters.

Documentation

JSON Schema provides self-documenting metadata:

{
  "title": "User",
  "description": "A user account in the system",
  "properties": {
    "username": {
      "description": "Unique identifier for the user"
    }
  }
}

The title, description, and property descriptions help developers understand the data structure.

Hypermedia Support

JSON Hyper-Schema extends JSON Schema for hypermedia-driven APIs:

{
  "links": [
    {
      "rel": "self",
      "href": "/users/{id}",
      "templateRequired": ["id"]
    }
  ]
}

This defines a link relation that constructs URLs using instance data, enabling HATEOAS principles.

Interoperability

JSON Schema works across different programming languages.

A schema could be emitted by a library in one programming language, and used for validation in a different programming language.

Versions

JSON Schema has undergone multiple revisions:

• Draft 4 (2013) – First widely adopted version.
• Draft 6 (2017) – Introduced new keywords and enhanced validation.
• Draft 7 (2018) – Added support for complex validation scenarios.
• Draft 2019-09 (2019) – Introduced dynamic references and new annotation features.
• Draft 2020-12 (2020) – The latest version, refining features and improving interoperability.

Implementations

JSON Schema is supported in various programming languages:

• Python: The 'jsonschema' library provides validation capabilities.
• JavaScript: The Ajv library offers efficient JSON Schema validation.
• Java: Libraries such as Everit JSON Schema enable schema validation in Java applications.

Applications

JSON Schema is commonly used in:

• API Development: Ensures consistency in request and response formats.
• Configuration Management: Validates configuration files for correctness.
• Data Storage: Helps define structured data models in NoSQL databases.

Tools

Several tools facilitate working with JSON Schema:

• JSON Schema Validator: Online tool for validation.
• JSON Builder: Interactive tool for creating and testing JSON structures.

See also

• JSON
• XML Schema (W3C)
• OpenAPI Specification

External links

• Official JSON Schema website