🚀 JSON Server

· engineering · 4 min read

By Ankit Jain

JSON Schema - The Common Language Across OpenAPI, AsyncAPI

JSON Schema underpins OpenAPI 3.1, AsyncAPI, Arazzo, Spectral, APIs.json, MCP, and A2A. This post explains how each spec uses JSON Schema for structure, validation, and tooling.

JSON Schema has quietly become the shared foundation for all the modern API specifications. Be it OpenAPI 3.1, AsyncAPI, Arazzo, Overlays, Spectral rules, APIs.json, MCP, and A2A all rely on it to define data structures, validation rules, and contracts.

This convergence is not accidental. As APIs expand beyond HTTP into events, workflows, and agent-to-agent communication, a single, precise schema language reduces ambiguity, improves tooling interoperability, and enables automated validation at scale. Understanding how JSON Schema sits underneath these specs is key to understanding where API design and governance are heading next.

  • When you write OpenAPI 3.1, every request body, response payload, parameter schema, and header schema is pure JSON Schema. There is no separate “OpenAPI-style schema” anymore. If you understand JSON Schema, you already understand how OpenAPI 3.1 models data.

  • The same applies to AsyncAPI. Message payloads, headers, and channel bindings all use JSON Schema to define what goes on the wire. Whether the transport is Kafka, MQTT, WebSockets, or HTTP, the structure of the message is still described using JSON Schema keywords.

  • Arazzo, Overlays, and Spectral rules build on top of existing API descriptions. They do not need to invent a new data modeling system. Instead, the authors reference, extend, or validate schemas that are already written in JSON Schema. Spectral rules, for example, often validate schema correctness itself. Things like required fields, formats, or structural consistency all depend on JSON Schema semantics.

  • APIs.json uses JSON Schema to describe metadata about APIs, collections, and relationships. While its focus is discovery and cataloging, the schema layer is still JSON Schema, ensuring consistency and machine-readability.

  • Newer initiatives like MCP and A2A follow the same pattern. They describe contracts, messages, and capabilities using JSON-based structures, and JSON Schema is the mechanism that defines what those structures look like and how they are validated.

Keep It Simple & Stupid

So the mental model to keep is simple:

If a spec needs to describe data, validate input, define message shapes, or enforce structure, it uses JSON Schema.

Once you are comfortable with JSON Schema concepts like type, properties, required, oneOf, anyOf, allOf, format, and $ref, you are not learning each of these specifications from scratch. You are mostly learning how they apply JSON Schema in slightly different contexts.

OpenAPI 3.1 (OpenAPI-Specification GitHub)

JSON Schema is first-class in OpenAPI 3.1: the specification explicitly defines that the Schema Object is a superset of JSON Schema, aligned with Draft 2020-12. This alignment allows you to use JSON Schema keywords directly in OpenAPI documents.

  • The official OpenAPI GitHub hosts the 3.1 spec where all schema-related constructs reference JSON Schema semantics.
  • The spec also has a published JSON Schema representation (with $id and $schema references) that describes the shape of a valid OpenAPI document.
  • Version 3.1.0 and newer fully support the latest JSON Schema features, enabling validation, tooling, and IDE support based on standard JSON Schema vocabularies.

AsyncAPI (asyncapi/spec-json-schemas on GitHub)

The AsyncAPI spec provides complete JSON Schema files for versions 2.x and later in its spec-json-schemas repository. These schemas are used for validating AsyncAPI documents.

  • The repo includes two sets of schema artifacts: one with $id and one without $id to support differences in tooling implementations around $ref and $id.
  • AsyncAPI’s JSON Schema artifacts are generated bundles from individual definition files that together validate the structure of AsyncAPI documents.
  • The repository notes that JSON Schema alone does not cover all AsyncAPI rules, so parsers add additional custom validation logic beyond what JSON Schema describes.

Arazzo (spec.openapis.org + GitHub gist snapshot)

Arazzo workflows and document structure itself are defined via JSON Schema Draft 2020-12 with $schema and $id declarations.

The core Arazzo JSON Schema defines workflow objects, steps, inputs, outputs, and other typed constructs as JSON Schema objects with typed properties.

The Arazzo schema includes explicit $defs sections to modularize schema pieces such as info, workflow, and step objects.

Spectral (stoplightio/spectral GitHub)

Spectral is an open-source JSON/YAML linter that supports rule sets for multiple specifications including OpenAPI (v2 & v3.1), Arazzo v1.0, and AsyncAPI.

  • It’s capable of validating content against JSON Schema as part of custom rulesets and can use JSON Schema validation in custom lint rules.
  • Official Spectral repositories include rule schema definitions that themselves use JSON Schema to define the shape and configuration of rules.

That is why investing time in JSON Schema pays off across the entire API tooling ecosystem. One schema language, many specs, same foundation.

MCP, A2A

MCP (Model Control Protocol) and A2A (API-to-API) specs are being published with JSON Schema definitions in their GitHub repos (e.g., see the json/a2a.json path in the A2A GitHub project).

One standard. Shared understanding. Consistent validation across the API ecosystem.

Share:
Back to Blog