OpenAPI, AsyncAPI, JSON Schema, Arazzo, Overlays, APIs.json — the machine-readable artifacts that make an API knowable.
Make the contract executable in your pipeline. Lint the definition on every change, run contract tests against the live API, and fail the build when the two disagree. Drift is a process problem, not a discipline problem.
Applying targeted modifications to an OpenAPI document without altering the source — adding examples, translating descriptions, injecting governance metadata, or specializing for one audience. Keep the base pristine a...
A machine-readable index a provider publishes on their own domain, describing their APIs and everything around them — docs, OpenAPI, terms, pricing, support. A sitemap for APIs, and decentralized discovery by design.
Arazzo is the OpenAPI Initiative specification for describing multi-step API workflows. You need it when the outcome your consumers want takes more than one call — which is nearly always.
AsyncAPI is the machine-readable contract for event-driven and message-driven APIs — the OpenAPI of the asynchronous world. You need it the moment you have a Kafka topic, a queue, or a webhook that consumers depend on.
JSON Schema describes and validates the structure of your data. It matters because it is what OpenAPI is built out of, and because schema drift is the most expensive and most preventable form of API decay.
JSON-LD adds shared meaning to JSON by linking fields to common vocabularies. Adoption has been frustratingly thin — but machine consumers that must interpret data without a human in the loop are the case it was built...
OpenAPI is the static source of truth describing what the API can do. A collection is an executable derivative describing how it is actually used, for a specific outcome. You want both.
At minimum an OpenAPI document, the JSON Schema behind it, and interactive documentation generated from both. After that, a collection, an APIs.json index, and — when you have workflows — Arazzo.
