$ref reuse versus inline schemas for large API documentation load
18.5K reputation · 08 May 2021, 22:53 UTC
Designing schema composition for an OpenAPI document with hundreds of object types under a concrete constraint of documentation load time and editor responsiveness.
Trade-off
Components/schemas with $ref centralizes definitions, reduces duplication and supports maintainability. Tooling can cache and reuse parsed schemas, which benefits large APIs and keeps the document DRY.
Inline schema definitions avoid $ref resolution indirection and simplify copy-paste examples for readers, but duplicate structure, increase document size and raise drift risk when the same shape evolves in multiple places.
Version and interpretation uncertainty
The discussion assumes OpenAPI 3.0 and 3.1. OpenAPI 3.1 uses JSON Schema 2020-12 dialect, which changes nullability and composition semantics versus 3.0.
The specification does not mandate how tools should handle circular $ref chains or maximum ref depth, leading to divergent behavior between validators, generators and documentation UIs when schemas reference each other.
Is a circular $ref chain considered valid composition in OpenAPI 3.0 versus 3.1? What interpretation should be applied for unbounded ref depth to achieve consistent tooling behavior?
openapi