OpenAPI and JSON Schema are powerful and complementary tools for creating APIs. 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.
This article looks at how OpenAPI supports JSON Schema and uses it throughout the specification. It also offers 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 humans alike can read OAS documents, making it easy for 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.
JSON support 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’ that supports content negotiation, which means you can define different schemas and examples for various media types. It allows web services to accept and return data in different formats, including JSON.
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.
JSON Schema use cases
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.
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.
