# json-schema-resolver > Resolve all your $refs Latest version **3.0.0** (published 2025-01-18) · MIT license · 0 weekly downloads ## Install ```sh npm install json-schema-resolver pnpm add json-schema-resolver yarn add json-schema-resolver bun add json-schema-resolver ``` ## Health **Score 40/100 (D)** — status: stable. Positive: no vulnerabilities; high maintenance score. Warnings: low downloads; no types; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 3.0.0 | | Published | 2025-01-18 | | First published | 2020-05-16 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=20 | | Dependencies | 3 | | Unpacked size | 13 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 14 | | Author | Manuel Spigolon | | Maintainers | eomm | | Keywords | json, schema, json-schema, ref, $ref | ## Links - npm: https://www.npmjs.com/package/json-schema-resolver - Repository: https://github.com/Eomm/json-schema-resolver - Homepage: https://github.com/Eomm/json-schema-resolver#readme - Issues: https://github.com/Eomm/json-schema-resolver/issues - Funding: https://github.com/Eomm/json-schema-resolver?sponsor=1 - npm.io page: https://npm.io/package/json-schema-resolver ## Dependencies (3) - [rfdc](https://npm.io/package/rfdc.md) ^1.1.4 - [debug](https://npm.io/package/debug.md) ^4.1.1 - [fast-uri](https://npm.io/package/fast-uri.md) ^3.0.5 ## 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 - 3.0.0 (latest) — 2025-01-18 - 1.1.1-0 (beta) — 2020-05-21 - 2.0.0 — 2022-09-10 - 1.3.0 — 2021-08-30 - 1.2.2 — 2020-07-12 - 1.2.1 — 2020-05-31 - 1.2.0 — 2020-05-22 - 1.1.0-0 — 2020-05-18 - 1.0.1-0 — 2020-05-16 - 1.0.0-0 — 2020-05-16 ## README # json-schema-resolver [![CI](https://github.com/Eomm/json-schema-resolver/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Eomm/json-schema-resolver/actions/workflows/ci.yml) [![NPM version](https://img.shields.io/npm/v/json-schema-resolver.svg?style=flat)](https://www.npmjs.com/package/json-schema-resolver) [![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard) Resolve all `$refs` in your [JSON schema](https://json-schema.org/specification.html)! This module will resolve the `$ref` keyword against the `externalSchemas` you will provide. By resolving the `$ref` keyword, means that you get back a single BIG inlined JSON schema that does not rely on any external schema. If a reference is missing, it will not throw any error. ## Install ```sh npm install json-schema-resolver ``` This plugin support Node.js >= 10 ## Usage: resolve one schema against external schemas The `$ref` string is going to be modified to point to a local reference URI: `#/definitions/`. Moreover, the `definitions` keyword will be decorated with the external schemas to get only one JSON schema resolved as output. By default the `` has the `def-${index}` format. You can customize it by passing a `buildLocalReference` function as follows: ```js const RefResolver = require('json-schema-resolver') const ref = RefResolver({ clone: true, // Clone the input schema without changing it. Default: false, buildLocalReference (json, baseUri, fragment, i) { // the `json` that is being resolved // the `baseUri` object of the schema. Its values is the parse result from https://www.npmjs.com/package/fast-uri // the `fragment` is the `$ref` string when the `$ref` is a relative reference // the `i` is a local counter to generate a unique key return `def-${i}` // default value } }) const inputSchema = { $id: 'http://example.com/SimplePerson', type: 'object', properties: { name: { type: 'string' }, address: { $ref: 'relativeAddress#' }, houses: { type: 'array', items: { $ref: 'relativeAddress#' } } } } const addresSchema = { $id: 'relativeAddress', // Note: prefer always absolute URI like: http://mysite.com type: 'object', properties: { zip: { type: 'string' }, city: { type: 'string' } } } const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema] }) // inputSchema is untouched thanks to clone:true ``` `singleSchema` will be like: ```json { "$id": "http://example.com/SimplePerson", "type": "object", "properties": { "name": { "type": "string" }, "address": { "$ref": "#/definitions/def-0" }, "houses": { "type": "array", "items": { "$ref": "#/definitions/def-0" } } }, "definitions": { "def-0": { "$id": "relativeAddress", "type": "object", "properties": { "zip": { "type": "string" }, "city": { "type": "string" } } } } } ``` ## Usage: resolve multiple schemas against external shared schemas When you have multiple schemas to resolve against a collection of shared schema you need to use this module with little changes. This is needed to have all the same definitions path (`#/definitions/`) across all the root schemas ```js const ref = RefResolver({ clone: true, // Clone the input schema without changing it. Default: false applicationUri: 'my-application.org', // You need to provide an unique URI to resolve relative `$id`s externalSchemas: [addresSchema] // The schemas provided at the creation of the resolver, will be used evvery time `.resolve` will be called }) const inputSchema = { $id: 'http://example.com/SimplePerson', type: 'object', properties: { name: { type: 'string' }, address: { $ref: 'relativeAddress#' }, houses: { type: 'array', items: { $ref: 'relativeAddress#' } } } } // the resolved schema DOES NOT have definitions added const singleSchema = ref.resolve(inputSchema) const anotherResolvedSchema = ref.resolve(input_2_Schema) // resolve schemas within the same externalSchemas // to get the definition you need only to call: const sharedDefinitions = ref.definitions() ``` ## Debug To debug this module, simply set: ```bash export DEBUG=json-schema-resolver ``` ## License Licensed under [MIT](./LICENSE). --- _Source: https://npm.io/package/json-schema-resolver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._