# @hey-api/json-schema-ref-parser > Parse, Resolve, and Dereference JSON Schema $ref pointers Latest version **1.4.4** (published 2026-06-22) · MIT license · 0 weekly downloads ## Install ```sh npm install @hey-api/json-schema-ref-parser pnpm add @hey-api/json-schema-ref-parser yarn add @hey-api/json-schema-ref-parser bun add @hey-api/json-schema-ref-parser ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.4.4 | | Published | 2026-06-22 | | First published | 2024-12-25 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=22.18.0 | | Dependencies | 3 | | Unpacked size | 376.8 KB | | Known vulnerabilities | 0 (+3 in 1 direct dependencies) | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 5438 | | Author | Hey API | | Maintainers | mrlubos | | Keywords | $ref, dereference, json, json-pointer, json-schema, jsonschema, resolve, schema | ## Links - npm: https://www.npmjs.com/package/@hey-api/json-schema-ref-parser - Repository: https://github.com/hey-api/hey-api - Homepage: https://heyapi.dev/ - Issues: https://github.com/hey-api/hey-api/issues - Funding: https://github.com/sponsors/hey-api - npm.io page: https://npm.io/package/@hey-api/json-schema-ref-parser ## Dependencies (3) - [js-yaml](https://npm.io/package/js-yaml.md) 4.2.0 - [@jsdevtools/ono](https://npm.io/package/@jsdevtools/ono.md) 7.1.3 - [@types/json-schema](https://npm.io/package/@types/json-schema.md) 7.0.15 ## Alternatives - [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads - [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads - [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads - [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads - [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads ## Recent versions - 1.4.4 (latest) — 2026-06-22 - 0.0.0-next-20260824173136 (next) — 2026-08-24 - 0.0.0-next-20260819153534 — 2026-08-19 - 0.0.0-next-20260813201118 — 2026-08-13 - 0.0.0-next-20260811214609 — 2026-08-11 - 0.0.0-next-20260804175203 — 2026-08-04 - 0.0.0-next-20260803133142 — 2026-08-03 - 0.0.0-next-20260803131638 — 2026-08-03 - 0.0.0-next-20260803105733 — 2026-08-03 - 0.0.0-next-20260803085119 — 2026-08-03 - 0.0.0-next-20260729142554 — 2026-07-29 - 0.0.0-next-20260728215008 — 2026-07-28 - 0.0.0-next-20260724070045 — 2026-07-24 - 0.0.0-next-20260723124023 — 2026-07-23 - 0.0.0-next-20260722143429 — 2026-07-22 - … 222 more at https://npm.io/package/@hey-api/json-schema-ref-parser/versions ## README # JSON Schema $Ref Parser #### Parse, Resolve, and Dereference JSON Schema $ref pointers ## Installation Install using [npm](https://docs.npmjs.com/about-npm/): ```bash npm install @hey-api/json-schema-ref-parser pnpm add @hey-api/json-schema-ref-parser yarn add @hey-api/json-schema-ref-parser bun add @hey-api/json-schema-ref-parser ``` ## The Problem: You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML format. Maybe some of the files contain cross-references to each other. ```json { "definitions": { "person": { // references an external file "$ref": "schemas/people/Bruce-Wayne.json" }, "place": { // references a sub-schema in an external file "$ref": "schemas/places.yaml#/definitions/Gotham-City" }, "thing": { // references a URL "$ref": "http://wayne-enterprises.com/things/batmobile" }, "color": { // references a value in an external file via an internal reference "$ref": "#/definitions/thing/properties/colors/black-as-the-night" } } } ``` ## The Solution: JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward JavaScript objects. - Use **JSON** or **YAML** schemas — or even a mix of both! - Supports `$ref` pointers to external files and URLs, as well as custom sources such as databases - Can bundle multiple files into a single schema that only has _internal_ `$ref` pointers - Can dereference your schema, producing a plain-old JavaScript object that's easy to work with - Supports circular references, nested references, back-references, and cross-references between files - Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object instance - Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux ### New in this fork (@hey-api) - **Multiple inputs with `bundleMany`**: Merge and bundle several OpenAPI/JSON Schema inputs (files, URLs, or raw objects) into a single schema. Components are prefixed to avoid name collisions, paths are namespaced on conflict, and `$ref`s are rewritten accordingly. ```javascript import { $RefParser } from '@hey-api/json-schema-ref-parser'; const parser = new $RefParser(); const merged = await parser.bundleMany({ pathOrUrlOrSchemas: [ './specs/a.yaml', 'https://example.com/b.yaml', { openapi: '3.1.0', info: { title: 'Inline' }, paths: {} }, ], }); // merged.components.* will contain prefixed names like a_, b_, etc. ``` - **Dereference hooks**: Fine-tune dereferencing with `excludedPathMatcher(path) => boolean` to skip subpaths and `onDereference(path, value, parent, parentPropName)` to observe replacements. ```javascript const parser = new $RefParser(); parser.options.dereference.excludedPathMatcher = (p) => p.includes('/example/'); parser.options.dereference.onDereference = (p, v) => { // inspect p / v as needed }; await parser.dereference({ pathOrUrlOrSchema: './openapi.yaml' }); ``` - **Smart input resolution**: You can pass a file path, URL, or raw schema object. If a raw schema includes `$id`, it is used as the base URL for resolving relative `$ref`s. ```javascript await new $RefParser().bundle({ pathOrUrlOrSchema: { $id: 'https://api.example.com/openapi.json', openapi: '3.1.0', paths: { '/ping': { get: { responses: { 200: { description: 'ok' } } } }, }, }, }); ``` ## Contributing Want to see your code in products used by millions? Start with our [Contributing](https://heyapi.dev/docs/openapi/typescript/community/contributing) guide and release your first feature. ## Sponsors Partners behind the future of API tooling. [Become a sponsor](https://github.com/sponsors/hey-api).

Gold

Stainless logo
Best-in-class developer interfaces for your API.
stainless.com

Opencode logo
The open source coding agent.
opencode.ai

Silver

Scalar logo
scalar.com 		FastAPI logo
fastapi.tiangolo.com 		Unblocked logo
getunblocked.com

Bronze

Kinde logo Cella logo Photon logo
## License Released under the [MIT License](https://github.com/hey-api/hey-api/blob/main/LICENSE.md). --- _Source: https://npm.io/package/@hey-api/json-schema-ref-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._