Meta-index of the specification languages used to describe APIs, events, schemas, and service interfaces across the modern API landscape. This repo is the META layer above the topical repos that profile each individual specification — it catalogs every major HTTP, event-driven, schema, and service interface specification along with its current version, governing body, license, and tooling ecosystem.
URL: Visit APIs.json
Run: Capabilities Using Naftiko
- API Specifications, Specification Languages, API Design, Contracts, Schemas, Interface Definitions, Standards
- Created: 2026-05-22
- Modified: 2026-05-22
API specifications are not one thing. They fall into a handful of recurring categories, each addressing a different shape of API contract. This index draws the lines between them and points to the topical repo for each.
Languages for describing synchronous request/response APIs over HTTP. OpenAPI 3.0/3.1 is the dominant standard, with RAML persisting in Mulesoft/Anypoint estates and API Blueprint documented here as historical context. Older XML-based interface description still lives in WSDL/SOAP for legacy enterprise and government systems.
Languages for describing message-driven and event-driven APIs across Kafka, AMQP, MQTT, WebSocket, NATS, and SNS/SQS. AsyncAPI 3.0 is the canonical specification, frequently used alongside protocol-native schemas (Avro, Protobuf, JSON Schema) for the message payload itself.
Protocol-agnostic languages that define service contracts and emit clients, servers, and other specs. gRPC/Protobuf is the high-performance binary IDL backbone; GraphQL SDL defines type systems and queryable graphs; Smithy (AWS) and TypeSpec (Microsoft) are higher-level IDLs that compile down to OpenAPI, JSON Schema, and Protobuf; WSDL is the historical baseline.
Languages for describing data shapes independent of transport. JSON Schema (Draft 2020-12) is the embedded schema language inside OpenAPI 3.1, AsyncAPI 3, and most modern API contracts. JSON Structure is an emerging spec that extends JSON Schema's type system for cleaner code generation.
Specifications for remote procedure call protocols. JSON-RPC 2.0 is the lightweight, JSON-encoded RPC powering blockchain APIs (Ethereum, Bitcoin) and IDE language servers (LSP). gRPC is the binary HTTP/2-based RPC framework using Protobuf as its IDL.
Vendor-owned specification formats that govern modern API products. Tinybird's API spec is profiled here as a representative — a higher-level domain model that often emits OpenAPI as a derived artifact.
- OpenAPI 3.1 embeds JSON Schema 2020-12 as its schema dialect; OpenAPI 3.0 uses a closely-related Schema Object.
- AsyncAPI embeds JSON Schema for payloads but routinely points to Avro/Protobuf schemas via
schemaFormat. - Smithy and TypeSpec sit above OpenAPI and Protobuf as authoring sources of truth that emit them.
- gRPC uses Protobuf as its IDL; Protobuf can also be used standalone as a serialization spec.
- RAML and API Blueprint cover the same problem space as OpenAPI but have lost mindshare; their tooling ecosystems are now in maintenance mode.
- WSDL/SOAP describes the same surface as OpenAPI but for XML/SOAP transports; modern migrations replace WSDL with OpenAPI- or gRPC-described services.
The OpenAPI Specification (formerly Swagger) is the dominant industry standard for describing HTTP-based RESTful APIs. Active versions: 3.0.x and 3.1.0 (fully aligned with JSON Schema 2020-12). Governed by the OpenAPI Initiative, a Linux Foundation project, under the Apache 2.0 license.
Human URL: https://www.openapis.org/
Tooling: OpenAPI Tools Directory
- Documentation
- Specification (latest)
- OpenAPI 3.1.0
- OpenAPI 3.0.3
- GitHub Repository
- Specification Record Example
The open standard for describing event-driven and message-driven APIs across Kafka, AMQP, MQTT, WebSocket, NATS, and SNS/SQS. AsyncAPI 3.0 (December 2023) decoupled operations from channels for clearer pub/sub, request/reply, and streaming modelling. Governed by the AsyncAPI Initiative under the Linux Foundation, Apache 2.0 licensed.
Human URL: https://www.asyncapi.com/
Tooling: AsyncAPI Tools
- Documentation
- Specification (latest)
- AsyncAPI 3.0.0
- GitHub Organization
- Specification Record Example
A declarative language for annotating and validating JSON documents — the foundational schema language embedded in OpenAPI 3.1, AsyncAPI 3, and most modern API specifications. Current dialect: Draft 2020-12. Reference tooling is BSD-3-Clause / MIT.
Human URL: https://json-schema.org/
Tooling: JSON Schema Tooling Ecosystem
- Documentation
- Draft 2020-12 Release Notes
- JSON Schema Core (2020-12)
- GitHub Organization
- Specification Record Example
An emerging open specification that extends and complements JSON Schema with a clearer, code-generation-friendly type system designed for data contracts and cross-language model generation. Apache 2.0 licensed.
Human URL: https://json-structure.org/
A query language and runtime for APIs, defined by the GraphQL Specification. The Schema Definition Language (SDL) is the declarative format for types, queries, mutations, and subscriptions. Governed by the GraphQL Foundation, a Linux Foundation project, under OWFa 1.0. Current edition: October 2021 with continued Working Drafts.
Human URL: https://graphql.org/
- Documentation
- Specification (October 2021)
- Working Draft
- GitHub Repository
- Specification Record Example
High-performance RPC framework using HTTP/2 and Protocol Buffers as its IDL and wire format. gRPC is a CNCF graduated project; Protocol Buffers (proto3) is maintained by Google. Apache 2.0 / BSD-3-Clause licensed.
Human URL: https://grpc.io/ — https://protobuf.dev/
- gRPC Documentation
- Protobuf Language Guide (proto3)
- proto3 Specification
- gRPC GitHub Organization
- Protocol Buffers GitHub Organization
- Specification Record Example
An open-source IDL and code-generation framework created and maintained by AWS. Protocol-agnostic (HTTP REST, AWS JSON, MQTT, RPC), traits-based modelling. Used to generate AWS service SDKs, OpenAPI, and JSON Schema. Apache 2.0 licensed.
Human URL: https://smithy.io/
A language for describing API shapes developed by Microsoft (formerly Cadl). TypeSpec definitions emit OpenAPI 3.x, JSON Schema, Protobuf, and other artifacts, and serve as the upstream source for Azure SDK generation. MIT licensed.
Human URL: https://typespec.io/
A YAML-based modelling language for RESTful APIs, originally created by Mulesoft. RAML 1.0 (2016) is the current spec. Steward: Mulesoft/Salesforce. Industry mindshare has shifted to OpenAPI; RAML remains in Anypoint estates. Apache 2.0.
Human URL: https://raml.org/
A Markdown-based specification language for web APIs, originally created by Apiary (acquired by Oracle). The spec is MIT licensed but development effectively stalled after acquisition. Documented here as historical context for the API specification landscape.
Human URL: https://apiblueprint.org/
The historical XML-based interface definition for SOAP web services. WSDL 1.1 (2001) is the most widely deployed; WSDL 2.0 is a W3C Recommendation (2007). Governed by the W3C, remains critical in legacy enterprise and government integrations.
Human URL: https://www.w3.org/TR/wsdl/
- Documentation (WSDL 2.0 Primer)
- WSDL 1.1 Note
- WSDL 2.0 Recommendation
- SOAP 1.2 Recommendation
- Specification Record Example
A stateless, light-weight remote procedure call protocol encoded in JSON. Widely used in blockchain/Web3 APIs (Ethereum, Bitcoin), IDE language servers (LSP), and developer tooling. 2.0 (2010) is the stable revision. Released into the public domain.
Human URL: https://www.jsonrpc.org/
The Tinybird API specification is a vendor-defined, declarative format for describing analytics endpoints (pipes), data sources, and parameters backed by ClickHouse. Documented here as a representative example of vendor-specific specification formats that govern modern data API products outside of the OpenAPI/AsyncAPI mainline. MIT licensed (SDKs/CLI).
Human URL: https://www.tinybird.co/docs
- Repository
- Specification Record JSON Schema
- Specification Record JSON Structure
- API Specifications JSON-LD Context
- API Specifications Vocabulary
| Name | Description |
|---|---|
| HTTP Request/Response Specifications | OpenAPI, RAML, API Blueprint, and historically WSDL — describing synchronous HTTP APIs. |
| Event-Driven Specifications | AsyncAPI for channels, operations, and messages across brokers; combined with Avro/Protobuf for payloads. |
| Service Interface Definition Languages (IDLs) | gRPC/Protobuf, Smithy, TypeSpec, GraphQL SDL, and WSDL — protocol-agnostic service contracts that emit clients and other specs. |
| Schema Languages | JSON Schema (de facto, embedded in OpenAPI/AsyncAPI) and JSON Structure (emerging) — describing data shapes. |
| RPC Protocol Specifications | JSON-RPC 2.0 and gRPC — describing RPC method calls and their payloads. |
| Vendor-Defined Specifications | Vendor-specific formats (e.g. Tinybird) that govern modern API products, often emitting OpenAPI as a derived artifact. |
| Name | Description |
|---|---|
| Specification Discovery and Cataloging | Maintain an enterprise inventory of specifications used across internal and partner APIs, mapped to governing bodies and tooling. |
| Multi-Format Code Generation | Author in TypeSpec or Smithy and emit OpenAPI, JSON Schema, and Protobuf to generate SDKs across protocols. |
| Event-Driven Architecture Contracts | Use AsyncAPI alongside Avro/Protobuf to define event schemas, channels, and operations for streaming systems. |
| Governance and Linting Across Specs | Apply Spectral or similar linters against OpenAPI, AsyncAPI, and JSON Schema artifacts as part of an API governance program. |
| Legacy SOAP/WSDL Modernization | Migrate legacy WSDL/SOAP interfaces to OpenAPI-described REST or gRPC services as part of modernization initiatives. |
| Name | Description |
|---|---|
| Spectral | Open-source linting engine (Stoplight) for OpenAPI, AsyncAPI, and JSON Schema — the de facto governance engine. |
| Redocly CLI | CLI for linting, bundling, and rendering OpenAPI specs; enforces style guides and integrates with CI. |
| AsyncAPI Generator | Template-driven code and documentation generator for AsyncAPI specs across languages and brokers. |
| Protoc / Buf | The canonical Protobuf compiler and Buf's modern toolchain for linting, breaking-change detection, and codegen. |
| Smithy CLI | AWS-maintained CLI for compiling Smithy models and generating OpenAPI, JSON Schema, and SDK artifacts. |
| TypeSpec Compiler | Microsoft-maintained compiler that emits OpenAPI 3, JSON Schema, Protobuf, and other artifacts from TypeSpec sources. |
Machine-readable artifacts organized by format.
- Specification Record Schema — Normalized schema for describing any API specification language (name, version, governing body, license, format, tooling).
- Specification Record Structure — JSON Structure counterpart aligned with the v0 core meta-schema.
- API Specifications Context — Maps the specification record terms to schema.org
SoftwareSourceCode,Organization, andCreativeWorkplus the localspec:namespace.
- OpenAPI
- AsyncAPI
- JSON Schema
- JSON Structure
- GraphQL SDL
- gRPC / Protobuf
- Smithy
- TypeSpec
- RAML
- API Blueprint
- WSDL / SOAP
- JSON-RPC 2.0
- Tinybird
- API Specifications Vocabulary — Unified taxonomy mapping 13 specifications, 9 resources, 7 actions, 6 workflows, and 5 personas across the API specification landscape.
FN: Kin Lane
Email: kin@apievangelist.com