Compendium

HTTP / API / Schema Description Languages Family Index

8 min read

HTTP / API / Schema Description Languages Family Index

type: language-family-index family: api-description languages_catalogued: 28 tags: [language-reference, family-index, api, idl, schema, openapi, graphql, grpc, contract-first]

HTTP / API / Schema Description Languages — Family Index

  • Type: Tier 3 family index
  • Family: HTTP / API / Schema Description
  • Languages catalogued: 28
  • Last updated: 2026-05-09

Family overview

API description languages exist because two services that have never met still need to agree on the exact shape of the bytes they exchange. The space splits along two axes: contract-first vs code-first (do humans write the schema and generate the code, or do they write the code and generate the schema?), and protocol (REST → OpenAPI / RAML / API Blueprint, gRPC → Protobuf, GraphQL → SDL, async/event-driven → AsyncAPI, RPC-style binary → Thrift / Cap’n Proto / FlatBuffers / Avro, SOAP → WSDL, linked data → JSON-LD). The 2010s were a contract-first vs code-first holy war; the 2020s are a quiet reconciliation. TypeSpec (Microsoft, formerly Cadl) and Smithy (AWS) both pitch the same idea: write one source-of-truth model and emit OpenAPI, JSON Schema, Protobuf, GraphQL, client SDKs, and server stubs from it. Microsoft uses TypeSpec internally for Azure SDKs; AWS uses Smithy for the entire AWS SDK family. This is the dominant trajectory.

The other big 2020s story is the JSON Schema explosion. JSON Schema started as a validation vocabulary, then OpenAPI 3.1 finally aligned its body schema to JSON Schema 2020-12 (a long-running mismatch that plagued tooling), so the same schema document now validates request bodies, generates types, drives contract tests (Pact), and decorates linked data (JSON-LD). Draft 2020-12 is still the latest stable as of May 2026; a “next” draft is in active editing in the IETF JSON Schema WG but has not stabilized. AsyncAPI 3.0 (released late 2023) embraced this fully — its message payloads are JSON Schema by default — and has become the de facto description format for Kafka / NATS / MQTT / WebSocket APIs.

The protocol fan-out is real but shrinking at the edges. gRPC + Protobuf 3 quietly became ubiquitous inside microservice meshes; Connect-RPC (from Buf) and gRPC-Web solved the “how do I call gRPC from a browser” problem two different ways. Meanwhile RAML and API Blueprint are effectively dead — RAML’s last spec is from 2017 and Mulesoft (now Salesforce) has shifted focus, while API Blueprint’s reference parser was last seriously updated years ago. WSDL and WADL survive only inside enterprises that still ship SOAP. The Cap’n Proto / FlatBuffers / Avro tier has settled into specific niches (low-latency RPC, mobile/games, big-data pipelines respectively) and isn’t really competing with Protobuf for general microservice traffic.

In our deep library

None catalogued in the deep library — these are IDLs and schema languages, not general-purpose programming languages. Cross-reference config-and-dsl (where adjacent schema-shaped DSLs like Cue/KCL sit and partly overlap with API contract validation), query (GraphQL’s query side lives there; the SDL side is here), build-devops (some gateway DSLs sit there), and notation-spec for Mermaid’s broader role.

Tier 3 family table

