Repository files navigation

Install usingnpm:

npm install @apidevtools/json-schema-ref-parseryarn add @apidevtools/json-schema-ref-parserbun add @apidevtools/json-schema-ref-parser

You've got a JSON Schema with$ref pointers to other files and/or URLs. Maybe you know all the referenced files aheadof time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAMLformat. Maybe some of the files contain cross-references to each other.

{"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"    }  }}

JSON Schema $Ref Parser is a fullJSON ReferenceandJSON Pointer implementation that crawls even the mostcomplexJSON Schemas and gives you simple, straightforwardJavaScript objects.

• UseJSON orYAML schemas — or even a mix of both!
• Supports$ref pointers to external files and URLs, as wellascustom sources such as databases
• Canbundle multiplefiles into a single schema that only hasinternal$ref pointers
• Candereferenceyour schema, producing a plain-old JavaScript object that's easy to work with
• Supportscircular 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 objectinstance
• Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux

import$RefParserfrom"@apidevtools/json-schema-ref-parser";try{await$RefParser.dereference(mySchema);// note - by default, mySchema is modified in place, and the returned value is a reference to the same objectconsole.log(mySchema.definitions.person.properties.firstName);// if you want to avoid modifying the original schema, you can disable the `mutateInputSchema` optionletclonedSchema=await$RefParser.dereference(mySchema,{mutateInputSchema:false});console.log(clonedSchema.definitions.person.properties.firstName);}catch(err){console.error(err);}

For more detailed examples, please see theAPI Documentation

If you are using Node.js < 18, you'll need a polyfill forfetch,likenode-fetch:

importfetchfrom"node-fetch";globalThis.fetch=fetch;

JSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers mayrequireBabel and/orpolyfills.

To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool suchasWebpack,Rollup,Parcel,orBrowserify. Some bundlers may require a bit of configuration, such assettingbrowser: true inrollup-plugin-resolve.

Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them upyourself ( after npm-installing them )Edit yourwebpack.config.js :

config.resolve.fallback={path:require.resolve("path-browserify"),fs:require.resolve("browserify-fs"),};config.plugins.push(newwebpack.ProvidePlugin({Buffer:["buffer","Buffer"],}),);

Full API documentation is availableright here

I welcome any contributions, enhancements, andbug-fixes.Open an issue on GitHubandsubmit a pull request.

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/APIDevTools/json-schema-ref-parser.git

2. Install dependencies
   yarn install

3. Run the tests
   yarn test

JSON Schema $Ref Parser is 100% free and open-source, under theMIT license. Use it however you want.

Thanks to these awesome contributors for their major support of this open-source project.

• JonLuca De Caro
• Phil Sturgeon
• Stoplight