What Is JSON Schema and How to Use It

Defining JSON Schema

JSON Schema is a standard specification for describing and validating JSON data structures. Simply put, it's a "contract" written in JSON that defines what a JSON data object should look like — which fields must be present, what type each field should be, value range constraints, and more.

JSON Schema is itself a JSON object, using specific keywords to describe rules. For example, "type": "string" means a value must be a string; "required": ["name", "age"] means these two fields are mandatory.

A Complete JSON Schema Example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A user in the system",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1,
      "description": "Unique user ID"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "uniqueItems": true
    }
  },
  "additionalProperties": false
}

Common JSON Schema Keywords

• type: Specifies data type ("string", "number", "integer", "boolean", "array", "object", "null")
• required: Array of property names that must be present
• properties: Defines the Schema for each property of an object
• minimum/maximum: Min/max value for numbers
• minLength/maxLength: Min/max length for strings
• pattern: Regular expression the string must match
• format: String format (e.g., "email", "date", "uri")
• enum: Value must be one of a specified list
• items: Schema for array items
• additionalProperties: Whether undefined additional properties are allowed

JSON Schema Versions

JSON Schema has multiple versions (drafts) with slightly different syntax and supported keywords: Draft 4 (2013) is the most widely supported version, backed by most validation libraries; Draft 6/7 (2016/2018) added new features like contains, const, if/then/else; Draft 2019-09 and 2020-12 are the latest standards with more advanced features.

Declare the version being used in the Schema via the $schema field, telling validation tools which ruleset to use when interpreting the Schema.

JSON Schema in Real-World Development

Applications in API development: In OpenAPI (Swagger) specifications, request and response data structures are described using JSON Schema; backend frameworks (like Fastify, FastAPI) can directly use JSON Schema for automatic request data validation, reducing repetitive manual validation code; frontend form validation libraries (like react-jsonschema-form) can automatically generate form interfaces and validation rules from JSON Schema.

Configuration file support: VS Code uses JSON Schema to provide IntelliSense and real-time error checking for configuration files like package.json, tsconfig.json, and .eslintrc.json — this is why editing these files in VS Code shows auto-completion and error highlighting.

$ref and $defs: Schema Reuse

For complex projects where the same data structure may be used in multiple places, JSON Schema provides the $ref (reference) mechanism to reuse Schema definitions and avoid duplication:

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": {"type": "string"},
        "city": {"type": "string"}
      }
    }
  },
  "type": "object",
  "properties": {
    "homeAddress": {"$ref": "#/$defs/address"},
    "workAddress": {"$ref": "#/$defs/address"}
  }
}

Validation Library Recommendations

• JavaScript/Node.js: ajv (fastest, supports Draft 4-2020, most popular)
• Python: jsonschema (standard library, easy to use); fastjsonschema (high performance)
• Java: networknt/json-schema-validator
• Go: santhosh-tekuri/jsonschema
• .NET: JsonSchema.Net (NuGet)