What is a JSON Schema?

<p>If you're a developer, you likely work with JSON a lot. But how do you define and validate JSON and prevent problems from malformed JSON data?</p> <p>This article explores what a JSON schema is, some examples of JSON schemas, and who decides what one should look like.</p> <h2 id="heading-prerequisites">Prerequisites</h2> <p>To understand this article, you need to <a href="https://thenetworkbits.com/an-overview-of-json/">know some JSON basics</a> and have a <a href="https://www.freecodecamp.org/news/how-apis-work/">general understanding of APIs</a> and how they work.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ul> <li><p><a href="#heading-whats-the-deal-with-json">What's the Deal with JSON</a>?</p> </li> <li><p><a href="#heading-what-is-validation">What is Validation</a>?</p> </li> <li><p><a href="#heading-the-structure-of-a-json-schema">The Structure of a JSON Schema</a></p> </li> <li><p><a href="#heading-how-to-create-a-json-schema">How to Create a JSON Schema</a></p> </li> <li><p><a href="#heading-json-schema-use-cases">JSON Schema Use Cases</a></p> <ul> <li><p><a href="#heading-openapi">OpenAPI</a></p> </li> <li><p><a href="#heading-azure-resource-manager-arm-templates">Azure Resource Manager (ARM) Templates</a></p> </li> </ul> </li> <li><p><a href="#heading-the-json-schema-project">The JSON Schema Project</a></p> </li> </ul> <h2 id="heading-whats-the-deal-with-json">What's the Deal with JSON?</h2> <p><a href="https://thenetworkbits.com/an-overview-of-json/">JSON</a> is a popular document format typically used for the interchange of data through APIs. It's lightweight, easily readable by both humans and machines, and is supported by a lot of programming languages.</p> <p>But JSON objects aren't rigid, and can be built to represent different types of data. This means that it's flexible, but it doesn't enforce a data model or constraints. This can introduce problems between the communicating parties.</p> <p>For example, if a server expects cart items, and it receives an object with payment transaction data, it could get confused and not parse it correctly. Maybe even crash.</p> <p>Or if a server handles messaging between users of an app and expects a certain structure of payload, but the client sent something different, it could break the app during parsing or lead to security compromises.</p> <p>That’s why there's validation.</p> <h2 id="heading-what-is-validation">What is Validation?</h2> <p>It's always a good practice to validate your forms before any data is sent. Validation happens when data that's entered into the form gets checked against the expected structure and data types.</p> <p>If the data entered has another format, structure, or data type from what's expected and acceptable, the form is rejected and isn't sent to the server. This protects the server from parsing the wrong type of data, and also from potential security issues.</p> <p>A JSON schema is a JSON document that describes the expected format of other JSON documents. It basically restricts the type of JSON data the server can receive and accept, and ensures that only the right type of data is parsed by the server.</p> <p>Configuration files like package.json in node.js, and even the Azure ARM template use JSON. These have to be validated against a schema to ensure that the files are written with the correct syntax and structure so they can be understood by the system. Validators do this, and they help prevent any problems that might arise from improper parsing.</p> <h2 id="heading-the-structure-of-a-json-schema">The Structure of a JSON Schema</h2> <p>A normal JSON file contains data, while a JSON schema contains rules about the data. The schema is declarative.</p> <p>Let's look at an example of a regular JSON file with data:</p> <pre><code class="language-json"> { "username": "chidiadi", "followers": 2200 } </code></pre> <p>Now here's the schema representing the structure and constraints of the JSON data:</p> <pre><code class="language-json">{ "type": "object", "properties": { "username": { "type": "string" }, "followers": { "type": "integer" } } } </code></pre> <p>The JSON schema consists of JSON objects too, but these objects represent the constraints and syntax of the data.</p> <p>For example, this schema expects a JSON object that has two properties: username and followers. For the username property, it should be a string (which is a data type supported by JSON). For the followers property, it should be an integer. The parent object itself is an “object” type.</p> <p>This is the basic structure of a JSON schema. You can then build on this for a more complex and comprehensive schema based on your use case.</p> <h2 id="heading-how-to-create-a-json-schema">How to Create a JSON Schema</h2> <p>To create a basic schema, you need to:</p> <ol> <li><p>Define the schema keyword, <code>$schema</code></p> </li> <li><p>Define the schema keyword, <code>$id</code></p> </li> <li><p>Then define the <code>title</code> and <code>description</code> keywords (which are schema annotations)</p> </li> <li><p>Define the <code>type</code> and <code>properties</code> validation keywords</p> </li> </ol> <p>The <code>$schema</code> keyword is used to declare what version of the JSON schema specification your schema adheres to. Example:</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema" } </code></pre> <p>The <code>$id</code> keyword is used to give that schema a unique identifier (URI) so you can reference it from another schema. This allows you to reuse and organize your schemas. Example:</p> <pre><code class="language-json">{ "$id": "http://yourdomain.com/schemas/followers.json" } </code></pre> <p>They can then be referenced with the <code>$ref</code> keyword from another schema.</p> <pre><code class="language-json">{ "$ref": "http://yourdomain.com/schemas/followers.json" } </code></pre> <p>The <code>title</code> and <code>description</code> keywords are annotations. They're used to describe what the schema is for.</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "http://yourdomain.com/schemas/followers.json" "title": "Followers Schema", "description": "Number of followers per person", } </code></pre> <p>So far, all the keywords we've mentioned don't affect the output of the validation. They haven't said anything about what the expected JSON document should be like, or what to validate against. That is what <code>type</code> and <code>properties</code> keywords do. They are <em>validation keywords</em>.</p> <p>The type keyword determines the type of instance being validated by the schema. That could be a <code>string</code>, an <code>object</code>, an <code>array</code>, a <code>number</code>, <code>boolean</code> or <code>null</code>.</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "http://yourdomain.com/schemas/followers.json" "title": "Followers Schema", "description": "Number of followers per person", "type":"object" } </code></pre> <p>Now, if you send some JSON that consists of an array as the parent in the file, it will be rejected. But what should the object contain? That's where the <code>properties</code> keyword comes in.</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "http://yourdomain.com/schemas/followers.json" "title": "Followers Schema", "description": "Number of followers per person", "type":"object", "properties":{ "username": { "description":"The username of the user", "type": "string" }, "followers": { "description":"The number of followers user has", "type": "integer" } } } </code></pre> <p>Here, we've added keys that are expected in the JSON file: <code>username</code> and <code>followers</code>. So, files containing other keys than that will fail validation.</p> <p>This will pass:</p> <pre><code class="language-json">{ "username": "chidiadi", "followers": 2200 } </code></pre> <p>And this will fail:</p> <pre><code class="language-json">{ "username": "chidiadi", "name":"Chidiadi Anyanwu", "followers": 2200, } </code></pre> <p>It will fail because that extra <code>name</code> key in the JSON file wasn't included in the schema. The <code>description</code> keyword in those keys are just annotations to tell the developer or whoever is going through the schema file what those keys are all about.</p> <p>There's also a <code>required</code> keyword that can be used to specify what keys in the JSON file <em>have to</em> be there to be accepted. For example, if we want to reject any JSON file sent without populating the <code>username</code> field, we could make it required.</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "http://yourdomain.com/schemas/followers.json" "title": "Followers Schema", "description": "Number of followers per person", "type":"object", "properties":{ "username": { "description":"The username of the user", "type": "string" }, "followers": { "description":"The number of followers user has", "type": "integer" } }, "required":["username"] } </code></pre> <p>The <code>required</code> keyword is a validation keyword for objects, and the value of this keyword must be an array. Not including the keyword is akin to an empty array. You can add multiple keys to that array. For example, if we want both the username and follower count to be compulsory keys in the JSON file, we can put both of them there:</p> <pre><code class="language-json">{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "http://yourdomain.com/schemas/followers.json" "title": "Followers Schema", "description": "Number of followers per person", "type":"object", "properties":{ "username": { "description":"The username of the user", "type": "string" }, "followers": { "description":"The number of followers user has", "type": "integer" } }, "required":["username","followers"] } </code></pre> <h2 id="heading-json-schema-use-cases">JSON Schema Use Cases</h2> <h3 id="heading-openapi">OpenAPI</h3> <p>According to the OpenAPI Initiative,</p> <blockquote> <p>“The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.”</p> </blockquote> <p>Basically, it gives developers a way to document their API design in a way that's easy for them to understand and track their development. It also allows others who need to consume the API to understand what they need to know to use it.</p> <p>OAS is a specification for describing APIs. It uses schema definitions (based on a JSON schema) to describe the structure of requests and responses. OpenAPI documents, also known as OpenAI Descriptions (OAD), can be written in JSON or YAML.</p> <p>Here's an example in JSON format:</p> <pre><code class="language-json">{ "openapi": "3.2.0", "info": { "title": "Counter API", "version": "1.0.0", "description": "A simple API that stores and increments a counter." }, "servers": [ { "url": "https://api.example.com" } ], "paths": { "/counter": { "get": { "summary": "Get the current counter value", "operationId": "getCounter", "responses": { "200": { "description": "Current counter value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } } } } }, "post": { "summary": "Increment the counter", "operationId": "incrementCounter", "responses": { "200": { "description": "Updated counter value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } } } } } } }, "components": { "schemas": { "Counter": { "type": "object", "properties": { "value": { "type": "integer", "example": 42 } }, "required": ["value"] } } } } </code></pre> <p>For YAML:</p> <pre><code class="language-yaml">openapi: 3.2.0 info: title: Counter API version: 1.0.0 description: A simple API that stores and increments a counter. servers: - url: https://api.example.com paths: /counter: get: summary: Get the current counter value operationId: getCounter responses: "200": description: Current counter value content: application/json: schema: $ref: "#/components/schemas/Counter" post: summary: Increment the counter operationId: incrementCounter responses: "200": description: Updated counter value content: application/json: schema: $ref: "#/components/schemas/Counter" components: schemas: Counter: type: object properties: value: type: integer example: 42 required: - value </code></pre> <p>Here, we have one schema object, a counter. This schema object describes the structure of the request and response the API should receive and send, respectively.</p> <p>The OAD describes an API for a simple counter application with URL, “<code>https://api.example.com/counter</code>”, that accepts two HTTP methods: POST for increasing the counter, and GET for retrieving the current number in the counter.</p> <h3 id="heading-azure-resource-manager-arm-templates">Azure Resource Manager (ARM) Templates</h3> <p>The Azure Resource Manager (ARM) is responsible for creating, deleting, and updating resources in an Azure account. The Azure portal, REST clients, Azure Powershell, and Azure CLI all depend on it to provision resources. You can also define templates for the provisioning of infrastructure using the ARM template.</p> <p>The ARM template is a JSON file that declaratively defines the infrastructure and configuration of a project. It defines the resources to be deployed to a tenant, resource group, subscription, or management group.</p> <p>Here’s an example of an ARM template. This is an example from the documentation:</p> <pre><code class="language-json"> { "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "location": { "type": "string", "defaultValue": "[resourceGroup().location]" } }, "resources": [ { "type": "Microsoft.Storage/storageAccounts", "apiVersion": "2025-06-01", "name": "mystorageaccount", "location": "[parameters('location')]", "sku": { "name": "Standard_LRS" }, "kind": "StorageV2" } ] } </code></pre> <p>This template creates a storage account of name <code>mystorageaccount</code>, using the location of the resource group as the location for the storage account.</p> <p>As you can see, it has a schema keyword that links to the JSON schema created by the Azure team for the validation of the ARM templates. So, when a template is to be deployed, it's validated against that schema.</p> <h2 id="heading-the-json-schema-project">The JSON Schema Project</h2> <p>It's easy to confuse a JSON schema as a concept with the JSON Schema Project. But JSON Schema is an open source project that works closely with the Internet Engineering Task Force (IETF). Its aim is to harmonize the specifications for building JSON schemas.</p> <p>The point is that anyone building JSON schemas all over the world can use the same templates, assumptions, formats, and structure, which will increase the interoperability of systems that use JSON. And this is what JSON is all about as a file interchange format.</p> <p>As you can see in the screenshot below, the Azure ARM template schema was built on top of a version of a JSON schema from the JSON Schema project:</p> <img src="https://cdn.hashnode.com/uploads/covers/66d08331fe16681b64d858db/49cbf0f6-7dbe-4dfb-bf2b-f8d6204a44c4.png" alt="49cbf0f6-7dbe-4dfb-bf2b-f8d6204a44c4" style="display:block;margin:0 auto" width="887" height="610" loading="lazy"> <p>To learn more about the JSON Schema project, you can visit their <a href="https://json-schema.org/">website</a>.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>JSON schemas are used all around the world, but they're often not well-understood or talked about. Schemas are a foundational technology relied on by APIs and projects like OpenAPI, AsyncAPI, HL7 FHIR and SDFormat, so they're worth learning about as a dev. Share this article if you enjoyed it. You can also reach out to me on <a href="https://linkedin.com/in/chidiadi-anyanwu">LinkedIn</a> or <a href="https://x.com/chidiadi01">X</a>.</p>