JSON Schema is a vocabulary that lets you annotate and validate JSON documents. It defines the structure, data types, required fields, and constraints of your JSON data. JSON Schema is used in OpenAPI specifications to define request and response body schemas, making it fundamental to API documentation and validation.

How do I convert JSON to JSON Schema?

Start with a representative JSON example. For each field, determine the appropriate type (string, integer, boolean, array, object). Add format annotations (email, date-time, uri) where applicable. Mark required fields. Add constraints like minimum, maximum, pattern, and enum. Tools can auto-generate a basic schema from examples, but you should always review and refine the result.

What is the difference between JSON and JSON Schema?

JSON is a data format for storing and transmitting structured data. JSON Schema is a separate specification that describes the expected structure and constraints of a JSON document. Think of JSON as the data and JSON Schema as the blueprint that validates it. JSON Schema is itself written in JSON format.

Which JSON Schema draft should I use?

For new projects, use Draft 2020-12 (the latest). For OpenAPI 3.0 compatibility, use Draft 2020-12 or Draft 7 (both are well-supported). OpenAPI 3.1 fully aligns with JSON Schema Draft 2020-12. Avoid older drafts (Draft 3, Draft 4) unless you need backward compatibility with legacy systems.

How does JSON Schema relate to OpenAPI?

OpenAPI uses JSON Schema to define the data types in your API specification. Request bodies, response bodies, parameters, and headers all use JSON Schema syntax to describe their structure. OpenAPI 3.1 is fully compatible with JSON Schema Draft 2020-12, while OpenAPI 3.0 uses a subset of JSON Schema with some extensions.

Can I validate data against a JSON Schema at runtime?

Yes. Libraries like ajv (JavaScript), jsonschema (Python), and json-schema (Ruby) validate data against JSON Schema at runtime. This is commonly used to validate API request bodies before processing them. Most web frameworks have middleware or plugins for schema validation built in.

How does Specway use JSON Schema?

Specway renders JSON Schema definitions from your OpenAPI spec as interactive, expandable type documentation. Developers can explore nested objects, see type annotations, format constraints, and required fields directly in the docs. The built-in playground validates requests against your schemas in real time.

JSON Schema is a vocabulary that lets you annotate and validate JSON documents. It defines the structure, data types, required fields, and constraints of your JSON data. JSON Schema is used in OpenAPI specifications to define request and response body schemas, making it fundamental to API documentation and validation.

How do I convert JSON to JSON Schema?

Start with a representative JSON example. For each field, determine the appropriate type (string, integer, boolean, array, object). Add format annotations (email, date-time, uri) where applicable. Mark required fields. Add constraints like minimum, maximum, pattern, and enum. Tools can auto-generate a basic schema from examples, but you should always review and refine the result.

What is the difference between JSON and JSON Schema?

JSON is a data format for storing and transmitting structured data. JSON Schema is a separate specification that describes the expected structure and constraints of a JSON document. Think of JSON as the data and JSON Schema as the blueprint that validates it. JSON Schema is itself written in JSON format.

Which JSON Schema draft should I use?

For new projects, use Draft 2020-12 (the latest). For OpenAPI 3.0 compatibility, use Draft 2020-12 or Draft 7 (both are well-supported). OpenAPI 3.1 fully aligns with JSON Schema Draft 2020-12. Avoid older drafts (Draft 3, Draft 4) unless you need backward compatibility with legacy systems.

How does JSON Schema relate to OpenAPI?

OpenAPI uses JSON Schema to define the data types in your API specification. Request bodies, response bodies, parameters, and headers all use JSON Schema syntax to describe their structure. OpenAPI 3.1 is fully compatible with JSON Schema Draft 2020-12, while OpenAPI 3.0 uses a subset of JSON Schema with some extensions.

Can I validate data against a JSON Schema at runtime?

Yes. Libraries like ajv (JavaScript), jsonschema (Python), and json-schema (Ruby) validate data against JSON Schema at runtime. This is commonly used to validate API request bodies before processing them. Most web frameworks have middleware or plugins for schema validation built in.

How does Specway use JSON Schema?

Specway renders JSON Schema definitions from your OpenAPI spec as interactive, expandable type documentation. Developers can explore nested objects, see type annotations, format constraints, and required fields directly in the docs. The built-in playground validates requests against your schemas in real time.

Developer Tool

JSON to JSON Schema Converter

Generate JSON Schema from your JSON examples. Use JSON Schema to validate API requests, generate forms, enforce data contracts, and create self-documenting APIs with Specway.

Try Specway Free API Design Guide

JSON to JSON Schema: Before & After

Here is a typical JSON response and the JSON Schema that validates it. The schema adds type annotations, required fields, format constraints, and descriptions.

Input: JSON Example

