Using JSON Schema with OpenAPI

Everything you need to know about OpenAPI JSON Schema. Simplify API development and improve data integrity.

If you want to create standardized, consistent APIs, OpenAPI and JSON Schema are powerful and complementary tools to help you do so. 

• OpenAPI provides a standardized framework for describing an entire API, from paths and operations to components and security schemes. 
• JSON Schema is a tool for validating and documenting JSON data structures, ensuring an API’s data conformity.

In this article, we show you how OpenAPI supports JSON Schema and uses it throughout the specification. We’ve also provided handy tips on working with both tools.

What is JSON Schema?

JavaScript Object Notation, or JSON, is a simple text-based data format for representing and exchanging semi-structured data. JSON Schema is a language derived from JSON that lets you describe and validate JSON data in a standardized way.

You can specify various aspects of JSON documents, including data types, formatting, and constraints, to ensure that data structures remain consistent across an API.

What is OpenAPI?

The OpenAPI Specification (OAS) is an open standard for defining and structuring REST APIs. Machines and developers alike can read OAS documents, making it easy for human and agentic AI consumers to understand an API’s purpose and functionality. Developers who use OpenAPI can take advantage of its many benefits, like automated processes and improved collaboration, not to mention better API documentation. API designers who use it in combination with JSON Schema can benefit extensively when it comes to schema modeling. 

What JSON Schema does in OpenAPI

OpenAPI supports JSON Schema. However, the level of support depends on whether you’re using version 3.0 or 3.1. Let’s take a look.

OpenAPI version 3.0

Version 3.0 supports many JSON Schema elements, including the ‘oneOf’ or ‘anyOf’ keywords. You can use these keywords to describe an API request or response with OpenAPI alternative schemas (based on polymorphism).

This version introduced a ‘requestBody’ feature that supports content negotiation. This is where OpenAPI, with its use of JSON Schema, comes in. You can define different schemas and examples for various media types using JSON Schema throughout your OpenAPI specification. This allows web services to accept and return data in different formats, including JSON, and provides greater flexibility.

OpenAPI 3.0 also updated ‘examples’, allowing you to use a JSON string to describe multiple examples of any format. In earlier OpenAPI versions, you had to use a JSON or YAML object to describe examples.

OpenAPI version 3.1

Version 3.1 is fully compatible with the most recent drafts of JSON Schema (2019-09 and 2020-12) and supports all JSON Schema keywords. With OpenAPI v3.1, you can use any keyword in the JSON Schema vocabulary.

Using JSON Schema for validation in OpenAPI

In an OpenAPI specification, JSON Schema defines the structure of data that your API accepts and returns. It describe things like:

• The data type of each field (string, number, boolean, object, array)
• Whether fields are required
• Value constraints (min/max length, numeric ranges)
• Formats (email, date-time, URI)
• Nested structures and arrays
• Alternative schemas (polymorphism)

When an API receives a request or produces a response, the data can be validated against the schema to ensure it follows the expected format. This helps with data integrity, early error detection, consistent API contracts, and automatic documentation generation.

Differences between JSON Schema and OpenAPI schema objects

JSON Schema is the general validation language for JSON data, while OpenAPI schema objects are the API-focused implementation of those schemas within an OpenAPI specification. 

JSON Schema use cases in APIs

Most use cases for JSON Schema in OpenAPI involve API data models:

• Defining bodies and payloads: JSON Schema is typically used to define the structure of API request bodies and response payloads. These definitions help consumers understand what an API’s requests and responses should include and help improve interoperability between API clients and servers.
• Validating parameters: JSON Schema lets you validate various parameters of an API, such as header parameters, path parameters, and query string parameters. Validating parameters helps you catch errors early in the design process and ensures consistency across the API. You can also use the full range of JSON Schema keywords (OpenAPI v3.1) to validate API structures more precisely.
• Creating reusable components: An API can have many endpoints with components that follow the same structure. JSON Schema allows you to create reusable components for various elements, including response payloads, parameters, request bodies, and examples. You can reference these reusable components throughout the API, reducing redundancy and simplifying maintenance.
• Accommodating different needs: Incorporating JSON Schema into OpenAPI allows the specification to accommodate different needs. For example, developers may want to use OpenAPI to define nested structures or arrays, add validation rules, or employ polymorphism. JSON Schemas allow OpenAPI to handle a wide range of API project requirements.

Working with JSON Schema and OpenAPI

OpenAPI and JSON Schema complement each other and can help you design and build consistent, high-quality APIs. Here are a few tips when working with both:

• Use OpenAPI v3.1: Version 3.1 is fully compatible with JSON Schema, which means you can leverage the full range of the latter’s keywords and use its syntax. You get the highest level of JSON compatibility with this version of OpenAPI. However, keep in mind that JSON compatibility may change again in the next version, Moonwalk.
• Reference external JSON schemas: With OpenAPI v3.1, you can directly reference any external JSON Schema files to promote reusability and modularity. To do this, use the ‘$ref’ keyword. Note ‘imports’ may replace $ref in the Moonwalk version.
• Leverage automated validation tools: Use automated tools to validate OAS documents against JSON Schema, ensuring that API definitions meet the specified standards. Tools like Tyk OAS + Tyk Middleware and Hyperjump – JSON Schema (NodeJS) allow you to automate validation.
• Leverage automated conversion tools: Use automated tools to convert JSON Schema to OpenAPI Schema Objects. Automatically converting schemas helps prevent manual conversion errors and maintains compatibility. JSON Schema to OpenAPI Schema (NodeJS) is a tool that converts JSON Schema (Draft 04) to OpenAPI (v3.0) Schema Objects.
• Utilize ‘oneOf’, ‘anyOf’, or ‘allOf’ to combine schemas: OpenAPI 3.0+ lets you use JSON Schema keywords ‘oneOf’, ‘anyOf’, or ‘allOf’ to combine multiple schemas. You can also use these keywords to validate a value against various criteria.

Tools for JSON Schema validation

There are numerous tools that help ensure JSON data conforms to a defined schema, including automated validation tools to boost DevOps and platform team efficiency. JSON Schema validation tools can validate request and response payloads, catch errors early, and enforce consistent data structures, making them invaluable for backend developers too.

Examples of popular tools for JSON Schema validation include:

• AJV: A fast JavaScript validator widely used in Node.js applications and API framework
• jsonschema: A popular Python library for validating JSON documents against JSON Schema
• Everit JSON Schema: A robust Java-based validator supporting modern JSON Schema drafts
• Newtonsoft.Json Schema: A .NET library for defining and validating JSON schemas
• Spectral: A flexible linter that can validate OpenAPI and JSON Schema rules
• Stoplight Studio: A visual API design tool with built-in OpenAPI and JSON Schema validation

OpenAPI + JSON Schema = consistent APIs

OpenAPI and JSON Schema work well together. OpenAPI defines the entire API, and JSON Schema describes the data structure within that API. OpenAPI v3.1 is fully compatible with JSON Schema, making it easier for you to create consistent, high-quality APIs.

Keep up with the latest developments at JSON-Schema.org and The OpenAPI Initiative for changes that could impact your API projects. Also, check out Tyk 5.3, which introduces native support for the OpenAPI Specification.