{"id":18084750,"url":"https://github.com/coderofsalvation/json-ref-lite","last_synced_at":"2025-06-18T09:36:28.568Z","repository":{"id":57285114,"uuid":"42851090","full_name":"coderofsalvation/json-ref-lite","owner":"coderofsalvation","description":"Extremely light weight way to resolve jsonschema '$ref' references \u0026 inheritance: create circular/graphs, fractals from json (browser/coffeescript/javascript)","archived":false,"fork":false,"pushed_at":"2020-05-28T19:09:37.000Z","size":50,"stargazers_count":7,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-16T23:16:57.909Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coderofsalvation.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},"funding":{"custom":"https://gumroad.com/l/hGYGh"}},"created_at":"2015-09-21T07:34:27.000Z","updated_at":"2024-08-31T06:05:09.000Z","dependencies_parsed_at":"2022-09-19T23:21:21.964Z","dependency_job_id":null,"html_url":"https://github.com/coderofsalvation/json-ref-lite","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coderofsalvation/json-ref-lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderofsalvation%2Fjson-ref-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderofsalvation%2Fjson-ref-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderofsalvation%2Fjson-ref-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderofsalvation%2Fjson-ref-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coderofsalvation","download_url":"https://codeload.github.com/coderofsalvation/json-ref-lite/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderofsalvation%2Fjson-ref-lite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260528346,"owners_count":23022923,"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":[],"created_at":"2024-10-31T15:08:03.421Z","updated_at":"2025-06-18T09:36:23.554Z","avatar_url":"https://github.com/coderofsalvation.png","language":"Shell","funding_links":["https://gumroad.com/l/hGYGh"],"categories":[],"sub_categories":[],"readme":"Extremely light weight way to resolve jsonschema '$ref' references \u0026 inheritance: create circular/graphs, fractals from json (browser/coffeescript/javascript).\n\n\u003cimg alt=\"\" src=\"https://raw.githubusercontent.com/coderofsalvation/jsongraph/master/logo.png\"/\u003e\n\nStop processing json tree-structures, think json references and extentions.\n\n# Usage\n\nnodejs:\n\n    jref = require('json-ref-lite')\n\nor in the browser:\n\n    \u003cscript type=\"text/javascript\" src=\"json-ref-lite.min.js\"\u003e\u003c/script\u003e\n    jref = require('json-ref-lite');\n\nFor example here's how to do a multidirected graph:\n\n      json = {\n        \"a\": { \"$ref\": [{\"$ref\":\"#/b\"}]           },\n        \"b\": { \"$ref\": [{\"$ref\": [{\"$ref\":\"#/a\"}] }\n      }\n      console.dir(jref.resolve(json));\n\noutputs:\n\n      { a: { '$ref': [ { '$ref': [ [Circular] ] } ] },\n        b: { '$ref': [ { '$ref': [ [Circular] ] } ] } }\n\n\u003e NOTE #1: for flowprogramming with json-ref-lite see [jsongraph](https://npmjs.org/packages/jsongraph)\n\u003e NOTE #2: for converting a restful service to server/client graph see [ohmygraph](https://npmjs.org/packages/ohmygraph)\n\n# Resolve Jsonschema v1/2/3 references\n\njson-ref-lite resolves newer, older jsonschema reference notations, as well as simple dotstyle:\n\n    json = {\n      foo: {\n        id: 'foobar',\n        value: 'bar'\n      },\n      old: { '$ref': 'foobar'      }\n      new: { '$ref': '#/foo/id'    }\n      dotstyle: { '$ref': '#foo.id' } \n    };\n\n    console.dir(jref.resolve(json));\n\nOutputs:\n\n    { \n      foo: { id: 'foobar', value: 'bar' },\n      old: { value: 'bar' },\n      new: 'foobar',\n      dotstyle: 'foobar',\n    }\n\n# Why?\n\nBecause dont-repeat-yourself (DRY)! \nIt is extremely useful to use '$ref' keys in jsonschema graphs.\nInstead of writing manual REST-api gluecode, you can build a restgraph client \u0026 server.\n\n# Rule of thumb\n\nWhen referencing to keys, always use underscores. Not doing this will not resolve references correctly.\n\n# Features \n\n| Feature                                             | Notation                                                               |\n|-----------------------------------------------------|------------------------------------------------------------------------|\n|resolving (old) jsonschema references to 'id'-fields | `\"$ref\": \"foobar\"`                                                     |\n|resolving (new) jsonschema internal jsonpointers     | `\"$ref\": \"#/foo/value\"`                                                |\n|resolving positional jsonpointers                    | `\"$ref\": \"#/foo/bar[2]\"`                                               |\n|resolving grouped jsonpointers                       | `\"$ref\": [{\"$ref\": \"#/foo\"},{\"$ref\": \"#/bar}]` for building jsongraphs |\n|evaluating positional jsonpointer function           | `\"$ref\": \"#/foo/bar()\"`                                                |\n|resolving local files                                | `\"$ref\": \"/some/path/test.json\"`                                       |\n|resolving remote json(schema) files                  | `\"$ref\": \"http://foo.com/person.json\"`                                 |\n|resolving remote jsonpointers                        | `\"$ref\": \"http://foo.com/person.json#/address/street\"`                 |\n|evaluating jsonpointer notation in string            | `foo_{#/a/graph/value}`                                                |\n|evaluating dot-notation in string                    | `foo_{a.graph.value}`                                                  |\n\nDeveloper tools:\n\n| Feature                                             | Howto                                                                  |\n|-----------------------------------------------------|------------------------------------------------------------------------|\n|console.log debug output                             | `jref.debug = true`                                                    |\n|redefine ref token                                   | `jref.reftoken = '@ref'`                                               |\n|redefine extend token                                | `jref.extendtoken = '@extend'`                                         |\n|redefine jsonpointer starttoken                      | `jref.pathtoken = '#'`                                                 |\n\n\u003e 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.\n\n## Example: id fields\n\n    json = {\n      foo: {\n        id: 'foobar',\n        value: 'bar'\n      },\n      example: {\n        '$ref': 'foobar'\n      }\n    };\n\noutputs:\n\n    { \n      foo: { id: 'foobar', value: 'bar' },\n      example: { value: 'bar' } \n    }\n\n## Example: jsonpointers\n\n    {\n      foo: {\n        value: 'bar',\n        foo: 'flop'\n      },\n      example: {\n        ids: {\n          '$ref': '#/foo/foo'\n        }\n      }\n    }\n\noutputs:\n\n    {\n      foo: {\n        value: 'bar',\n        foo: 'flop'\n      },\n      example: {\n        ids: 'flop' \n      }\n    }\n\n\u003e NOTE: escaping slashes in keys is supported. `\"#/model/foo['\\\\/bar']/flop\"` will try to reference `model.foo['/bar'].flop` from itself \n\n## Example: remote schemas\n\n    {\n      foo: {\n        \"$ref\": \"http://json-schema.org/address\"\n      }\n      bar: {\n        \"$ref\": \"http://json-schema.org/address#/street/number\"\n      }\n    }\n\noutputs: replaces value of foo with jsonresult from given url, also supports jsonpointers to remote source\n\n\u003e NOTE: please install like so for remote support: 'npm install json-ref-lite sync-request'\n\n## Example: local files    \n\n    {\n      foo: {\n        \"$ref\": \"./test.json\"\n      }\n    }\n\noutputs: replaces value of foo with contents of file test.json (use './' for current directory).\n\n## Example: array references\n\n    {\n      \"bar\": [\"one\",\"two\"],\n      \"foo\": { \"$ref\": \"#/bar[1]\" }\n    }\n\noutputs:\n\n    {\n      \"bar\": [\"one\",\"two\"],\n      \"foo\": \"two\"\n    }\n\n## Example: evaluating functions \n\nOfcoarse functions fall outside the json scope, but they can be executed after\nbinding them to the json.\n\n    json = {\n      \"bar\": { \"$ref\": \"#/foo()\" }\n    }\n\n    json.foo = function(){ return \"Hello World\"; }\n\noutputs:\n\n    {\n      \"bar\": \"Hello World\"\n    }\n\n\n## Example: Graphs / Circular structures\n\nJson-ref allows you to build circular/flow structures.\n\n    {\n      \"a\": { \"$ref\": [{\"$ref\":\"#/b\"}] },\n      \"b\": { \"$ref\": [{\"$ref\":\"#/a\"}] },\n      \"c\": { \"$ref\": [{\"$ref\":\"#/a\"}] }\n    }\n\nThis resembles the following graph: b\u003c-\u003ea\u003c-c\n\nSee superminimalistic dataflow programming example here [JS](/test/flowprogramming.js) / [CS](/test/flowprogramming.coffee)\n\n\u003e HINT: But hey, since you're reading this, why not use [jsongraph](https://npmjs.org/packages/jsongraph) instead?\n\n## Example: json inheritance / extensions\n\nThe \"$extend\" key is an easy way to inherit/extend existing objects.\nIt's like `patch` for json.\n\n    json = {\n      \"a\": {\n        \"foo\": {\n          \"bar\": { \"title\": \"foo\" }\n        }\n      },\n      \"$extend\": {\n        \"$ref\": \"#a.foo.bar\",\n        \"location\": \"skyscraper\",\n        \"sex\": \"male\"\n      }\n    }\n    jref.extend(json);\n\noutput:\n\n    {\n      \"a\": {\n        \"foo\": {\n          \"bar\": {\n            \"title\": \"foo\",\n            \"location\": \"skyscraper\",\n            \"sex\": \"male\"\n          }\n        }\n      }\n    }\n\n## Example: evaluating data into graph\n\nProcess graph-values into strings:\n\n    data = \n      boss: {name:\"John\"}\n      employee: {name:\"Matt\"}\n\n    template = jref.resolve \n      boss:\n        name: \"{boss.name}\"\n      employee:\n        name: \"{#/employee/name}\"\n      names: [{\"$ref\":\"#/boss/name\"},{\"$ref\":\"#/employee/name\"}]\n\n    graph = jref.evaluate template, data # !!! (k,v) -\u003e return v\n\n    console.log JSON.stringify graph, null, 2\n\n\u003e Note #1: you can override the evaluator with your own by adding a function as third argument. See the '!!' comment \n\u003e Note #2: both jsonpointer notation `foo_{#/a/graph/value}` as well as dot-notation is allowed `foo_{a.graph.value}`\n\n## Example: restgraph using jsonschema\n\nCRUD operations in server/client without dealing with the underlying rest interface?\nSee the [ohmygraph](https://npmjs.org/packages/ohmygraph) module.\n\n# Philosophy\n\n* This is a zero-dependency module.\n* isomorphic is cool\n* pistachio icecream is nice\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderofsalvation%2Fjson-ref-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoderofsalvation%2Fjson-ref-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderofsalvation%2Fjson-ref-lite/lists"}