{
  "id": 123,
  "name": "Jane Smith",
  "email": "jane@example.com",
  "age": 28,
  "is_active": true,
  "roles": ["admin", "editor"],
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Output: JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "description": "Full name of the user"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email address"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "description": "Age in years"
    },
    "is_active": {
      "type": "boolean",
      "description": "Whether the account is active"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "User roles"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string" },
        "zip": { "type": "string", "pattern": "^[0-9]{5}$" }
      },
      "required": ["street", "city", "state", "zip"]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Account creation timestamp"
    }
  },
  "required": ["id", "name", "email"]
}

Why Use JSON Schema?

JSON Schema is the foundation of modern API development. Here are the most common use cases.

API Request/Response Validation

Validate incoming API requests against a schema before processing. Reject malformed data at the edge and return clear error messages. JSON Schema is the foundation of OpenAPI specification data types.

Example: Ensure POST /users requests include required fields like name and email, and that age is a positive integer.

Form Generation

Auto-generate user-friendly forms from JSON Schema. Libraries like react-jsonschema-form and ajv render forms with proper input types, validation, and error messages based on your schema definition.

Example: A schema with type: "string", format: "email" renders as an email input with built-in validation.

Data Contracts Between Services

Define shared data contracts between microservices. When producer and consumer agree on a schema, changes are detected early and backwards compatibility is enforced. This is the foundation of contract testing.

Example: The User Service and Order Service share a User schema. Breaking changes trigger CI failures.

Configuration Validation

Validate YAML/JSON configuration files against a schema. Catch typos, missing fields, and invalid values before deployment. VS Code and other editors use JSON Schema to provide autocomplete for config files.

Example: Validate docker-compose.yml, package.json, or tsconfig.json against their official JSON schemas.

Documentation Generation

Generate API documentation from JSON Schema definitions embedded in your OpenAPI spec. Tools like Specway render schema definitions as interactive documentation with expandable objects and type annotations.

Example: Import an OpenAPI spec with JSON Schema definitions and get beautiful, interactive type documentation.

Code Generation

Generate TypeScript interfaces, Go structs, Python dataclasses, and more from JSON Schema definitions. Keep your types in sync across languages and eliminate manual type maintenance.

Example: A JSON Schema User definition generates TypeScript `interface User`, Go `type User struct`, and Python `@dataclass User`.

JSON Schema Keywords Reference

The most important JSON Schema keywords you will use when defining API data types.

Keyword	Description
`type`	The data type: string, number, integer, boolean, array, object, null
`properties`	Define the properties of an object type
`required`	Array of property names that must be present
`items`	Schema for array elements
`enum`	Restrict values to a fixed set
`format`	Semantic validation: email, uri, date-time, uuid, ipv4
`minimum / maximum`	Numeric range constraints
`minLength / maxLength`	String length constraints
`pattern`	Regex pattern for string validation
`default`	Default value if not provided
`$ref`	Reference another schema definition (for reuse)
`description`	Human-readable description (shows in docs)

JSON Schema in OpenAPI Specifications

JSON Schema is used throughout OpenAPI specs to define request bodies, response bodies, parameters, and headers.

# OpenAPI 3.1 uses JSON Schema natively
openapi: 3.1.0
paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                email:
                  type: string
                  format: email
                age:
                  type: integer
                  minimum: 0
                  maximum: 150
              required:
                - name
                - email
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

See Your Schemas Come to Life

Import your OpenAPI spec into Specway and see JSON Schema definitions rendered as interactive, expandable type documentation. Developers can explore nested objects, see constraints, and test requests against your schemas in the built-in playground.

Related Resources

API Design Guide

Best practices for designing APIs developers love

API Documentation Guide

Write docs that developers actually read

YAML Reference

Quick reference for YAML syntax in OpenAPI specs

API Glossary

Every API term you need to know

Frequently Asked Questions

Common questions about JSON Schema.

Beautiful Schema Documentation

Import your OpenAPI spec with JSON Schema definitions and publish interactive API documentation in minutes.

Start Publishing Free View Pricing

Developer Tool

JSON to JSON Schema Converter

Generate JSON Schema from your JSON examples. Use JSON Schema to validate API requests, generate forms, enforce data contracts, and create self-documenting APIs with Specway.

Try Specway Free API Design Guide

JSON to JSON Schema: Before & After

Here is a typical JSON response and the JSON Schema that validates it. The schema adds type annotations, required fields, format constraints, and descriptions.

Input: JSON Example

{
  "id": 123,
  "name": "Jane Smith",
  "email": "jane@example.com",
  "age": 28,
  "is_active": true,
  "roles": ["admin", "editor"],
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Output: JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "description": "Full name of the user"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email address"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "description": "Age in years"
    },
    "is_active": {
      "type": "boolean",
      "description": "Whether the account is active"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "User roles"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string" },
        "zip": { "type": "string", "pattern": "^[0-9]{5}$" }
      },
      "required": ["street", "city", "state", "zip"]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Account creation timestamp"
    }
  },
  "required": ["id", "name", "email"]
}

