JSON Schema $ref Resolver

Paste a JSON Schema or OpenAPI document with pointers and get back a fully dereferenced version — every reference inlined, no keys remaining. Useful for generators and validators that don't follow refs, for diffing two schemas at the data level, and for getting a single-file artifact you can publish without worrying about broken external pointers.

How to use the JSON Schema $ref Resolver

Paste a schema with pointers like #/definitions/Address or #/components/schemas/User. Each pointer is resolved to its target and replaced inline. If a schema references itself (or refers in a loop), pick whether to error out or trim the cycle by replacing the deeper occurrence with an empty schema. The strip toggle removes the now-unused definitions block so the output is fully self-contained.

This tool only resolves internal references (within the same document). External references (./other.json#/Foo, http://...) are left untouched — fetching those requires network access, which a browser tool can't do safely for arbitrary URLs.

About JSON Schema $ref Resolver

JSON Schema's keyword lets you reuse type definitions: declare Address once under definitions and reference it from any property with { "$ref": "#/definitions/Address" }. This keeps schemas DRY but creates problems for downstream tooling. Some validators don't follow refs. Some code generators choke on circular references. Some documentation pipelines need a fully-resolved schema to render type tables. Diffing two schemas with refs scattered through them surfaces irrelevant structural differences instead of the actual data shape change.

Dereferencing — inlining every ref into the place where it's used — solves all of these. The output is verbose but unambiguous: every property's full type is visible at the point of use. The same idea applies to OpenAPI 3 specs where #/components/schemas/X is the convention; both are pure JSON-Pointer references and the resolver handles both shapes.

Common use cases

  • Feeding an old validator that predates ref support (some embedded / mobile JSON-Schema libraries still don't dereference).
  • Schema diffing — dereference both versions, diff the result, see the actual data-shape changes rather than ref-graph noise.
  • Producing single-file API docs — many doc generators are simpler if the schema is self-contained.
  • Code-gen sanity check — confirm that every ref in your schema actually resolves before running the generator.

Frequently asked questions

Does it follow external references?
No — only same-document refs (#/...). External refs need network fetches, which raise CORS and security concerns for a browser tool. Pre-bundle externals with a CLI like swagger-cli bundle first.

What happens with circular references?
Pick the cycle handling option. Trim replaces the recursive occurrence with an empty schema ({}); Error halts and reports the cycle path. Trim is the right default for most use cases — it produces a finite output that's still meaningful for the non-recursive parts.

Will this work for OpenAPI 3.1?
Yes. OpenAPI 3.1 uses standard JSON Schema 2020-12, including $ref and JSON Pointer fragments. The resolver doesn't care about the surrounding OpenAPI structure — it walks the entire tree.

Does it deduplicate inlined definitions?
No — each ref is inlined fresh. If the same definition is referenced 10 times, it appears 10 times in the output. That's correct (each occurrence is independent in the dereferenced form) but it does make the file larger.