# json-ref-lite

> Extremely light weight way to resolve jsonschema '$ref' references & inheritance: create circular/graphs, fractals from json (browser/coffeescript/javascript).

Latest version **1.1.0** (published 2017-03-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install json-ref-lite
pnpm add json-ref-lite
yarn add json-ref-lite
bun add json-ref-lite
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2017-03-29 |
| First published | 2015-09-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 7 |
| Maintainers | coderofsalvation |
| Keywords | json, jsonschema, ref, json pointers, jsonpointer, jsonref, $ref, resolve, remote reference, json jsonschema ref json pointers jsonref remote reference lightweight, circular, graph |

## Links

- npm: https://www.npmjs.com/package/json-ref-lite
- Repository: https://coderofsalvation@github.com/coderofsalvation/json-ref-lite
- Homepage: https://github.com/coderofsalvation/json-ref-lite
- Issues: https://github.com/coderofsalvation/json-ref-lite/issues
- npm.io page: https://npm.io/package/json-ref-lite

## Dependencies (1)

- [property-expr](https://npm.io/package/property-expr.md) ^1.3.1

## 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

- 1.1.0 (latest) — 2017-03-29
- 1.0.73 — 2015-11-13
- 1.0.72 — 2015-11-13
- 1.0.71 — 2015-11-06
- 1.0.69 — 2015-11-06
- 1.0.68 — 2015-11-04
- 1.0.67 — 2015-11-04
- 1.0.66 — 2015-11-04
- 1.0.64 — 2015-11-03
- 1.0.63 — 2015-11-03
- 1.0.62 — 2015-11-02
- 1.0.61 — 2015-11-01
- 1.0.60 — 2015-11-01
- 1.0.58 — 2015-10-07
- 1.0.57 — 2015-10-05
- … 9 more at https://npm.io/package/json-ref-lite/versions

## README

Extremely light weight way to resolve jsonschema '$ref' references & inheritance: create circular/graphs, fractals from json (browser/coffeescript/javascript).

<img alt="" src="https://raw.githubusercontent.com/coderofsalvation/jsongraph/master/logo.png"/>

Stop processing json tree-structures, think json references and extentions.

# Usage

nodejs:

    jref = require('json-ref-lite')

or in the browser:

    <script type="text/javascript" src="json-ref-lite.min.js"></script>
    jref = require('json-ref-lite');

For example here's how to do a multidirected graph:

      json = {
        "a": { "$ref": [{"$ref":"#/b"}]           },
        "b": { "$ref": [{"$ref": [{"$ref":"#/a"}] }
      }
      console.dir(jref.resolve(json));

outputs:

      { a: { '$ref': [ { '$ref': [ [Circular] ] } ] },
        b: { '$ref': [ { '$ref': [ [Circular] ] } ] } }

> NOTE #1: for flowprogramming with json-ref-lite see [jsongraph](https://npmjs.org/packages/jsongraph)
> NOTE #2: for converting a restful service to server/client graph see [ohmygraph](https://npmjs.org/packages/ohmygraph)

# Resolve Jsonschema v1/2/3 references

json-ref-lite resolves newer, older jsonschema reference notations, as well as simple dotstyle:

    json = {
      foo: {
        id: 'foobar',
        value: 'bar'
      },
      old: { '$ref': 'foobar'      }
      new: { '$ref': '#/foo/id'    }
      dotstyle: { '$ref': '#foo.id' } 
    };

    console.dir(jref.resolve(json));

Outputs:

    { 
      foo: { id: 'foobar', value: 'bar' },
      old: { value: 'bar' },
      new: 'foobar',
      dotstyle: 'foobar',
    }

# Why?

Because dont-repeat-yourself (DRY)! 
It is extremely useful to use '$ref' keys in jsonschema graphs.
Instead of writing manual REST-api gluecode, you can build a restgraph client & server.

# Rule of thumb

When referencing to keys, always use underscores. Not doing this will not resolve references correctly.

# Features 

| Feature                                             | Notation                                                               |
|-----------------------------------------------------|------------------------------------------------------------------------|
|resolving (old) jsonschema references to 'id'-fields | `"$ref": "foobar"`                                                     |
|resolving (new) jsonschema internal jsonpointers     | `"$ref": "#/foo/value"`                                                |
|resolving positional jsonpointers                    | `"$ref": "#/foo/bar[2]"`                                               |
|resolving grouped jsonpointers                       | `"$ref": [{"$ref": "#/foo"},{"$ref": "#/bar}]` for building jsongraphs |
|evaluating positional jsonpointer function           | `"$ref": "#/foo/bar()"`                                                |
|resolving local files                                | `"$ref": "/some/path/test.json"`                                       |
|resolving remote json(schema) files                  | `"$ref": "http://foo.com/person.json"`                                 |
|resolving remote jsonpointers                        | `"$ref": "http://foo.com/person.json#/address/street"`                 |
|evaluating jsonpointer notation in string            | `foo_{#/a/graph/value}`                                                |
|evaluating dot-notation in string                    | `foo_{a.graph.value}`                                                  |

Developer tools:

| Feature                                             | Howto                                                                  |
|-----------------------------------------------------|------------------------------------------------------------------------|
|console.log debug output                             | `jref.debug = true`                                                    |
|redefine ref token                                   | `jref.reftoken = '@ref'`                                               |
|redefine extend token                                | `jref.extendtoken = '@extend'`                                         |
|redefine jsonpointer starttoken                      | `jref.pathtoken = '#'`                                                 |

> NOTE: re-defining tokens is useful to prevent resolving only certain references. A possible rule of thumb could be to have '$ref' references for serverside, and '@ref' references for clientside when resolving the same jsondata.

## Example: id fields

    json = {
      foo: {
        id: 'foobar',
        value: 'bar'
      },
      example: {
        '$ref': 'foobar'
      }
    };

outputs:

    { 
      foo: { id: 'foobar', value: 'bar' },
      example: { value: 'bar' } 
    }

## Example: jsonpointers

    {
      foo: {
        value: 'bar',
        foo: 'flop'
      },
      example: {
        ids: {
          "foo":"bar",
          '$ref': '#/foo/foo'
        }
      }
    }

outputs:

    {
      foo: {
        value: 'bar',
        foo: 'flop'
      },
      example: {
        foo:"bar",
        ids: 'flop' 
      }
    }

> NOTE: escaping slashes in keys is supported. `"#/model/foo['\\/bar']/flop"` will try to reference `model.foo['/bar'].flop` from itself 

## Example: remote schemas

    {
      foo: {
        "$ref": "http://json-schema.org/address"
      }
      bar: {
        "$ref": "http://json-schema.org/address#/street/number"
      }
    }

outputs: replaces value of foo with jsonresult from given url, also supports jsonpointers to remote source

> NOTE: please install like so for remote support: 'npm install json-ref-lite sync-request'

## Example: local files    

    {
      foo: {
        "$ref": "./test.json"
      }
    }

outputs: replaces value of foo with contents of file test.json (use './' for current directory).

## Example: array references

    {
      "bar": ["one","two"],
      "foo": { "$ref": "#/bar[1]" }
    }

outputs:

    {
      "bar": ["one","two"],
      "foo": "two"
    }

## Example: evaluating functions 

Ofcoarse functions fall outside the json scope, but they can be executed after
binding them to the json.

    json = {
      "bar": { "$ref": "#/foo()" }
    }

    json.foo = function(){ return "Hello World"; }

outputs:

    {
      "bar": "Hello World"
    }


## Example: Graphs / Circular structures

Json-ref allows you to build circular/flow structures.

    {
      "a": { "$ref": [{"$ref":"#/b"}] },
      "b": { "$ref": [{"$ref":"#/a"}] },
      "c": { "$ref": [{"$ref":"#/a"}] }
    }

This resembles the following graph: b<->a<-c

See superminimalistic dataflow programming example here [JS](/test/flowprogramming.js) / [CS](/test/flowprogramming.coffee)

> HINT: But hey, since you're reading this, why not use [jsongraph](https://npmjs.org/packages/jsongraph) instead?

## Example: evaluating data into graph

Process graph-values into strings:

    data = 
      boss: {name:"John"}
      employee: {name:"Matt"}

    template = jref.resolve 
      boss:
        name: "{boss.name}"
      employee:
        name: "{#/employee/name}"
      names: [{"$ref":"#/boss/name"},{"$ref":"#/employee/name"}]

    graph = jref.evaluate template, data # !!! (k,v) -> return v

    console.log JSON.stringify graph, null, 2

> Note #1: you can override the evaluator with your own by adding a function as third argument. See the '!!' comment 
> Note #2: both jsonpointer notation `foo_{#/a/graph/value}` as well as dot-notation is allowed `foo_{a.graph.value}`

## Example: restgraph using jsonschema

CRUD operations in server/client without dealing with the underlying rest interface?
See the [ohmygraph](https://npmjs.org/packages/ohmygraph) module.

# Philosophy

* This is a zero-dependency module.
* isomorphic is cool
* pistachio icecream is nice

---
_Source: https://npm.io/package/json-ref-lite · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._