This article explores what a JSON schema is, some examples of JSON schemas, and who decides what one should look like.

Prerequisites

To understand this article, you need to know some JSON basics and have a general understanding of APIs and how they work.

Table of Contents

• What's the Deal with JSON?

• What is Validation?

• The Structure of a JSON Schema

• How to Create a JSON Schema

• JSON Schema Use Cases

  • OpenAPI

  • Azure Resource Manager (ARM) Templates

• The JSON Schema Project

What's the Deal with JSON?

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

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.

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.

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.

That’s why there's validation.

What is Validation?

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.

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.

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.

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.

The Structure of a JSON Schema

A normal JSON file contains data, while a JSON schema contains rules about the data. The schema is declarative.

Let's look at an example of a regular JSON file with data:

 {
  "username": "chidiadi",
  "followers": 2200
}

Now here's the schema representing the structure and constraints of the JSON data:

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "followers": {
      "type": "integer"
    }
  }
}

The JSON schema consists of JSON objects too, but these objects represent the constraints and syntax of the data.

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.

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.

How to Create a JSON Schema

To create a basic schema, you need to:

1. Define the schema keyword, $schema

2. Define the schema keyword, $id

3. Then define the title and description keywords (which are schema annotations)

4. Define the type and properties validation keywords

The $schema keyword is used to declare what version of the JSON schema specification your schema adheres to. Example:

{ 
    "$schema": "https://json-schema.org/draft/2020-12/schema" }

The $id 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:

{ 
    "$id": "http://yourdomain.com/schemas/followers.json" 
}

They can then be referenced with the $ref keyword from another schema.

{ 
    "$ref": "http://yourdomain.com/schemas/followers.json" 
}

The title and description keywords are annotations. They're used to describe what the schema is for.

{ 
  "$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",
 }

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 type and properties keywords do. They are validation keywords.

The type keyword determines the type of instance being validated by the schema. That could be a string, an object, an array, a number, boolean or null.

{ 
  "$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"
 }

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 properties keyword comes in.

{ 
  "$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"
    }
  }
}

Here, we've added keys that are expected in the JSON file: username and followers. So, files containing other keys than that will fail validation.

This will pass:

{
  "username": "chidiadi",
  "followers": 2200
}

And this will fail:

{
  "username": "chidiadi",
  "name":"Chidiadi Anyanwu",
  "followers": 2200,
}

It will fail because that extra name key in the JSON file wasn't included in the schema. The description 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.

There's also a required keyword that can be used to specify what keys in the JSON file have to be there to be accepted. For example, if we want to reject any JSON file sent without populating the username field, we could make it required.

{ 
  "$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"]
}

The required 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:

{ 
  "$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"]
}

JSON Schema Use Cases

OpenAPI

According to the OpenAPI Initiative,

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

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.

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.

Here's an example in JSON format:

{
  "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"]
      }
    }
  }
}

For 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

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.

The OAD describes an API for a simple counter application with URL, “https://api.example.com/counter”, that accepts two HTTP methods: POST for increasing the counter, and GET for retrieving the current number in the counter.

Azure Resource Manager (ARM) Templates

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.

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.

Here’s an example of an ARM template. This is an example from the documentation:

{
  "$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"
    }
  ]
}

This template creates a storage account of name mystorageaccount, using the location of the resource group as the location for the storage account.

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.

The JSON Schema Project

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.

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.

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:

To learn more about the JSON Schema project, you can visit their website.

Conclusion

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 LinkedIn or X.

Now I find myself designing event schemas for sending messages across a distributed system. It's a very similar problem with similar pain points and solutions. Adhering to data contracts is critical to ensure we don't frustrate event subscribers or bring down systems.

Versioning APIs is translatable to versioning event schemas, but if you can effectively evolve schemas, you don't actually need versioning. Effective evolution of schemas comes down to avoiding breaking changes.

