What is JSON Schema?

Gbadebo Bello

October 23, 2023

JSON Schema is a declarative language that provides a standardized way to describe and validate JSON data. It describes the content, structure, data types, and expected constraints within a JSON document, which helps ensure the consistency and integrity of JSON data in different applications.

Here, we will discuss the importance of JSON Schema and explain how it relates to JSON. We’ll also review some common use cases for JSON Schema, walk through its benefits, and highlight how the Postman API Platform can help you get the most out of what JSON Schema has to offer.

Why is JSON Schema important?

JSON is a lightweight, text-based data exchange format that humans and machines can read and write. Over the years, it has become the industry standard for sharing data across multiple applications and systems, especially in web and JavaScript-based applications.

JSON makes it easy to store and exchange data, but it lacks the ability to communicate additional information, such as the shape of the data, which fields are missing, or what similar data is supposed to look like. It also cannot provide additional context to its properties, which leaves room for too many assumptions and can make it difficult to work with. Let’s take a look at the JSON object below:

{
    "id": "123",
    "name": "John Doe",
    "age": 30,
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY"
    },
    "interests": ["sports", "music"],
    "createdAt": "2013-08-14T01:10:00Z"
}

The above JSON contains some information about a specific user, but it omits details that can lead to certain limitations when working with it. For instance, this JSON is:

• Ambiguous: JSON can be open to multiple interpretations, and our example does not tell us which fields are required or optional, or what their respective types are. For example, we do not know if the ID field should always be a string, a number, or either.  Additionally, if it should be a string, we do not know the data format of the string. Should it be a UUID or an incremented number, as shown in the example? This lack of clarity leaves us with a lot of assumptions.
• Incomplete: A JSON document does not tell us everything we need to know about the data it represents. For example, the user’s address might include a zip code, or the user could have a mobile number, but there is no way to know which fields were omitted.
• Lacking documentation: The JSON data format does not have support for comments. This means there is no standard way of describing the fields in a JSON data.
• Lacking standardized validation and data constraints: JSON lacks a built-in mechanism for defining and enforcing data validation rules and constraints. In our example data, for instance, we can’t specify that users are expected to be at least 18 years old, or that their interests should be one of some predefined list of interests (rather than arbitrary words).

JSON Schema is a blueprint for JSON data that solves all of these issues. It defines the rules, structure, and constraints that the data should follow, which leaves minimal room for assumptions and makes it a lot easier to predict the nature and behavior of JSON data.

JSON Schema uses a separate JSON document to provide the JSON data’s blueprint, which means the schema itself is also machine and human-readable. Let’s take a look at what the schema for our example JSON data above will look like:

{

    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Example user object",
    "description": "This is an example user object used to explain the importance of JSON Schema.",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "This is the ID of the user",
            "format": "UUID"
        },
        "name": {
            "type": "string",
            "description": "This is the full name of the user",
        },
        "age": {
            "type": "number",
            "description": "This is the age of the user. We only allow adult users.",
            "minimum": 18,
        },
       "address": {
            "type": "object",
            "properties": {
                "streetAddress": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" },
                "zipcode": { "type": "string" },
                "country": { "type": "string" }
            },
            "required": ["streetAddress", "city", "state", "zipcode", "country"]
            },
        "interests": {
            "type": "array",
            "items": {
                "type": "string",
                "enum": ["sports", "music", "movies", "books"]
            }
        },
        "createdAt": {
            "type": "string",
            "format": "date-time"
        },
    },
    "required": ["id", "name", "address"]
}

As you can see, the schema above provides a lot more context to our initial JSON data. The schema clearly defines the type and constraints of each field, and it provides descriptions where necessary. For example, if we had data containing a user who is 16 years old, it would be invalid because the schema specifies that users need to be at least 18 years old.

What are some of the use cases of JSON Schema?

JSON Schema is widely used by a lot of applications for a wide range of purposes, some of which go beyond JSON data validation. Let’s take a look at some of these use cases:

• API data validation: JSON Schema is very commonly used to validate data that is sent and received through API endpoints. API Specifications like the OpenAPI and AsyncAPI have embedded JSON Schema and are used extensively to validate all kinds of data, such as request headers, request and response bodies, and query and path parameters.
• Configuration validation: JSON is commonly used for configuration files in software applications, which JSON Schema can be used to validate. This ensures that these configuration files are correctly formatted and contain valid settings, which prevents misconfigurations that could lead to application errors.
• Dynamic data generation: JSON Schema makes it possible to generate dynamic data that conforms with the schema. For example, example responses to an API request can be generated based on an API definition that uses JSON Schema. These example responses can then be used to create mock servers.
• Dynamic form generation: JSON Schema’s declarative nature makes it possible to represent form data and its respective validations as a schema definition. This allows for forms to be dynamically generated based on a schema. Furthermore, the responses to the form can be validated against the schema, which makes it easy to build dynamic forms (such as registration forms and contact forms) with several custom validations.
• Data transformation and ETL (Extract, Transform, Load): When integrating data from different sources or performing ETL processes, JSON Schema can be employed to ensure that the transformed data maintains a consistent structure. It helps map and validate data during transformation, reducing data integration challenges.

JSON Schema has a lot of other exciting use cases. This article highlights a few real-world use cases and how different companies make use of JSON Schema in production.

What are the benefits of working with JSON Schema?

JSON Schema offers numerous benefits when working with JSON data, some of these benefits include:

• Data contracts: JSON Schema acts as a contract between data providers and consumers. It specifies the data format and constraints, reducing misunderstandings, assumptions, and disagreements about data expectations.
• Data validation: JSON Schema provides a robust mechanism for validating JSON data against predefined rules and constraints. It ensures that the data adheres to the expected structure and data types, preventing the use of invalid or unexpected data.
• Data governance: JSON Schema can be a valuable tool for data governance and compliance efforts. It helps organizations maintain control over the structure and quality of their data, which is crucial for regulatory compliance and data management best practices.
• Improved data quality: By enforcing data validation through JSON Schema, you can significantly improve data quality and consistency within your applications and systems. This leads to fewer data-related errors and more reliable processes.
• Documentation: JSON Schema serves as a documentation for the expected structure and constraints of JSON data. It provides a clear and standardized way to communicate data requirements as descriptions, making it easier for API consumers to understand how to work with the data.

How can Postman help you work with JSON Schema?

The Postman API Platform includes several features that make it easy to utilize JSON Schema in your API development workflows. With Postman, you can:

• Leverage built-in support for schema validation: Postman uses libraries like Ajv JSON Schema Validator to validate the structure of your JSON data against a schema. For instance, you can validate the structure of an API response against a predefined schema in test scripts, or validate the structure of a request body in a pre-request script.
• Work with JSON Schema in your API definitions: Postman’s API Builder allows you to create an API using a wide range of API specifications, including OpenAPI and AsyncAPI. These specifications let you describe your API data using JSON Schema, and Postman’s API Builder supports and understands API schemas authored within your API definition.
• Generate a Postman Collection based on your API schema: Postman’s API Builder lets you generate a collection from an API definition. During the generation process, the API Builder provides an option that allows you to generate request and response parameters based on the schema in your API definition.
• Automatically validate your collections: When you generate a collection from an API definition, Postman helps you keep them in sync by constantly validating your collection data against your API schema. This ensures that your API definition remains the single source of truth for your API.

To learn more about JSON Schema, visit their official website.