Getting Started

What is JSON Schema?

A JSON Schema is a declarative format for specifying the structure, content, and semantics of JSON data. It is written in JSON itself and provides a comprehensive vocabulary for describing data structures, including:

  • The types of values (e.g., strings, numbers, objects, arrays)

  • The properties that an object can have

  • Constraints on data values (e.g., minimum and maximum values, string lengths)

  • Data relationships and dependencies

Elements of JSON Schema

In JSON Schema, each element is defined using a dictionary (or object) with various fields that describe the component’s properties, constraints, and types.

Common Fields

These fields can be present in all types of JSON Schema elements:

type

Warning

The β€˜type’ field is required.

Determines the nature of the data. Here are all possible types:

  • Array Type:

    Represents an ordered list of items.

    {
    "type": "array"
    // Remaining fields
}

  • Boolean Type:

    Represents a true or false value.

    {
    "type": "boolean"
    // Remaining fields
}

  • Integer Type:

    Represents whole numbers without a fractional component.

    {
    "type": "integer"
    // Remaining fields
}

  • Number Type:

    Represents numeric data, including integers and floating-point numbers.

    {
    "type": "number"
    // Remaining fields
}

  • Object Type:

    Represents a collection of key-value pairs.

    {
    "type": "object"
    // Remaining fields
}

  • String Type:

    Represents textual data.

    {
    "type": "string"
    // Remaining fields
}

  • Tuple Type:

    Represent a variant of the β€˜array’ type where each position in the array can have a different schema. This allows for arrays with fixed-length and heterogeneously-typed items.

    {
    "type": "tuple"
    // Remaining fields
}

description

Note

The β€˜description’ field is optional, but can be very useful for documentation and understanding the schema.

Provides a brief description of what the element represents within the schema.

{
    "type": "string",
    "description": "The user's name"
    // Remaining fields
}

nullProperty

Note

The β€˜nullProperty’ field is optional. Its default value is false.

Warning

Ensure that β€˜nullProperty’ is correctly set based on whether the element is allowed to have null values. Incorrect settings can lead to unexpected validation behavior.

Indicates whether an element can have a null value. If nullProperty is set to true, the element can be null and, in that case, the element will not be validated and will be considered correct automatically. If set to false, the validator will give an error if the element has a null value.

{
    "type": "string",
    "nullProperty": true
    // Remaining fields
}

Specific Fields for Each Type

Each element type can have additional specific fields that define its properties and constraints. These fields are documented in detail in the sections for each type:

Benefits of Using JSON Schema

  • Validation: JSON Schema ensures that JSON data adheres to a specified structure and set of rules, making data validation straightforward and consistent.

  • Documentation: It serves as a form of documentation, clearly defining what data is expected and how it should be structured.

  • Interoperability: JSON Schema promotes interoperability between systems by providing a standard way to describe data formats.

  • Automation: Tools can automatically generate forms, APIs, and other components based on JSON Schemas, reducing development time and errors.

  • Consistency: It helps maintain data consistency across different parts of an application or between different systems.

Example of a Complete JSON Schema

Here’s a more comprehensive example of a JSON Schema for a user profile:

{
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "The unique identifier for a user"
        },
        "name": {
            "type": "string",
            "description": "The user's name"
        },
        "age": {
            "type": "integer",
            "description": "The user's age",
            "minimum": 0
        },
        "email": {
            "type": "string",
            "description": "The user's email address"
        },
        "isActive": {
            "type": "boolean",
            "description": "Whether the user is active"
        },
        "roles": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Roles assigned to the user"
        }
    }
}