What Is JSON Schema?

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 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.