Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Design-first Workflows

Splitting and Bundling Large OpenAPI Specs

Organize a large OpenAPI description into many files with external $ref, then bundle it for tools; includes folder layouts, circular references, and a runnable bundler stand-in.

A real API description can grow to thousands of lines. A single openapi.yaml of that size is hard to review, causes merge conflicts and makes it unclear who owns what. OpenAPI lets you spread the document over many files using $ref pointers to other files. Before you hand the result to a tool that does not follow external references, you bundle it back into one file.

The redocly commands below are real but need Node, so they are read-only here. A small bundler written in Python will let you watch references being resolved.

References to other files

A $ref can point inside the same document (#/components/schemas/Book) or to another file, optionally with a JSON Pointer to a part of it:

YAML
# openapi.yaml (the root document)
openapi: 3.1.0
info: {title: Bookstore API, version: 1.0.0}
paths:
  /books:
    $ref: "./paths/books.yaml"
  /books/{bookId}:
    $ref: "./paths/book-by-id.yaml"
components:
  schemas:
    Book:
      $ref: "./schemas/Book.yaml"
YAML
# paths/books.yaml
get:
  operationId: listBooks
  summary: List books
  responses:
    "200":
      description: A page of books.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "../schemas/Book.yaml"

Relative paths are resolved from the file that contains the $ref, which is why paths/books.yaml goes up one level with ../schemas/.

A layout that scales

TEXT
api/
  openapi.yaml            # root: info, servers, tags, paths -> $ref
  paths/
    books.yaml
    book-by-id.yaml
    orders.yaml
  schemas/
    Book.yaml
    Order.yaml
    Problem.yaml
  parameters/
    limit.yaml
    cursor.yaml
  responses/
    NotFound.yaml
  examples/
    book-available.yaml

Benefits: pull requests touch small files, CODEOWNERS can assign folders to teams, and shared pieces (Problem.yaml, pagination parameters) live once.

Bundling

Many tools (some SDK generators, linters, validators and viewers) expect a single file. Use a bundler:

Terminal
# Redocly CLI: resolve external refs into one document
npx @redocly/cli bundle api/openapi.yaml --output dist/openapi.yaml

# also dereference fully (inline every $ref) when a tool cannot handle refs at all
npx @redocly/cli bundle api/openapi.yaml --dereferenced --output dist/openapi.full.yaml

# the reverse: split a large single file into a folder structure
npx @redocly/cli split openapi.yaml --outDir api/

Bundle keeps references but moves everything into the one file's components section (so a schema used in ten places is still defined once). Dereference inlines every reference and can make the file enormous; circular references (a Category that contains Category children) cannot be fully dereferenced at all.

Do not publish files with relative external references to a docs site or registry and assume consumers can resolve them. Publish the bundled file, and generate SDKs from it.

A bundler in miniature

The stand-in holds several "files" in a Python dictionary, follows $ref strings that point into other files, moves the referenced schemas into components/schemas and rewrites each pointer to a local one. It also stops cycles by tracking what it has already seen.

Python Stand-in: resolve external $ref into one document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The cycle Book -> Author -> Book stays a pointer, which is exactly how a real bundle represents it.

Working habits

  • Keep one root document and treat everything else as parts.
  • Name files after what they define (Book.yaml defines Book), and keep one schema per file.
  • Lint the bundled output in CI so rule messages refer to the document consumers see (see Linting with Spectral).
  • Run the breaking-change diff on bundled files too.
  • Use components for anything reused three times or more; inline the rest.
  • Avoid very deep chains of references; humans have to navigate them.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How are relative file references in $ref resolved?

    That is why a file in paths/ uses ../schemas/ to reach a sibling folder.
  2. 2. What is the difference between bundling and dereferencing?

    A bundle keeps components reusable. Full dereferencing copies content and cannot handle circular references.
  3. 3. Which file should you publish to consumers and SDK generators?

    Consumers may not be able to resolve your relative file paths, so give them the bundle.

Summary

  • Split large descriptions into files with $ref; relative paths resolve from the referencing file.
  • Use a clear folder layout and one schema per file.
  • Bundle for publishing and tools; dereference only when you must, and never with circular references.
  • Lint and diff the bundled result in CI.
  • The Python bundler is a stand-in for redocly bundle.

Next: Project: a bookstore contract