Skip to content

feat: resolve external $refs (files and URLs) - #16

Merged
includeamin merged 9 commits into
mainfrom
external-refs
Nov 21, 2026
Merged

includeamin merged 9 commits into
mainfrom
external-refs

Conversation

@includeamin

Copy link
Copy Markdown
Owner

Summary

  • Specs split across files or URLs ($ref: ./schemas/pet.yaml#/Pet, $ref: https://example.com/defs.yaml#/Error) are now bundled per source before merging: each external target is hoisted into that source's own components and the $ref is rewritten to #/components/.... Circular refs work, and the existing merge and rename logic is untouched. Specs without external refs produce identical output.
  • New pure bundle module in openapi-aggregator-core (no I/O, still wasm-compatible): missing_documents finds what a spec needs, bundle / bundle_source bundle it once loaded. Each front end runs its own fetch loop.
  • CLI / library: files and URLs are loaded by a fetch loop in refs.rs. Added aggregate_with_options and AggregateOptions; aggregate and aggregate_with_report keep their signatures and use the sandboxed defaults.
  • Playground: new wasm export pendingRefs and a docs argument on aggregate. The pipeline resolves referenced files from the workspace (and URLs through the existing guarded loader). Missing files get an actionable problem, and all of them are reported at once. Added a "Multi-file spec" example.

Hoisting rules

  • #/components/<type>/<name> keeps its type and name; #/definitions/X and #/$defs/X become schemas.
  • Otherwise the type is inferred from where the $ref sits, and the name is the last pointer segment (the file stem for a whole-file ref).
  • On a name clash the file name is added (pet_Pet) and a warning is emitted. Path-item refs are inlined. example, default, enum and value data is never treated as refs.

Security

  • Sandbox: external file refs may only read inside the config directory and the directory of each file source. Paths are canonicalised, so symlinks and absolute paths pointing elsewhere are rejected. Opt out with --allow-outside-config-dir (CLI) or AggregateOptions::allow_outside_config_dir.
  • A URL source's headers are only sent to its own origin. A document fetched over HTTP can never cause a local file read, and file: URLs are rejected.
  • At most 100 external documents per source.
  • The playground does not fetch remote refs from share links until fetching is allowed.

Test plan

  • cargo test --workspace (location helpers, doc discovery, every bundling rule, bundle_source, 11 new CLI integration tests covering sandbox, symlink escape, absolute paths, sibling sources, header origin rule via mockito, file: from remote, missing file, 100-document cap; wasm tests)
  • cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --check
  • cd web && npm test (69 tests), npm run typecheck, npm run e2e

@includeamin
includeamin merged commit 5a39245 into main Nov 21, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant