Why Are JSON API Structures So Popular?

If you search for "XML vs. JSON" online, you'll find many opinions explaining why JSON has surpassed XML in popularity. While JSON is less verbose, more lightweight, and significantly simpler to use than XML, these aren't the only reasons for its success.

JSON support is built into every modern browser. More importantly, JSON is the native format for data in JavaScript applications—and JavaScript is the most widely used language for building web applications. As JavaScript rose in popularity, JSON rose alongside it.

You could attempt to use XML as the data interchange format for a JavaScript application, but it would require significantly more effort than using JSON. Similarly, most programming languages have data structures that closely resemble JSON's structure, which makes translation straightforward.

JSON Schema Eliminates XML Holdouts

In the early days of JSON, schemas were a key difference that XML proponents pointed to as an advantage. XML Schema is a language that lets you describe the structure of an XML document, enabling structured descriptions of your data models and document validation.

JSON by default does not include a schema in the way that XML does. However, in 2010, the JSON Schema project was born, which allows developers to define the structure of JSON documents.

JSON Schema is a vocabulary and standard for annotating and validating JSON documents. The main goal for JSON Schema is validation—you can use it to validate data from another source and fit that data to your data model.

Early on, some developers worried that JSON Schema would become as complex as XML. But the goal of JSON Schema was always to help developers make sense of JSON data without the schema getting in the way.

Early Use Cases: NoSQL Databases

One of the early use cases for JSON Schema was NoSQL databases that use JSON as data representation. These storage options, like CouchDB and MongoDB, also gained popularity in the early 2010s. While NoSQL databases don't always require schemas, you still likely want one. A schema makes your data predictable and easier to query, especially if the data has a complicated structure and many levels.

More recently, JSON Schema is applied to other data tools, including APIs. In particular, its inclusion within the OpenAPI standard enables teams to create more consistent, predictable APIs.

Five Ways JSON Schema Can Help You Build Better APIs

You can use JSON Schema to improve the design of your APIs along with third-party tools that support it. Many third-party tools have implemented JSON Schema, and you can find a list on the JSON Schema website for tools that support draft-06 or later.

With JSON Schema and third-party tools, you can perform client-side validation, simplify contract testing, create mock servers, create style guides for your structured data, and generate documentation for your API automatically.

Let's examine five ways JSON Schema can improve the design of your API in more detail.

1. Perform Client-Side Validation in API Testing

API validation rules can live in two places: the server and the client. Developers often reproduce server-side validation in the client-side, which is not the best approach. Validation rules should not be stored only inside the backend code.

Instead, you can use JSON Schema to create validation rules that can be seen by API clients. Client-side validation allows applications to notice new validation rules almost immediately and avoid breaking when there are minor validation changes.

2. Simplify Contract Testing

When you talk to developers about "contract testing," they usually think you mean "producer contract testing." You can simplify contract testing by using JSON Schema along with a schema matcher in your integration tests.

The standard process usually starts with the API development team creating a test that records all parts of an interface. Then they run tests on pull requests to the API repository to make sure that there are no accidental changes to the code.

However, if you use JSON Schema models along with OpenAPI, you can take the schemas and assert that the standard response format matches it without having to write things like properties, data formats, and validations.

3. Create Mock Servers

With JSON Schema and an API definition standard like OpenAPI, you can generate a complete mock server. A mock server helps you accelerate the development of an API by allowing you to get feedback on the API design before you spend time on implementation.

You can also ensure that your API fulfills consumer requirements and that any changes you make to your API won't break the applications of your customers. Some mock API servers include dynamic mocking, where you can leverage fake data to respond dynamically to requests, thus simulating real server behavior.

4. Create Style Guides for Your Structured Data

If you want your developers to build consistent APIs, you need an API style guide. It's not a good idea for your developers to make guesses about API design components, like naming conventions and field formats.

With a JSON Linter, you can create a style guide that keeps all your API developers on the same page and your API designs consistent across your organization.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$",
      "description": "User identifier in snake_case"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["user_id", "email"]
}

5. Generate API Documentation Automatically

If you're providing an API for developers to consume, you must also provide well-designed, easily understandable API documentation. It's not enough to design your API well—you need to tell developers how to use it in a clear and concise manner.

You can find many tools that allow you to generate nicely designed, human-readable API documentation from your JSON Schema files. Using JSON Schema, via an OpenAPI document, can also help you ensure that your API documentation is always up to date.

When your schema changes, your documentation updates automatically. This eliminates the problem of outdated documentation that doesn't match the actual API behavior.

JSON Schema Validation Example

Let's look at a practical example of how JSON Schema can be used to validate JSON data:

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120
    }
  }
}

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Getting Started with JSON Schema

If you're working with JSON data in your APIs, implementing JSON Schema is a logical next step. You can create reusable models so the names and data objects remain consistent across your APIs.

Start by defining schemas for your most commonly used data structures. Even if you don't implement full validation immediately, having a schema definition helps document your API's expectations and makes it easier for consumers to understand your data format.

Conclusion

JSON Schema brings the structure and validation capabilities that many developers appreciate about XML, while maintaining JSON's simplicity and flexibility. By implementing JSON Schema in your API design, you can improve validation, simplify testing, create better mock servers, enforce consistency, and generate up-to-date documentation automatically.

The combination of JSON's popularity and JSON Schema's capabilities makes it an ideal data format for most modern APIs. Whether you're building REST APIs, working with NoSQL databases, or designing microservices, JSON Schema can help you create better, more maintain-facing APIs.