Though I covered that briefly in the article above, here I want to thoroughly address breaking changes and propose more solutions to avoiding them.

What are Breaking Changes?

Essentially, a breaking change to a schema (in an API or event context) is anything that requires a consumer to make an update on their end. It's a change that forces change. Schemas will evolve, but once a schema is in use in production, you have to be very careful not to break the data contract.

Removing an event format or changing an event's basic structure constitutes a breaking change. But the nuts and bolts are at the attribute (the field or property) level.

Structural breaking changes

Here's a list of structural breaking changes for schema attributes:

• Renaming Attributes – Changes to an attribute's name, even if it's just changing the case (for example, from camelCase to TitleCase), is a breaking change.
• Removing Attributes – Taking an attribute out of a schema.
• Data Types Changes – Changing data types, even if the change seems compatible.
• Making Attributes Required – Anytime you mark an attribute (even a new one) as required when it wasn't before, it's a breaking change.

Semantic breaking changes

The other primary category of attribute-level breaking changes has to do with changes in what the data means, or semantic changes. They force consumers to re-interpret the data they're getting.

They are as follows:

• Format Changes – Any change to the format of an attribute.
• Meaning Changes – When the declared or implied meaning of data changes.
• Stricter Constraints – When attribute requirements are added or made more restrictive.

It's important to note that what counts as a "breaking change" might be more nuanced. Changing an amount from dollars to cents still forces a change by event subscribers, in interpreting the meaning of the data being sent. Be careful of those, as they are not always obvious.

What are Non-Breaking Changes?

We can generally describe non-breaking changes as additive or permissive ones. These are changes that don't require change for consumers.

Here is a list of non-breaking attribute changes:

• Adding New Attribute – In all schema contexts, the addition of a new attribute is a non-breaking change, so long as it's not required (for example, for a POST request).
• Making Attribute Not Required – When an attribute was required but newer schema versions do not require it.
• Looser Constraints – Things like more permissive integer ranges (min and max) or allowing for greater decimal precision. Be cautious and communicate with consumers, though, as they may rely on stricter constraints.

Non-breaking changes can often be avoided. But evolving schemas effectively can be challenging and require a lot of thought so as not to break schemas and consumers' trust.

How to Evolve Schemas

Sadly, the list of breaking changes is longer than the non-breaking ones. But there are some strategies for evolving schemas in a non-breaking way.

1. Domain Knowledge – Understanding the domain will help ensure you don't end up with poorly named attributes, attributes on the wrong object, or incorrect data types.
2. Specific Attribute Names – Rather than changing an attribute's name, data type, or format, introduce a new attribute with a more specific name and correct the data type or format.
3. Attribute Names With Intent – Leverage attribute names that reflect their format or intent. For example, consumers might not know whether providerCost would be in dollars or cents, so specify with providerCostInDollars or providerCostInCents. This will also prevent a breaking change if you're having calculation precision issues with dollars and decide to deliver the cost in cents.
4. Drafted Schemas & Attributes – Utilize "draft mode" extensively at the schema level, getting feedback on attributes in simulated environments before they are live in production. For schemas that are in use in production, you could introduce a draftedAttributes object and dump experimental (non-production ready) attributes into it. Communicate with consumers that they attributes are being refined – so they should expect breaking changes – and will be moved to the main schema when ready.
5. Support Existing Attributes – Leave old attributes in the schema. Don't remove old attributes unless you've been able to coordinate a deprecation/sunsetting strategy with consumers.
6. Versioning – If necessary, version your schemas. Although it can become quite difficult to maintain, versioning your schemas is a way to allow for backwards compatibility but move forward with a new schema. You can do high-level versioning (for example, v1 and v2) or more granular semantic versioning (for example, v1.0.1). It's best to version each schema independently, so you don't have to, for example, copy all API v1 endpoints to v2.

Conclusion

Breaking changes are a quick way to break trust for any API consumers or event subscribers. I hope that the guidelines above will provide more insight what constitutes a breaking versus non-breaking change, and how to evolve schemas effectively.

