{
  "id": 20346219,
  "title": "OpenAPI Components: Reuse vs Duplication",
  "url": "https://urgent.news/2026/11/16/openapi-components-reuse-vs-duplication",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-16T23:26:37.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/jeff_pdc/openapi-components-reuse-vs-duplication-1enp"
  },
  "original_language": "en",
  "account": "Reuse OpenAPI components, like schemas or parameters, via the $ref mechanism when the same structure serves multiple purposes. This consolidates the definition into a single source of truth, preventing the proliferation of duplicate types in generated client code. Conversely, use inline duplication for one-off structures that are expected to vary independently.\n\nThe components object acts as a registry for reusable design elements, including schemas, parameters, request bodies, responses, headers, examples, security schemes, links, and callbacks. These components only become part of an operation when referenced via a JSON reference such as $ref: #/components/schemas/Customer. A reference is a pointer, not a copy, ensuring identical field sets, types, and constraints across all operations that utilize it. This reuse mechanism scales across multiple files in a split project, allowing a relative path to navigate to a component in another document.\n\nDuplicating inline structures across operations leads to drift over time, with each copy evolving separately. Reviewing such documents is challenging, as differences become buried within hundreds of lines of code. Code generation reveals the true cost: a referenced component results in a single model being reused, whereas an inlined component generates four identical types, cluttering SDKs and forcing consumers to manage conversions. Lint rules can detect unused components and structural duplicates but cannot determine if two copies were intended to stay in sync.\n\nIn summary, reuse components for stable, shared concepts that evolve together, while retaining inline structures for one-off variations. Carefully consider the size of shared definitions to avoid creating a \"god component\" that becomes a regression hotspot when modified. Refactoring should be a no-op for consumers, with tools like lint passes and resolved-output comparisons confirming that generated types remain consistent. By applying these principles, shared components become a clarity-enhancing tool rather than a source of coupling within OpenAPI specifications.",
  "summary": "Quick answer: Reuse an OpenAPI component with $ref whenever the same schema, parameter, or response is genuinely one concept used in multiple places; it gives you a single source of truth and keeps generated clients from sprouting duplicate types. Inline duplication is the right call for one-off structures or fields that look alike but are expected to change independently. What components and…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}