How the Specifications Relate

OpenAPI, AsyncAPI, JSON Schema, Arazzo, Overlay, Spectral, APIs.json, MCP and A2A — read from their published schemas, mapped by what each one points at, which property does which job, and how much vocabulary they share.

Each of these specifications solves one piece of the problem, and each one leans on the others to do it. The picture below comes from reading their published schemas side by side: which spec points at which, which property does the same job under a different name, and where the same name means something different.

What points at what

An arrow reads from the spec that holds the pointer to the spec it points at. Select a specification to trace its connections and see its root properties. Hover over an arrow to see the property it goes through.

Same job, different words

Fourteen jobs that most of these specs have to do, and the property each one uses to do it. An empty cell means that spec's schema has no property for the job, either because the job is out of scope or because it is handled somewhere other than the schema. Select a column heading to highlight that spec on the map.

How much vocabulary they share

Every property name each schema declares, anywhere in its object tree, compared pair by pair. Each cell shows how many names the two specs share; its shade is that count as a share of all the names the two use between them (Jaccard). The diagonal shows each spec's own vocabulary size. A shared name is a lead, not proof of a shared meaning; the next section shows why.

What the strongest pairs share

Same word, different meaning

Matching specs by property name goes wrong fast. These names appear in more than one schema, and in most of these cases they do different jobs. action is the exception worth noticing: Arazzo borrowed it from AsyncAPI on purpose, meaning included.

Sources and method