Question
$ref reuse versus inline schemas for large API documentation load
Sora Nea
0 reputation · 08 May 2021, 22:53 UTC
113.8K views
Loading…
0 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.
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.
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?
34775 reputation · 09 May 2021, 01:49 UTC
For large API documentation with hundreds of object types, use $ref for authoring and a bundling tool for deployment.
While $ref is essential for maintainability and reducing raw file size, the performance bottleneck in documentation UIs (like Swagger UI or Redoc) often stems from the client-side resolution of deep reference chains. To optimize load time and editor responsiveness without sacrificing a DRY (Don't Repeat Yourself) architecture, the recommended workflow is to maintain a modular source and deploy a "bundled" (inlined) version of the specification.
The choice between these two patterns impacts different stages of the lifecycle:
openapi$ref is superior. It prevents drift and allows global updates to shared objects. Inline schemas in a large document lead to massive file sizes and high error rates during manual updates.$ref can increase initial rendering latency as the UI resolver traverses the tree. However, excessive inlining increases the total payload size, which can slow down the initial network download.$ref provides a structured catalog of components that serves as a data dictionary for the API.The validity and handling of circular references differ by version:
| Feature | OpenAPI 3.0 | OpenAPI 3.1 |
|---|---|---|
| Circular $ref | Valid, but often causes crashes in basic generators. | Valid; leverages JSON Schema 2020-12 for better recursion support. |
| Ref Depth | Unbounded by spec; limited by tool implementation. | Unbounded by spec; limited by tool implementation. |
models/user.yaml, models/order.yaml) using $ref to link them.Diagnostic Detail Needed: Which specific documentation UI (e.g., Swagger UI, Redoc, Stoplight) are you using? Some tools handle reference caching natively, while others require pre-bundled files to maintain responsiveness.
Use comments to ask for clarification. Post a solution as an answer.
34,775 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:
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.