Why Use JSON Schema?

JSON Schema is the foundation of modern API development. Here are the most common use cases.

API Request/Response Validation

Example: Ensure POST /users requests include required fields like name and email, and that age is a positive integer.

Form Generation

Auto-generate user-friendly forms from JSON Schema. Libraries like react-jsonschema-form and ajv render forms with proper input types, validation, and error messages based on your schema definition.

Example: A schema with type: "string", format: "email" renders as an email input with built-in validation.

Data Contracts Between Services

Example: The User Service and Order Service share a User schema. Breaking changes trigger CI failures.

Configuration Validation

Example: Validate docker-compose.yml, package.json, or tsconfig.json against their official JSON schemas.

Documentation Generation

Example: Import an OpenAPI spec with JSON Schema definitions and get beautiful, interactive type documentation.

Code Generation

Generate TypeScript interfaces, Go structs, Python dataclasses, and more from JSON Schema definitions. Keep your types in sync across languages and eliminate manual type maintenance.

Example: A JSON Schema User definition generates TypeScript `interface User`, Go `type User struct`, and Python `@dataclass User`.

JSON Schema Keywords Reference

The most important JSON Schema keywords you will use when defining API data types.

Keyword	Description
`type`	The data type: string, number, integer, boolean, array, object, null
`properties`	Define the properties of an object type
`required`	Array of property names that must be present
`items`	Schema for array elements
`enum`	Restrict values to a fixed set
`format`	Semantic validation: email, uri, date-time, uuid, ipv4
`minimum / maximum`	Numeric range constraints
`minLength / maxLength`	String length constraints
`pattern`	Regex pattern for string validation
`default`	Default value if not provided
`$ref`	Reference another schema definition (for reuse)
`description`	Human-readable description (shows in docs)

JSON Schema in OpenAPI Specifications

JSON Schema is used throughout OpenAPI specs to define request bodies, response bodies, parameters, and headers.

# OpenAPI 3.1 uses JSON Schema natively
openapi: 3.1.0
paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                email:
                  type: string
                  format: email
                age:
                  type: integer
                  minimum: 0
                  maximum: 150
              required:
                - name
                - email
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

See Your Schemas Come to Life

Frequently Asked Questions

Common questions about JSON Schema.

Beautiful Schema Documentation

Import your OpenAPI spec with JSON Schema definitions and publish interactive API documentation in minutes.

Start Publishing Free View Pricing

JSON to JSON Schema Converter

JSON to JSON Schema: Before & After

Input: JSON Example

Output: JSON Schema

Why Use JSON Schema?

API Request/Response Validation

Form Generation

Data Contracts Between Services

Configuration Validation

Documentation Generation

Code Generation

JSON Schema Keywords Reference

JSON Schema in OpenAPI Specifications

See Your Schemas Come to Life

Related Resources

API Design Guide

API Documentation Guide

YAML Reference

API Glossary

Frequently Asked Questions

What is JSON Schema?

How do I convert JSON to JSON Schema?

What is the difference between JSON and JSON Schema?

Which JSON Schema draft should I use?

How does JSON Schema relate to OpenAPI?

Can I validate data against a JSON Schema at runtime?

How does Specway use JSON Schema?

Beautiful Schema Documentation

JSON to JSON Schema Converter

JSON to JSON Schema: Before & After

Input: JSON Example

Output: JSON Schema

Why Use JSON Schema?

API Request/Response Validation

Form Generation

Data Contracts Between Services

Configuration Validation

Documentation Generation

Code Generation

JSON Schema Keywords Reference

JSON Schema in OpenAPI Specifications

See Your Schemas Come to Life

Related Resources

API Design Guide

API Documentation Guide

YAML Reference

API Glossary

Frequently Asked Questions

What is JSON Schema?

How do I convert JSON to JSON Schema?

What is the difference between JSON and JSON Schema?

Which JSON Schema draft should I use?

How does JSON Schema relate to OpenAPI?

Can I validate data against a JSON Schema at runtime?

How does Specway use JSON Schema?

Beautiful Schema Documentation

JSON to JSON Schema Converter

JSON to JSON Schema: Before & After

Input: JSON Example

Output: JSON Schema

Why Use JSON Schema?

API Request/Response Validation

Form Generation

Data Contracts Between Services

Configuration Validation

Documentation Generation

Code Generation

JSON Schema Keywords Reference

JSON Schema in OpenAPI Specifications

See Your Schemas Come to Life

Related Resources

API Design Guide

API Documentation Guide

YAML Reference

API Glossary

Frequently Asked Questions

What is JSON Schema?

How do I convert JSON to JSON Schema?

What is the difference between JSON and JSON Schema?

Which JSON Schema draft should I use?