LanguageFirst appearedOwner / originProtocolStatus (2026)URL
OpenAPI 3.12021OpenAPI Initiative (Linux Foundation)REST / HTTPDominant; latest stable; uses JSON Schema 2020-12https://spec.openapis.org/oas/v3.1.0
OpenAPI 3.02017OpenAPI InitiativeREST / HTTPLegacy but very widely deployed; many tools still 3.0-onlyhttps://spec.openapis.org/oas/v3.0.3
Swagger 2.02014SmartBear (donated to OAI)REST / HTTPLegacy predecessor; surprisingly persistent in older enterprise stackshttps://swagger.io/specification/v2/
AsyncAPI 3.02023AsyncAPI Initiative (Linux Foundation)Kafka, MQTT, AMQP, NATS, WebSocket, SSEActive, dominant for event-driven APIshttps://www.asyncapi.com/docs/reference/specification/v3.0.0
GraphQL SDL2015 (public) / 2018 (foundation)GraphQL Foundation (Linux Foundation)GraphQL over HTTP/WSStable, widely used; October 2021 spec edition is currenthttps://spec.graphql.org/
Protobuf 3 (gRPC IDL)2016 (proto3)GooglegRPC, generic binary RPCDominant inside microservice meshes; proto3 + Editionshttps://protobuf.dev/programming-guides/proto3/
Apache Thrift IDL2007 (Apache) / 2007 (open-sourced from Facebook)Apache (originally Facebook)Thrift RPC, binaryMature, declining; still used at Meta, Evernote, some Hadoop-era stackshttps://thrift.apache.org/docs/idl
Apache Avro IDL2009Apache (originated at Hadoop)Kafka payloads, Hadoop, big-dataActive in data engineering (Confluent Schema Registry default)https://avro.apache.org/docs/current/idl-language/
Smithy2020 (open-sourced from AWS)AWSProtocol-agnostic; emits OpenAPI, JSON Schema, moreActive, growing; backbone of AWS SDK generationhttps://smithy.io/2.0/
TypeSpec2022 (renamed from Cadl)MicrosoftProtocol-agnostic; emits OpenAPI, JSON Schema, ProtobufActive, fastest-growing; backbone of Azure SDK generationhttps://typespec.io/
JSON Schema (Draft 2020-12)2020IETF JSON Schema WGJSON validation, embedded in OpenAPI/AsyncAPILatest stable; “next” draft in progress in 2026https://json-schema.org/specification
JSON-LD 1.12020W3CLinked data over JSONStable; used in schema.org, ActivityPub, Solid, verifiable credentialshttps://www.w3.org/TR/json-ld11/
RAML 1.02016 (1.0) / 2014 (0.8)RAML Workgroup (Mulesoft / Salesforce)REST / HTTPEffectively dormant; last major spec 2016https://raml.org/
API Blueprint2013Apiary (acquired by Oracle)REST / HTTPEffectively dormant; reference parser stagnanthttps://apiblueprint.org/
WSDL 2.02007W3CSOAP, occasionally RESTLegacy; survives in enterprise SOAP stackshttps://www.w3.org/TR/wsdl20/
WADL2009W3C member submissionREST / HTTPEffectively dead; never gained tractionhttps://www.w3.org/Submission/wadl/
HAR (HTTP Archive)2012W3C Web Performance WGHTTP traffic capture formatUniversal browser/devtools format; not a description language but adjacenthttps://w3c.github.io/web-performance/specs/HAR/Overview.html
Cap’n Proto schema2013Sandstorm.io / Kenton Varda (ex-Google)Cap’n Proto RPC, zero-copy serializationActive niche; used in Cloudflare Workers internalshttps://capnproto.org/language.html
FlatBuffers schema2014GoogleZero-copy binary; games, mobileActive in games, mobile, ML model formatshttps://flatbuffers.dev/
MessagePack2008Sadayuki FuruhashiBinary JSON drop-in; schema is optional/MsgPack-IDLActive; widely embedded; not strictly a description languagehttps://msgpack.org/
Pact2013DiUS / Pact FoundationConsumer-driven contract testingActive, dominant in contract-test spacehttps://docs.pact.io/
HTTP Message Signatures (RFC 9421)2024IETFHTTP request/response signingActive; replaces draft-cavage-http-signatureshttps://www.rfc-editor.org/rfc/rfc9421.html
Mermaid (sequence/API subset)2014Mermaid project (Knut Sveidqvist)API-flow diagramsActive, ubiquitous in markdown ecosystemshttps://mermaid.js.org/syntax/sequenceDiagram.html
Gateway DSLs (Kong, KrakenD, Tyk, AWS API Gateway, Apigee)various 2014–2018variousAPI gateway configActive sub-cluster; usually YAML/JSON over a vendor schemahttps://docs.konghq.com/
gRPC-Web2018Google / gRPC teamBrowser-callable gRPC over HTTP/1.1Active; reuses Protobuf schemashttps://github.com/grpc/grpc-web
Buf (Protobuf governance)2020Buf TechnologiesProtobuf linting, breaking-change detection, registryActive; ecosystem tooling, not a new languagehttps://buf.build/docs
Connect-RPC schema2022Buf TechnologiesBrowser/server RPC over HTTP/1.1, /2, gRPC-compatibleActive, growing; Protobuf-basedhttps://connectrpc.com/docs/
OpenRPC2019OpenRPC project (ConsenSys-incubated)JSON-RPC 2.0 descriptionNiche but stable; standard for Ethereum JSON-RPC and similarhttps://open-rpc.org/