If you can't avoid breaking changes, make sure to coordinate with any and all consumers. You can actually earn more trust with your consumers if you effectively evolve schemas and communicate breaking changes when they are necessary.

There’s an important thing to remember though, especially if your customer is some type of small business which deals with the public (such as a restaurant, a bakery, and so on). That thing to remember is that the customer probably doesn’t care about HTML, CSS, or JavaScript. They care about whether the website performs well in search and whether customers come into their business as a result.

This means that you need to build the website with search engine optimization (SEO) in mind. One of the bigger developments recently in the area of SEO is Google’s increasing use of “structured data” in its analysis of websites. This trend made me decide to write this article on the use of structured data in your various web projects.

I’m going to divide this discussion up into four sections. The areas I’m going to delve into include:

1. What is structured data and why does Google care about it?

2. How to use structured data in a website.

3. How to test your structured data and monitor for errors after the site launches.

4. The need to keep your structured data up to date after the website launches.

This is an important discussion to have. I find that many, many, many, many……(many) people who hold themselves out as web developers don’t actually know much (if anything) about SEO.

I also find that many people who hold themselves out as assisting with SEO don’t actually know anything about web development (and often can barely code at all).

Someone who can actually code, and who understands what the search engines are looking for, can provide a great deal of value to their customers. This value, in turn, helps you to make more money as a developer. In other words, pairing an understanding of SEO with your newly learned web development skills can help you go from looking like this:

To looking like this:

So let’s get to it and discuss why structured data is important to a website’s SEO.

What is structured data and why does Google care about it?

Structured data is form of markup you can apply to your website’s content. This markup allows you to provide information to search engines about your web pages and the information they contain.

This markup is important because search engines, while getting better at understanding natural language, can struggle with understanding the wording or other content contained within a web page.

For example, if someone is searching for “professional to help with investing,” search engines may struggle to distinguish between sites which belong to investment managers and sites which discuss how to pick an investment manager in general (this is a very generalized example).

By using structured data, you can help Google know that your website actually belongs to an investment manager.

Another purpose of structured data is that it helps search engines identify who is who on the web. Suppose, for example, you're doing a website for a political candidate. The candidate, in addition to an official campaign website, has an official Facebook page for the campaign.

For obvious reasons, there may be people who start false Facebook pages about the candidate. By including certain structured data in the website, you can create a relational link between the official Facebook page and the campaign’s website. This helps the search engines to know which Facebook page is legit and which one is bogus.

Google has been working to identify who is who on the web for roughly a decade. This started with their now defunct social network, Google+ (you know…..that social network that you may have tried but none of your friends were on).

Back in the early part of this decade, if a website included a link to a Google+ profile, and the link included the “rel=author” attribute, the link informed Google that the website belonged to the holder of the Google+ profile. This was something Google intended to ratchet up in search, as one of their executives explained in this 2013 video:

Google abandoned this approach, mainly due to the struggles of Google+, in August of 2014. Since that time, Google has been increasing its emphasis on structured data as a way of annotating information in search results and identifying who is who on the web.

So, in short, structured data is something you should be including to add value to any website you build for your clients.

How to use structured data in a website

Structured data can be used in a number of ways. In addition to using it to help identify the individual or entity operating the site, you can use it to help Google better understand a page’s content.

If, for example, you’ve built a website for a bakery, then there are types of markup you can use to highlight the business’ good reviews, to highlight upcoming events, and so on. This markup can lead to highlights in search results which, in turn, will make your customer (the bakery owner) happy.

