Schema-First vs Code-First

Schema-first: the contract file — OpenAPI: Describing the Contract, Not Designing It, protobuf, GraphQL SDL — is written and reviewed before implementation; server stubs, clients and docs are generated from it. The contract is designed as an artifact in its own right, which is precisely the posture this whole domain argues for: the review happens on the contract diff, *before* code exists to defend. The teams it pays for most are the ones with parallelism to unlock — consumer teams build against the agreed spec (with generated mocks) while the provider implements, and cross-team API review boards get a reviewable artifact instead of a walkthrough of handler code.

Code-first: handlers and types are written in the implementation language, and the spec is generated from annotations, decorators or reflection. It keeps one artifact in one language, gets full IDE and refactoring support, and iterates fastest — change the type, and the spec follows. Its gravity is the risk: when the contract is a byproduct of the code, contract *thinking* tends to become a byproduct too. The generated spec faithfully describes whatever the code happens to do — including the leaked ORM field and the accidentally-nullable response — and nobody reviewed those as promises (see Response Contracts Are Not Database Rows).

The dichotomy is softer than the debate: gRPC teams are schema-first by construction (gRPC: Schema, Codegen and Streams has no code-first option worth wanting); a two-person team iterating on an internal API is rationally code-first; and many mature teams land on code-first authoring with schema-first *governance* — the spec is generated, but it is committed, diffed and reviewed as the contract of record, and CI treats an unapproved spec change as a build failure.

Drift is the served API and the described API disagreeing, and each workflow drifts in its own direction. Schema-first drifts at the implementation seam: the spec says one thing, the handler does another — a field the stub scaffolded but the handler never populates, a documented 409 the code never returns, validation looser than the schema claims. Code-first drifts at the design seam: the spec is always accurate but the contract mutates without anyone deciding it should — an internal refactor renames a serialized field, and the generated spec dutifully documents the breaking change nobody chose (see Backward Compatibility: The Real Rules).

Both directions are closed mechanically, never by diligence. Against implementation drift: contract tests that exercise the real server and validate every response against the schema — request and response validation middleware in non-prod catches what the test suite misses (see Testing the Contract, Not Just the Code). Against design drift: the generated spec is committed to the repo, and CI diffs it against the approved version on every build — a changed contract fails the build until a human approves the diff, with a breaking-change classifier (OpenAPI: Describing the Contract, Not Designing It diff tooling) deciding which diffs need which level of sign-off. The committed-and-diffed spec is the single cheapest governance mechanism in this module: it converts every accidental contract change into a visible, reviewable event.

The choice keys on three questions. Who reviews contract changes? If API review crosses team boundaries — platform boards, public-API governance — schema-first gives reviewers a native artifact; if the implementing team self-reviews, code-first with a gated generated spec delivers the same safety with less ceremony. Who builds in parallel? Consumer teams waiting on the provider make schema-first's design-before-build concretely valuable — mocks from the spec unblock them on day one. How fast does the contract churn? Early-stage APIs redesigning weekly suffer under schema-first's double bookkeeping (edit spec, regenerate, reconcile); stable public contracts amortize it trivially.

Wherever you land, two invariants are non-negotiable, and they matter more than the direction. First: one source of truth, declared — a repo where some endpoints are spec-generated and others hand-annotated, with nobody sure which, is worse than either pure workflow. Second: the schema is not the contract — it captures shapes and operations, while idempotency, ordering, consistency and unknown-value rules live in prose the schema cannot express (see OpenAPI: Describing the Contract, Not Designing It and Documentation Is Part of the Contract); whichever artifact comes first, those clauses still have to be written by someone who means them.