Notable threads

  • OpenAPI 3.1 + JSON Schema 2020-12 unification (finally). From OpenAPI’s birth through 3.0, the body-schema dialect was almost JSON Schema but with subtle, painful divergences (nullable, example vs examples, missing keywords). 3.1 (2021) finally adopted JSON Schema 2020-12 as a strict superset, ending years of duplicated tooling. As of 2026, ecosystem migration is mostly complete but a long tail of 3.0-only generators remains.
  • TypeSpec and Smithy as the modern “design-once, generate everything” play. Both Microsoft (TypeSpec) and AWS (Smithy) bet that the right answer is neither contract-first nor code-first but a third artifact — a typed model that emits OpenAPI, JSON Schema, Protobuf, GraphQL, and SDKs in N languages. TypeSpec is now the source of truth for new Azure SDKs; Smithy is the source for AWS SDKs. If a third major cloud adopts one, the war is essentially over.
  • gRPC’s quiet ubiquity. gRPC + Protobuf 3 became the default for service-to-service traffic inside microservice meshes (Linkerd, Istio, Consul, Cilium) without ever winning a public spec war. Buf’s tooling (lint, breaking-change detection, BSR registry) plus Connect-RPC (a gRPC-compatible protocol that works in browsers without a proxy) cleaned up the two historical pain points: governance and browser-reachability.
  • AsyncAPI catching up to REST/gRPC. AsyncAPI 3.0 (late 2023) finally untangled the bidirectional message confusion of 2.x and embraced JSON Schema natively. It’s now the credible default for describing Kafka, NATS, MQTT, and WebSocket APIs — the event-driven equivalent of OpenAPI.
  • The death of RAML and API Blueprint. Both were better-designed than Swagger 2.0 in many ways, but neither had a single deep-pocketed steward willing to fund tooling year over year. Mulesoft (RAML) was acquired by Salesforce and shifted focus; Apiary (API Blueprint) was acquired by Oracle and quietly de-prioritized. OpenAPI won by being the survivor with the largest tooling ecosystem, not by being the best designed.
  • JSON Schema’s tooling gap. Validation libraries exist in every language, often multiple per language, and are excellent. Codegen from JSON Schema is patchy: the schema is too permissive (anyOf/oneOf/allOf, conditional subschemas, tuple-with-rest arrays) for clean type emission. This is partly why OpenAPI/Smithy/TypeSpec layer on top of JSON Schema rather than expecting people to use it bare.
  • Connect-RPC vs gRPC-Web for browser-callable RPC. gRPC-Web requires a proxy (Envoy or similar) to translate HTTP/2 framing. Connect-RPC was designed from the start to speak plain HTTP/1.1 and HTTP/2 without a proxy, while remaining wire-compatible with gRPC servers. Both reuse Protobuf schemas. Connect is gaining ground, especially among teams that want zero-proxy browser RPC.

Citations

Graph View