Let’s look at a few examples of what this looks like in real life, using a real estate agent website which I recently built (I'm including the link in case you want to take a look at the code).

The realtor I built the website for focuses her business on dealing with investors. The website includes structured data which informs Google that the site belongs to an actual real estate agent. When I perform a Google search for “Dayton realtor for investors,” the top three organic results I receive are as shown in this photo:

The first result is the website I built. The latter two are websites which do not belong to actual real estate agents, even though that is what I was clearly looking for with my search term. In fact, only one other realtor website even appears on the first page of the search results. Now, I’m not saying that this is entirely due to the structured data, but it certainly helps.

The markup used for structured data is generated/governed by Schema.org. When you’re marking up a site, an individual page, an event, or a product, it’s important to use as much markup as is reasonably possible in order to provide the search engines with relevant information.

Schema.org's website often provides examples of what your markup should look like. The start of the markup that I used for the realtor site involved informing Google that the site belonged to a real estate agent by placing the following inside of a

:

<itemscope itemtype=http://schema.org/RealEstateAgent>

This tells the search engines that I am relying on schema’s markup to identify and describe the site and that the site belongs to a real estate agent, as defined by schema here.

I was also able to use structured data to tell Google that this realtor has good online reviews and that they work on commission. This, in turn, is now showing up in search results.

For example, the page at the following link is on the first page of search when I look for Dayton apartments for sale. (Again, I'm including this link in case you want to look at the site's source code).

Notice that the search results include the fact that this is a five-star rated realtor and that the professional works on commission? In other words, the use of structured data helps the site to stand out more in the search results. This information was added to the site with the following markup:

<div itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">
Rated <span itemprop="ratingValue">Actual Rating of Realtor</span> out of <span itemprop="bestRating">Highest Possible Rating of Realtor</span> by <span itemprop="ratingCount">Number of Total Reviews</span> clients at <a href="URL of Website Where Reviews Are Located" target="_blank" rel="noopener">Name of Website Where Reviews Are Located</a>
Fee Structure: <span itemprop="priceRange">Commission</span>
</div>

Figuring out what structured data to use in a site, or on a particular page, can be difficult. Fortunately, Google gives a few tools that help with this. Let’s look at those tools in the following section of this article.

Testing your structured data and monitoring it after your site launches

The first step in adding structured data to your content is to figure out the category it falls into. You can do this by researching the Schema.org website, looking at the data from other websites, or a combination of both. Once you find the category you fall into, the rest is pretty easy. Let’s stick with the real estate agent example from above.

The first step is to add the realtor markup, from Schema, the site. Then enter your url into Google’s structured data testing tool. The tool will tell you what structured data has been found on your site, what errors you may have, and what structured data is “suggested” for the category you’ve selected. Once you start using this tool, you’ll find that making sure you have the right information in the website becomes fairly simple and straightforward.

Also, I heavily rely on the examples which Schema provides for various categories and data types. Using Google’s testing tool can help you to make sure that you have the correct data in your site from the get go.

Another important tool, in monitoring for errors, is Google Search Console. This is another developer tool, from Google, that will let you know when structured data errors appear on your website after launch. This is an incredibly useful tool and if you’re supporting your client’s website on an ongoing basis, after launch, then you need to be using it to monitor things.

The need to keep your structured data up to date after a website launches

It is important to understand that you may need to go back and edit a site’s older structured data after a site launches. This is because, like many other things, the standards for structured data change over time. As an example, I build and maintain websites for law firms as part of my primary business. Under the prior structured data standards, these websites were marked up with the following:

In later revisions to the structured data standards, however, the “Attorney” classification was deprecated and changed to “LegalService” – as such, I had to change the markup on each website I manage. I tell you this because it’s important to realize that these standards change somewhat often. It’s important that you keep up with the changes.

Conclusion

Web results are becoming increasingly rich in that they provide more information than just a link to a website. It’s important for your clients that you markup your pages accordingly. Doing so is important to your SEO efforts and to providing value to your customers. This is why it’s important to include structured data in your projects.

About Me

I am a web developer who primarily provides various types of services to law firms. I am also a co-founder of Modern Website Design. I enjoy writing on issues which help freelance developers and small businesses to grow their revenue.