Reusable components versus inline schemas for multi-team API governance

Answer to the Core Question

For a shared domain model owned by multiple teams, centralising the schemas in components.schemas generally offers a better balance between spec maintainability, CI validation latency, and cross‑language generator fidelity. The main trade‑off is the need for a shared ownership process: if teams cannot agree on a single source of truth, inline schemas become a pragmatic escape hatch that can undermine governance.

Why Centralisation Usually Wins

• Consistency – A single definition per concept prevents semantic drift across endpoints, making it easier to spot breaking changes and to enforce contract tests.
• Generator fidelity – Most OpenAPI generators (OpenAPI Generator, swagger‑codegen, oapi‑codegen) emit one class per referenced schema. Inline definitions are processed per‑operation, so identical bodies can lead to duplicate DTOs or even silent renaming.
• CI validation speed – Validation tools cache resolved references. A 5 k‑line spec that pulls in 50 shared schemas is usually faster to lint than a 15 k‑line spec where those schemas are duplicated inline, because the validator has to lint the same shape many times.

When the Model Evolves Frequently

Frequent changes amplify the benefits of centralisation: a single diff per change is easier to review, and automated breaking‑change detection (e.g., oasdiff, Spectral rulesets) can be applied once to the shared component set. If the teams cannot keep the shared component repository in sync, inline schemas will still be used, but the risk of divergent representations grows.

When the Model Is Stable for Months

In a stable domain the one‑time cost of extracting shared schemas pays off: the generated SDKs become cleaner, and future PRs touch only the $ref line, not a large block of duplicated JSON. The maintenance overhead is minimal because the component definitions rarely change.

Potential Caveats

• Centralised components require a clear ownership model (e.g., CODEOWNERS, dedicated review queue). Without it, teams may revert to inline definitions, negating the consistency gains.
• Some older CI setups (e.g., legacy swagger‑codegen validate) do not cache references, so the performance advantage can be less pronounced.
• Generators that do not honour nullable or discriminator mappings consistently may still produce subtle differences even with components.

Diagnostic Detail Needed to Fine‑Tune the Recommendation

If you can share the current line count of the OpenAPI document or the exact validator and its version used in your CI pipeline, we can estimate the impact of reference resolution on lint time more precisely. This information may shift the recommendation if, for example, the CI uses a validator that does not cache references.