Skip to content

PATTERN Cited by 1 source

Schema-driven interface generation

Generate every interface surface a product exposes — CLI, SDK, IaC provider, MCP server, Workers bindings, configuration file schema, documentation, OpenAPI spec — from one schema, not one-per-surface (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare).

Problem

Cloud platforms expose the same resources through many interface surfaces — REST API, SDKs in N languages, CLI, Terraform provider, MCP server for agents, Workers bindings, configuration files. The classic trap is to maintain each surface separately or to generate some from one schema and hand-maintain the rest:

  • CLI drifts from SDK (different verbs, different flags).
  • Terraform provider lags product launches.
  • MCP server includes some tools but not others.
  • Configuration schema is out of date.
  • Documentation contradicts the API response shapes.

At Cloudflare's scale — ~100 products, ~3,000 HTTP API operations — manual maintenance breaks. The original OpenAPI-centered pipeline generated SDKs, Terraform, and MCP but "updating our CLI, Workers Bindings, wrangler.jsonc configuration, Agent Skills, dashboard and docs is still a manual process. This was already error-prone, required too much back and forth, and wouldn't scale to support the whole Cloudflare API in the next version of our CLI."

Pattern

One schema → many generators → many interfaces. The schema describes every concept any interface might need: resource CRUD, CLI command definitions, configuration fields, agent skill metadata, documentation prose, Workers RPC bindings. Generators are independent programs, each responsible for producing one interface surface.

Key properties:

  1. Single source of truth. When a product adds a new resource, one schema entry gets written and every interface updates automatically on the next build.
  2. Convention enforcement at the schema layer. Rules like "every resource has get not info" are asserted once and propagate. See concepts/cli-convention-enforcement.
  3. Pluggable generators. Adding a new interface (say, a Pulumi provider) is a matter of writing a new generator; no schema change needed.
  4. Output conformance. External-facing specs (OpenAPI, JSON Schema) become outputs of the pipeline for backward-compatibility, not inputs.
  5. Cross-surface consistency for agents. The same resource appears with the same nouns / verbs / fields in CLI, SDK, MCP, Workers bindings — an agent that learns one surface can navigate another without confusion.

Cloudflare's concrete pipeline

Schema format: a set of TypeScript types with conventions, linting, and guardrails (see patterns/typescript-as-codegen-source).

From this one TypeScript schema, Cloudflare generates:

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

Why this is hard

  • Schema language must be rich enough for every surface's needs. OpenAPI could not do this, which is why Cloudflare rolled a TypeScript-based schema.
  • Generator quality matters a lot. A bad CLI generator produces an unusable CLI even with a perfect schema.
  • Convention churn is expensive. Changing "always get" once all surfaces are shipped requires a coordinated migration.
  • Product teams must work through the schema. If a team can't express what they need in the schema, they won't participate; the schema must be extensible on product-team timelines.

Scope — where this pattern is most valuable

Best fit:

  • Large platforms with many products needing many interfaces.
  • Orgs where agents are a first-class consumer and consistency across interfaces is critical.
  • Teams willing to invest in schema + generator tooling upfront.

Poor fit:

  • Small orgs with one interface (REST-only startup).
  • Teams without code-gen infrastructure discipline.

Seen in

Last updated · 200 distilled / 1,178 read