{"id":15012946,"url":"https://github.com/apidevtools/json-schema-ref-parser","last_synced_at":"2026-01-16T22:16:58.342Z","repository":{"id":34965639,"uuid":"39041446","full_name":"APIDevTools/json-schema-ref-parser","owner":"APIDevTools","description":"Parse, Resolve, and Dereference JSON Schema $ref pointers in Node and browsers","archived":false,"fork":false,"pushed_at":"2025-04-18T19:05:02.000Z","size":38510,"stargazers_count":1018,"open_issues_count":18,"forks_count":236,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-11T11:11:43.048Z","etag":null,"topics":["javascript","json-pointer","json-reference","json-schema","nodejs","openapi","parser","resolver","universal-javascript"],"latest_commit_sha":null,"homepage":"http://apidevtools.com/json-schema-ref-parser/","language":"TypeScript","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/APIDevTools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"philsturgeon"}},"created_at":"2015-07-13T22:52:29.000Z","updated_at":"2025-05-06T20:48:46.000Z","dependencies_parsed_at":"2024-04-07T19:30:50.192Z","dependency_job_id":"d0b49dfa-6e03-4bf8-8880-3d6492e6f335","html_url":"https://github.com/APIDevTools/json-schema-ref-parser","commit_stats":{"total_commits":626,"total_committers":52,"mean_commits":"12.038461538461538","dds":"0.27316293929712465","last_synced_commit":"27abe40702c18c02cae2ad9a0fdd5a33199d9154"},"previous_names":["bigstickcarpet/json-schema-ref-parser"],"tags_count":175,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fjson-schema-ref-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fjson-schema-ref-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fjson-schema-ref-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fjson-schema-ref-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/APIDevTools","download_url":"https://codeload.github.com/APIDevTools/json-schema-ref-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253554090,"owners_count":21926614,"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":["javascript","json-pointer","json-reference","json-schema","nodejs","openapi","parser","resolver","universal-javascript"],"created_at":"2024-09-24T19:43:28.288Z","updated_at":"2025-11-30T13:06:29.206Z","avatar_url":"https://github.com/APIDevTools.png","language":"TypeScript","readme":"# JSON Schema $Ref Parser\n\n#### Parse, Resolve, and Dereference JSON Schema $ref pointers\n\n[![Build Status](https://github.com/APIDevTools/json-schema-ref-parser/workflows/CI-CD/badge.svg?branch=master)](https://github.com/APIDevTools/json-schema-ref-parser/actions)\n[![Coverage Status](https://coveralls.io/repos/github/APIDevTools/json-schema-ref-parser/badge.svg?branch=master)](https://coveralls.io/github/APIDevTools/json-schema-ref-parser)\n\n[![npm](https://img.shields.io/npm/v/@apidevtools/json-schema-ref-parser.svg)](https://www.npmjs.com/package/@apidevtools/json-schema-ref-parser)\n[![License](https://img.shields.io/npm/l/@apidevtools/json-schema-ref-parser.svg)](LICENSE)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser)\n\n## Installation\n\nInstall using [npm](https://docs.npmjs.com/about-npm/):\n\n```bash\nnpm install @apidevtools/json-schema-ref-parser\nyarn add @apidevtools/json-schema-ref-parser\nbun add @apidevtools/json-schema-ref-parser\n```\n\n## The Problem:\n\nYou've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead\nof time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML\nformat. Maybe some of the files contain cross-references to each other.\n\n```json\n{\n  \"definitions\": {\n    \"person\": {\n      \"$ref\": \"schemas/people/Bruce-Wayne.json\"\n    },\n    \"place\": {\n      \"$ref\": \"schemas/places.yaml#/definitions/Gotham-City\"\n    },\n    \"thing\": {\n      \"$ref\": \"http://wayne-enterprises.com/things/batmobile\"\n    },\n    \"color\": {\n      \"$ref\": \"#/definitions/thing/properties/colors/black-as-the-night\"\n    }\n  }\n}\n```\n\n## The Solution:\n\nJSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)\nand [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most\ncomplex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward\nJavaScript objects.\n\n- Use **JSON** or **YAML** schemas \u0026mdash; or even a mix of both!\n- Supports `$ref` pointers to external files and URLs, as well\n  as [custom sources](https://apidevtools.com/json-schema-ref-parser/docs/plugins/resolvers.html) such as databases\n- Can [bundle](https://apidevtools.com/json-schema-ref-parser/docs/ref-parser.html#bundlepath-options-callback) multiple\n  files into a single schema that only has _internal_ `$ref` pointers\n- Can [dereference](https://apidevtools.com/json-schema-ref-parser/docs/ref-parser.html#dereferencepath-options-callback)\n  your schema, producing a plain-old JavaScript object that's easy to work with\n- Supports [circular references](https://apidevtools.com/json-schema-ref-parser/docs/#circular-refs), nested references,\n  back-references, and cross-references between files\n- Maintains object reference equality \u0026mdash; `$ref` pointers to the same value always resolve to the same object\n  instance\n- Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux\n\n## Example\n\n```javascript\nimport $RefParser from \"@apidevtools/json-schema-ref-parser\";\n\ntry {\n  await $RefParser.dereference(mySchema);\n  // note - by default, mySchema is modified in place, and the returned value is a reference to the same object\n  console.log(mySchema.definitions.person.properties.firstName);\n\n  // if you want to avoid modifying the original schema, you can disable the `mutateInputSchema` option\n  let clonedSchema = await $RefParser.dereference(mySchema, { mutateInputSchema: false });\n  console.log(clonedSchema.definitions.person.properties.firstName);\n} catch (err) {\n  console.error(err);\n}\n```\n\nFor more detailed examples, please see the [API Documentation](https://apidevtools.com/json-schema-ref-parser/docs/)\n\n## Polyfills\n\nIf you are using Node.js \u003c 18, you'll need a polyfill for `fetch`,\nlike [node-fetch](https://github.com/node-fetch/node-fetch):\n\n```javascript\nimport fetch from \"node-fetch\";\n\nglobalThis.fetch = fetch;\n```\n\n## Browser support\n\nJSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers may\nrequire [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).\n\nTo use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such\nas [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/),\nor [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as\nsetting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).\n\n#### Webpack 5\n\nWebpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up\nyourself ( after npm-installing them )\nEdit your `webpack.config.js` :\n\n```js\nconfig.resolve.fallback = {\n  path: require.resolve(\"path-browserify\"),\n  fs: require.resolve(\"browserify-fs\"),\n};\n\nconfig.plugins.push(\n  new webpack.ProvidePlugin({\n    Buffer: [\"buffer\", \"Buffer\"],\n  }),\n);\n```\n\n## API Documentation\n\nFull API documentation is available [right here](https://apidevtools.com/json-schema-ref-parser/docs/)\n\n## Contributing\n\nI welcome any contributions, enhancements, and\nbug-fixes. [Open an issue](https://github.com/APIDevTools/json-schema-ref-parser/issues) on GitHub\nand [submit a pull request](https://github.com/APIDevTools/json-schema-ref-parser/pulls).\n\n#### Building/Testing\n\nTo build/test the project locally on your computer:\n\n1. **Clone this repo**\u003cbr\u003e\n   `git clone https://github.com/APIDevTools/json-schema-ref-parser.git`\n\n2. **Install dependencies**\u003cbr\u003e\n   `yarn install`\n\n3. **Run the tests**\u003cbr\u003e\n   `yarn test`\n\n## License\n\nJSON Schema $Ref Parser is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.\n\n## Thanks\n\nThanks to these awesome contributors for their major support of this open-source project.\n\n- [JonLuca De Caro](https://jonlu.ca)\n- [Phil Sturgeon](https://philsturgeon.com)\n- [Stoplight](https://stoplight.io/?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=json_schema_ref_parser)\n","funding_links":["https://github.com/sponsors/philsturgeon"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapidevtools%2Fjson-schema-ref-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapidevtools%2Fjson-schema-ref-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapidevtools%2Fjson-schema-ref-parser/lists"}