JYBID
json yaml bundle inherit dereference **
This lib allows to bundle/dereference json
and yaml
documents and extend a document with JSON-Patch
bundle
dereference
selectors
examples
Purpose
- Split big documents
- Not only reference but inherit one documents from another
- Have differences between documents in form of JSON-Patch
Why does somebody want that?
Well, when I was writing some API docs in OpenAPI format I had troubles:
- one doc for whole API is too big
- docs sometimes logically extend one another
- how to get diff between versions of API? It would be great to have JSON-Patch and visualize it somehow
So I wanted to:
- Use
json
andyaml
files simultaneously, being able to split big files into several smaller - Have some inheritance technique based on JSON-Patch
1 comes easy, it can be solved by json-schema-ref-parser
2 also has a solution like ajv-merge-patch
But all together it doesn't work out of box.
So I made a little patch to json-schema-ref-parser that enables inheritance based on JSON-Patch syntax.
Also I extended JSON-Pointer for array indexes in selectors.
Methods
bundle
bundle(filepath, options) returns Promise with object - to bundle a file
dereference
dereference(filepath, options) returns Promise with object - to bundle a file and resolve even internal references
For both
- if
options.inherit==true
then json-patches will be compiled - if
options.inherit
is a string then it will set a keyword instead of"$inherit"
and if it is"$patch"
then document syntax complies to ajv-merge-patch
Example:
const { bundle, dereference } = require('./index')
const fs = require('fs')
fs.writeFileSync('/tmp/a.json', JSON.stringify({
a: 1,
c: {$ref: '#/d'},
d: 4
}), {encoding: 'utf8'})
fs.writeFileSync('/tmp/b.json', JSON.stringify({
$inherit: {
source: {$ref: '/tmp/a.json'},
with: [{op: 'add', path: '/b', value: 2}]
}
}), {encoding: 'utf8'})
bundle('/tmp/a.json').then((doc) => {console.log(JSON.stringify(doc));})
{"a":1,"c":{"$ref":"#/d"},"d":4}
bundle('/tmp/b.json', {inherit: true}).then((doc) => {console.log(JSON.stringify(doc));})
{"a":1,"c":{"$ref":"#/d"},"d":4,"b":2}
dereference('/tmp/b.json', {inherit: true}).then((doc) => {console.log(JSON.stringify(doc));})
{"a":1,"c":4,"d":4,"b":2}
compilePatchOps
compilePatchOps(source, patch) returns Array
To compile JSON-Patch with selectors in pathes to JSON-Patch with JSON-Pointer pathes there is a method
When source document is bundled we check every patch operation:
- if it contains selector in path
- corresponding object in source is array
then we replace it with equal operation with JSON-Pointer path, for example:
const { compilePatchOps } = require('./index')
compilePatchOps(
{arr: [{a: 1}, {c: 2}, {c: {$ref: '#/d'}}, {d: 4}]},
[{op: 'replace', path: '/arr/[c=]', value: 2}]
);
[ { op: 'replace', path: '/arr/1', value: 2 },
{ op: 'replace', path: '/arr/2', value: 2 } ]
>
Selectors
by property value
with property
with value
In JSON-Patch path must be a JSON-Pointer, but referencing array elements does not look good: what means path: '/2'
?. At what element do we point? You never know until you see object to which you apply the patch
object = [1,2,234]
patch = [{op: 'remove', path: '/2'}]
Now we know, we wanted to remove 234
.
Here I say, lets select element by its properties or value like in jquery
// selector by value
patch = [{op: 'remove', path: '/[=234]'}]
// compiling patch
compilePatchOps(object, patch)
// patch with JSON-Pointer path
[{op: 'remove', path: '/2'}]
So you can have documents with easier to understand JSON-Patch operations and compile them when needed.
Note that inside selectors quotation is used:
-
\"
is"
-
\\
is\
-
/
is/
-
~
is~
, not~1
and~0
like in JSON-Pointer
so, selectors are:
by property=value pairs
Value is treated as string if possible and as number if it can't be string
-
[prop=value]
=={prop: 'value'}
-
[prop="13"]
=={prop: '13'}
-
[prop=42]
=={prop: 42}
-
["string attr name"=name]
=={'string attr name': 'name'}
To reference compicated property name use double quotes
with property
-
[prop=]
=={prop: 1}
or{prop: 'a'}
or{prop: null}
-
["string attr name"=]
for quoted property name -
[prop=null]
=={prop: null}
-
[prop="null"]
=={prop: "null"}
with value
-
[="name"]
=='name'
-
[=13]
==13
multiple conditions
It works like AND
[prop=name][date=]
== {prop: 'name', date: 'anything'}
Examples
Long story short
node index.js bundle --file examples/api_v1.yaml
And you have bundled API file for version 1.
Next you have version 2 in file api_v2, look how short it is. Compile it to have correct service API file for version 2
node index.js bundle --file examples/api_v2.yaml
Without JYBID you'd have to write it manually: bundled
Long story long
Suppose we have a weather forecast database and want to build a readonly service for it. We have data only for Russia and Finland and we supposed that cities in these countries always have different names so we dont need to specify country in request to our service. Of course this is not the best idea, but just for example..
So, we have a sevice API api_v1.
Also there are bundled and dereferenced documents.
You can try bundling or dereferencing like this
node index.js bundle --file examples/api_v1.yaml
Ok, next month we add forecasts for Belarus and we have troubles now: for example a town named 'Kamenka' exists in Russia and in Belarus.
Of course we need to add parameter country
but we can't add it to v1 because some people already use our API in their app and it works ok in Russia and in Finland. If we add country
with some default value many requests will fail. Well, we could make some workarounds based on city name being checked against list of all cities in our 3 countries but.. it is just better to make next version of API correct and ask our clients to use it instead of incorrect v1.
So we need to replace unclear parameter 'names' with 'cities' and add 'country', this api_v2 is how we could do it with jybid
Without inheritance you would have to make one of these documents manually bundled dereferenced
In api_v2 you can find examples of inheritance
$inherit:
source:
$ref: ./api_v1.yaml
with:
Codewords are
- $inherit
- source
- with
Also there is an example of array selector
path: '/paths/~1city/get/parameters/[name=names]'