Skip to content

CONCEPT Cited by 1 source

Unified interface schema

A unified interface schema is a single machine-readable description of a product's APIs, commands, configuration, and RPC surfaces that is rich enough to serve as the source of truth for generating every interface the product exposes: REST API clients, CLI commands, infrastructure-as-code providers (Terraform, Pulumi, Crossplane), MCP servers, Workers bindings / RPC APIs, Agent Skills, configuration schemas, and documentation (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare).

Why it exists

Most orgs start with one schema for one interface (most often OpenAPI for REST APIs) and then fan out: SDKs are generated from OpenAPI, Terraform is generated from OpenAPI, MCP servers are generated from OpenAPI. Cloudflare has been doing all of the above. The problem is that OpenAPI describes REST APIs only. It cannot describe:

  • Interactive CLI commands that combine multiple API calls with local-dev steps.
  • Workers bindings, which are RPC APIs rather than HTTP APIs.
  • Agent Skills, which are task-level primitives not endpoints.
  • Configuration (Cloudflare's wrangler.jsonc), which links bindings, environment, and product surfaces together.
  • Cross-interface documentation (the same product appearing in CLI, SDK, bindings, and config docs coherently).

So any interface OpenAPI cannot describe has been generated manually or with ad-hoc tooling, which is error-prone and cannot keep pace with product development at Cloudflare's scale. At ~100 products and ~3,000 API operations, manual maintenance has broken.

Cloudflare's answer: TypeScript-as-schema

Cloudflare's new internal schema format is "just" a set of TypeScript types with in-house conventions, linting, and guardrails. The author explicitly calls out:

"It's the lingua franca of software engineering. And we keep finding that it just works better to express APIs in TypeScript."

The move is the same one Cloudflare made for Cap'n Web (TypeScript-native RPC) and Code Mode: prefer TypeScript's native type system over separate schema DSLs. OpenAPI is now an output of this schema (for REST-compatibility use cases), not an input.

What it generates

From the one TypeScript schema:

  • cf CLI commands and their arguments.
  • Workers bindings RPC APIs.
  • wrangler.jsonc configuration schema.
  • Cloudflare SDKs across multiple languages.
  • Terraform provider.
  • MCP Code Mode server (<1,000 tokens for ~3,000 operations).
  • Agent Skills.
  • Dashboard UI scaffolding.
  • Developer documentation.
  • OpenAPI schemas (as a generated artifact).

Properties

  • Owned in-house, so it can be extended to whatever interface Cloudflare needs next without waiting for a standards committee.
  • Lintable / enforceable — convention rules like "always get, never info" can be asserted at schema compile time. See concepts/cli-convention-enforcement.
  • Consistent across surfaces — the same resource appears as the same nouns / verbs / fields in every generated interface, reducing agent confusion.
  • A superset of OpenAPI capability-wise: expresses RPC, config, CLI, skills; OpenAPI is one of many targets.

Pattern shape

See patterns/typescript-as-codegen-source for the TypeScript-as-source-of-truth choice, and patterns/schema-driven-interface-generation for the 1-schema → N-interfaces pipeline structure.

Seen in

Last updated · 200 distilled / 1,178 read