Extremely light weight way to resolve jsonschema '$ref' references or create circular/graph structures (browser/coffeescript/javascript).

Dont think trees, think jsongraph, think graphmorphic applications.

Usage

nodejs:

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

or in the browser:

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

code:

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

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

Outputs:

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

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.

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

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

NOTE: for flowprogramming with json-ref-lite see jsongraph

Features

NOTE: for more functionality checkout jsongraph

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: {
      '$ref': '#/foo/foo'
    }
  }
}

outputs:

{
  foo: {
    value: 'bar',
    foo: 'flop'
  },
  example: {
    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": { edges: [{"$ref":"#/b"}] },
  "b": { edges: [{"$ref":"#/a"}] },
  "c": { edges: [{"$ref":"#/a"}] }
}

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

HINT: Superminimalistic dataflow programming example here JS / CS

There you go.

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?

the graph

graph = jref.resolve
  searchquery:
    type: "object"
    properties:
      category: { type: "string", default:'' }
      query:    { type: "string", default:'' }
  books:
    type: "array"
    books: [{"$ref":"#/book"}]
    data:
      get:
        config:
          method: 'get'
          url: '/books'
          payload:
            category: '{#/searchquery/properties/category/value}'
            query: '{#/searchquery/properties/query/value}'
        data: "{response.data}"
  book:
    type: "object"
    properties:
      id: { type:"number", default: 12 }
      name: { type: "string", default: 'John Doe' }
      category: { type: "string", default: 'amsterdam' }

....etc....

the server

for node,v of graph
  ( for method,u of v.data
    server[method] graph[node].data[method].config.url, (req, res, next) ->
      res.send "hello world..need some database bindingcode here"
      next();
  ) if v.data?

the client

rg = restgraph.create(graph)

# set user input
rg.get('searchquery').query.value = "foo"
rg.get('searchquery').category.value = "scifi"

# get items
graph.items.data.get (data) ->
  # do something with data, now we add a duplicate
  book = data[0]
  delete book.id
  book.post()

This could be used to allow server and/or clients to share the same rest-specs.

NOTE: see a minimal examplesource here: coffeescript / javascript

Philosophy

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