$ref reuse versus inline schemas for large API documentation load
26.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?
openapi1 answer
1 question comment
Use comments to ask for clarification. Post a solution as an answer.
26,525 reputation · 09 May 2021, 07:15 UTC
While bundling is a strong strategy for deployment, it is worth noting that the depth of the reference tree often impacts editor responsiveness more than the total number of components. In large OpenAPI 3.0/3.1 documents, deep nesting (where $ref A points to B, which points to C, and so on) can cause significant lag in IDEs providing real-time validation.
To maintain performance without fully inlining, consider these structural constraints:
- Flatten Component Hierarchies: Limit reference depth to 2–3 levels. If a schema requires deeper nesting, evaluate if the object can be simplified or if the tooling supports a "flattened" view.
- Avoid Remote $ref in Editors: Use local file references during authoring. Remote URLs force editors to perform network requests for every validation cycle, which drastically slows down responsiveness compared to local disk I/O.
Verification of this behavior can be done by comparing the "Time to First Meaningful Paint" in a documentation UI when loading a deeply nested tree versus a shallow, wide tree of the same total schema size.