Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cvent/json-schema-deref
json-schema dereference utility
https://github.com/cvent/json-schema-deref
Last synced: 9 days ago
JSON representation
json-schema dereference utility
- Host: GitHub
- URL: https://github.com/cvent/json-schema-deref
- Owner: cvent
- License: mit
- Created: 2015-01-28T03:16:01.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2021-09-21T07:42:36.000Z (about 3 years ago)
- Last Synced: 2024-10-13T13:39:00.720Z (30 days ago)
- Language: JavaScript
- Homepage: http://bojand.github.io/json-schema-deref
- Size: 276 KB
- Stars: 39
- Watchers: 6
- Forks: 18
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# json-schema-deref
[](https://www.npmjs.com/package/json-schema-deref)
[](https://travis-ci.org/bojand/json-schema-deref)
[](https://standardjs.com)
[](https://raw.githubusercontent.com/bojand/json-schema-deref/master/LICENSE)
Dereference JSON pointers in a JSON schemas with their true resolved values.
A lighter synchronous version of this module is available as [json-schema-deref-sync](https://github.com/bojand/json-schema-deref-sync),
but omits web references and custom loaders.
## Installation
`npm install json-schema-deref`
## Overview
Let's say you have the following JSON Schema:
```json
{
"description": "Just some JSON schema.",
"title": "Basic Widget",
"type": "object",
"definitions": {
"id": {
"description": "unique identifier",
"type": "string",
"minLength": 1,
"readOnly": true
}
},
"properties": {
"id": {
"$ref": "#/definitions/id"
},
"foo": {
"$ref": "http://www.mysite.com/myschema.json#/definitions/foo"
},
"bar": {
"$ref": "bar.json"
}
}
}
```
Sometimes you just want that schema to be fully expanded, with `$ref`'s being their (true) resolved values:
```json
{
"description": "Just some JSON schema.",
"title": "Basic Widget",
"type": "object",
"definitions": {
"id": {
"description": "unique identifier",
"type": "string",
"minLength": 1,
"readOnly": true
}
},
"properties": {
"id": {
"description": "unique identifier",
"type": "string",
"minLength": 1,
"readOnly": true
},
"foo": {
"description": "foo property",
"readOnly": true,
"type": "number"
},
"bar": {
"description": "bar property",
"type": "boolean"
}
}
}
```
This utility lets you do that:
```js
var deref = require('json-schema-deref');
var myschema = require('schema.json');
deref(myschema, function(err, fullSchema) {
console.dir(fullSchema); // has the full expanded $refs
});
```
## API Reference
### deref(schema, options, fn)
Derefs $ref's in JSON Schema to actual resolved values. Supports local, file and web refs.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| schema | Object | The JSON schema |
| options | Object | options |
| options.baseFolder | String | the base folder to get relative path files from. Default is process.cwd() |
| options.cache | String | whether to cache the result from the request. Default: true. |
| options.cacheTTL | Number | the time to keep request result in cache. Default is 5 minutes. |
| options.failOnMissing | Boolean | By default missing / unresolved refs will be left as is with their ref value intact. If set to true we will error out on first missing ref that we cannot resolve. Default: false. |
| options.loader | function | a function for custom loader. Invoked if we could not resolve the ref type, or if there was an error resolving a web or file ref types. function with signature: function(refValue, options, fn) refValue - the string value of the ref being resolved. Ex: db://my_database_id options - options parameter passed to deref fn - the final callback function, in form function(err, newValue) err - error if ref is valid for the loader but there was an error resolving the ref. If used in combination with failOnMissing option it will abort the whole deref process. newValue - the resolved ref value, or null or undefined if the ref isn't for this custom loader and we should just leave the $ref as is. |
| options.mergeAdditionalProperties | Boolean | By default properties in a object with $ref will be removed in the output. If set to true they will be added/overwrite the output. Default: false. |
| options.removeIds | Boolean | By default $id fields will get copied when dereferencing. If set to true they will be removed. Default: false. |
| fn | function | The final callback in form (error, newSchema) |
## Custom Loader
Let's say we want to get $ref's from a MongoDB database, and our `$ref` objects in the JSON Schema might be something like:
```json
"foo": {
"$ref":"mongodb:507c35dd8fada716c89d0013"
}
```
Our custom loader function passed in the `options` `loader` parameter would look something like:
```js
function myMongoDBLoader(ref, option, fn) {
if(ref.indexOf('mongodb:') === 0) {
var id = ref.substring(8);
return collection.findOne({_id:id}, fn);
}
// not ours, pass back nothing to keep it the same
// or pass error and use failOnMissing to abort
return fn();
}
```