{"id":14969163,"url":"https://github.com/fastify/json-schema-ref-resolver","last_synced_at":"2025-04-06T02:08:38.800Z","repository":{"id":202650093,"uuid":"704652730","full_name":"fastify/json-schema-ref-resolver","owner":"fastify","description":"JSON schema reference resolver","archived":false,"fork":false,"pushed_at":"2025-03-08T16:34:36.000Z","size":97,"stargazers_count":19,"open_issues_count":2,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T01:09:01.276Z","etag":null,"topics":["fastify-library","json-schema","openapi","reference","swagger"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/json-schema-ref-resolver","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2023-10-13T18:29:43.000Z","updated_at":"2025-03-13T15:27:01.000Z","dependencies_parsed_at":"2024-01-23T20:11:15.463Z","dependency_job_id":"62138daa-298c-4a35-b136-a80b3e929371","html_url":"https://github.com/fastify/json-schema-ref-resolver","commit_stats":{"total_commits":18,"total_committers":7,"mean_commits":"2.5714285714285716","dds":"0.33333333333333337","last_synced_commit":"ab2116f3acbab7e984806119d25825aa8457c78a"},"previous_names":["fastify/json-schema-ref-resolver"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fjson-schema-ref-resolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fjson-schema-ref-resolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fjson-schema-ref-resolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fjson-schema-ref-resolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/json-schema-ref-resolver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423514,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastify-library","json-schema","openapi","reference","swagger"],"created_at":"2024-09-24T13:41:15.453Z","updated_at":"2025-04-06T02:08:38.783Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# json-schema-ref-resolver\n\n[![CI](https://github.com/fastify/json-schema-ref-resolver/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/json-schema-ref-resolver/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/json-schema-ref-resolver)](https://www.npmjs.com/package/json-schema-ref-resolver)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\n__json-schema-ref-resolver__ is a javascript library that resolves references in [JSON schemas](https://json-schema.org/draft/2020-12/json-schema-core#name-introduction).\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [API](#api)\n  - [RefResolver([options])](#refresolveroptions)\n  - [addSchema(schema, [schemaId])](#addschemaschema-schemaid)\n  - [getSchema(schemaId, [jsonPointer])](#getschemaschemaid-jsonpointer)\n  - [getSchemaRefs(schemaId)](#getschemarefsschemaid)\n  - [getSchemaDependencies(schemaId)](#getschemadependenciesschemaid)\n  - [derefSchema(schemaId)](#derefschemaschemaid)\n  - [getDerefSchema(schemaId, [jsonPointer])](#getderefschemaschemaid-jsonpointer)\n- [Caveats](#caveats)\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\n\n## Installation\n\n```bash\nnpm install json-schema-ref-resolver\n```\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n## Usage\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      $ref: 'targetSchema#/definitions/bar'\n    }\n  }\n}\n\nconst targetSchema = {\n  $id: 'targetSchema',\n  definitions: {\n    bar: {\n      type: 'string'\n    }\n  }\n}\n\nconst refResolver = new RefResolver()\n\nrefResolver.addSchema(sourceSchema)\nrefResolver.addSchema(targetSchema)\n\nconst derefSourceSchema = refResolver.getDerefSchema('sourceSchema')\nassert.deepStrictEqual(derefSourceSchema, {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      type: 'string'\n    }\n  }\n})\n```\n\n\u003ca name=\"api\"\u003e\u003c/a\u003e\n\n## API\n\n\u003ca name=\"constructor\"\u003e\u003c/a\u003e\n\n#### RefResolver([options])\n\n- __allowEqualDuplicates__ - if set to `false`, an error will be thrown if a schema with the same `$id` is added to the resolver. If set to `true`, the error will be thrown only if the schemas are not equal. Default: `true`.\n\n- __insertRefSymbol__ - if set to `true` resolver inserts a `Symbol.for('json-schema-ref')` instead of the `$ref` property when dereferencing a schema. Default `false`.\n\n- __cloneSchemaWithoutRefs__ - if set to `false` resolver would not clone a schema if it does not have references. That allows to significantly improve performance when dereferencing a schema. If you want to modify a schema after dereferencing, set this option to `true`. Default: `false`.\n\n\u003ca name=\"add-schema\"\u003e\u003c/a\u003e\n\n#### addSchema(schema, [schemaId])\n\nAdds a json schema to the resolver. If the schema has an `$id` property, it will be used as the schema id. Otherwise, the `schemaId` argument will be used as the schema id. During the addition of the schema, ref resolver will find and add all nested schemas and references.\n\n- `schema` __\\\u003cobject\\\u003e__ - json schema to add to the resolver.\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id to use. Will be used only if the schema does not have an `$id` property.\n\n\u003ca name=\"get-schema\"\u003e\u003c/a\u003e\n\n#### getSchema(schemaId, [jsonPointer])\n\nReturns a json schema by its id. If the `jsonPointer` argument is provided, ref resolver will return the schema at the specified json pointer location.\n\nIf shema with the specified id is not found, an error will be thrown. If the `jsonPointer` argument is provided and the schema at the specified location is not found, getSchema will return `null`.\n\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id of the schema to return.\n- `jsonPointer` __\\\u003cstring\\\u003e__ - json pointer to the schema location.\n- __Returns__ - json schema or `null` if the schema at the specified location is not found.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst schema = {\n  $id: 'schema',\n  type: 'object',\n  properties: {\n    foo: { type: 'string' }\n  }\n}\n\nconst refResolver = new RefResolver()\nrefResolver.addSchema(schema)\n\nconst rootSchema = refResolver.getSchema(schema.$id)\nassert.deepStrictEqual(rootSchema, schema)\n\nconst subSchema = refResolver.getSchema(schema.$id, '#/properties/foo')\nassert.deepStrictEqual(subSchema, { type: 'string' })\n```\n\n`getSchema` can also be used to get a schema by its [json schema anchor](https://json-schema.org/draft/2020-12/json-schema-core#section-8.2.2). To get schema by schema anchor, the `schemaId` argument must be set to the `$id` of the schema that contains the anchor, and the `jsonPointer` argument must be set to the anchor.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst schema = {\n  $id: 'schema',\n  definitions: {\n    bar: {\n      $id: '#bar',\n      type: 'string'\n    }\n  }\n}\n\nconst refResolver = new RefResolver()\nrefResolver.addSchema(schema)\n\nconst anchorSchema = refResolver.getSchema(schema.$id, '#bar')\nassert.deepStrictEqual(subSchema, {\n  $id: '#bar',\n  type: 'string'\n})\n```\n\n\u003ca name=\"get-schema-refs\"\u003e\u003c/a\u003e\n\n#### getSchemaRefs(schemaId)\n\nReturns all references found in the schema during the addition of the schema to the resolver. If schema with the specified id is not found, an error will be thrown.\n\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id of the schema to return references for.\n- __Returns__ - array of objects with the following properties:\n  - `schemaId` __\\\u003cstring\\\u003e__ - schema id of the reference.\n  - `jsonPointer` __\\\u003cstring\\\u003e__ - json pointer of the reference.\n\nIf a reference does not have a schema id part, the schema id of the schema that contains the reference is used as the schema id of the reference.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\n\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      $ref: 'targetSchema#/definitions/bar'\n    },\n    baz: {\n      $ref: 'targetSchema#/definitions/qux'\n    }\n  }\n}\n\nconst refResolver = new RefResolver()\nrefResolver.addSchema(sourceSchema)\n\nconst refs = refResolver.getSchemaRefs('sourceSchema')\nassert.deepStrictEqual(refs, [\n  {\n    schemaId: 'targetSchema',\n    jsonPointer: '#/definitions/bar'\n  },\n  {\n    schemaId: 'targetSchema',\n    jsonPointer: '#/definitions/qux'\n  }\n])\n```\n\n\u003ca name=\"get-schema-dependencies\"\u003e\u003c/a\u003e\n\n#### getSchemaDependencies(schemaId)\n\nReturns all dependencies including nested dependencies found in the schema during the addition of the schema to the resolver. If schema with the specified id is not found, an error will be thrown.\n\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id of the schema to return dependencies for.\n- __Returns__ - an object with all found dependencies. The object keys are schema ids and the values are schema dependencies.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\n\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst targetSchema1 = {\n  $id: 'targetSchema1',\n  definitions: {\n    bar: { type: 'string' }\n  }\n}\n\nconst targetSchema2 = {\n  $id: 'targetSchema2',\n  type: 'object',\n  properties: {\n    qux: { $ref: 'targetSchema1' }\n  }\n}\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: { $ref: 'targetSchema2' }\n  }\n}\n\nconst refResolver = new RefResolver()\n\nrefResolver.addSchema(sourceSchema)\nrefResolver.addSchema(targetSchema1)\nrefResolver.addSchema(targetSchema2)\n\nconst dependencies = refResolver.getSchemaDependencies('sourceSchema')\nassert.deepStrictEqual(dependencies, { targetSchema1, targetSchema2 })\n```\n\n\u003ca name=\"deref-schema\"\u003e\u003c/a\u003e\n\n#### derefSchema(schemaId)\n\nDereferences all references in the schema. All dependencies will also be dereferenced. If schema with the specified id is not found, an error will be thrown.\n\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id of the schema to dereference.\n\n__If a json schema has circular references or circular cross-references, dereferenced schema will have js circular references. Be careful when traversing the dereferenced schema.__\n\n_Example_\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      $ref: 'targetSchema#/definitions/bar'\n    }\n  }\n}\n\nconst targetSchema = {\n  $id: 'targetSchema',\n  definitions: {\n    bar: {\n      type: 'string'\n    }\n  }\n}\n\nconst refResolver = new RefResolver()\n\nrefResolver.addSchema(sourceSchema)\nrefResolver.addSchema(targetSchema)\n\nrefResolver.derefSchema('sourceSchema')\nconst derefSourceSchema = refResolver.getDerefSchema('sourceSchema')\n\nassert.deepStrictEqual(derefSourceSchema, {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      type: 'string'\n    }\n  }\n})\n```\n\n\u003ca name=\"get-deref-schema\"\u003e\u003c/a\u003e\n\n#### getDerefSchema(schemaId, [jsonPointer])\n\nReturns a dereferenced schema by schema id and json pointer. If schema with the specified id is not found, an error will be thrown. If the `jsonPointer` argument is provided, ref resolver will return the schema at the specified json pointer location. If the `jsonPointer` argument is provided and the schema at the specified location is not found, getDerefSchema will return `null`.\n\nIf schema was not dereferenced before, it will be dereferenced during the call to `getDerefSchema`.\n\n- `schemaId` __\\\u003cstring\\\u003e__ - schema id of the schema to return.\n- `jsonPointer` __\\\u003cstring\\\u003e__ - json pointer to the schema location.\n- __Returns__ - dereferenced json schema or `null` if the schema at the specified location is not found.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      $ref: 'targetSchema#/definitions/bar'\n    }\n  }\n}\n\nconst targetSchema = {\n  $id: 'targetSchema',\n  definitions: {\n    bar: {\n      type: 'string'\n    }\n  }\n}\n\nconst refResolver = new RefResolver()\n\nrefResolver.addSchema(sourceSchema)\nrefResolver.addSchema(targetSchema)\n\nconst derefSourceSchema = refResolver.getDerefSchema('sourceSchema')\nassert.deepStrictEqual(derefSourceSchema, {\n  $id: 'sourceSchema',\n  type: 'object',\n  properties: {\n    foo: {\n      type: 'string'\n    }\n  }\n})\n```\n\n#### Caveats\n\n- If a reference schema and a source schema have a key with the same name and different values, an error will be thrown during a call to `derefSchema` or `getDerefSchema`.\n\n_Example:_\n\n```javascript\nconst assert = require('node:assert')\nconst { RefResolver } = require('json-schema-ref-resolver')\n\nconst targetSchema = {\n  $id: 'targetSchema',\n  definitions: {\n    bar: {\n      type: 'object',\n      properties: {\n        foo: { type: 'string' }\n      }\n    }\n  }\n}\n\nconst sourceSchema = {\n  $id: 'sourceSchema',\n  type: 'object',\n  $ref: 'targetSchema#/definitions/bar'\n  properties: {\n    foo: { type: 'number' }\n  }\n}\n\nconst refResolver = new RefResolver()\nrefResolver.addSchema(targetSchema)\nrefResolver.addSchema(sourceSchema)\n\nrefResolver.derefSchema('sourceSchema') // Throws an error\n```\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fjson-schema-ref-resolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Fjson-schema-ref-resolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fjson-schema-ref-resolver/lists"}