jsonld-flatfile v1.0.1
jsonld-flatfile
Similar Projects
Q/A
Why use jsonld-flatfile
instead of JSON.stringify
?
This package's stringification creates deterministic output from human-authored input.
Equivalent data results in equivalent serializations.
JavaScript implementations and some REPLs maintain an insertion order on Object
properties.
Object.keys
and JSON.stringify
preserve that order in their output.
However, other REPLs and debuggers present Object
properties ordered lexicographically.
The JSON-LD parser is indifferent to property order, and does not guarantee a stable sort on Object
properties in output.
This package's stringification enforces a lexicographic sort order on Object
properties by default.
Re-evaluated output is guareenteed line-by-line equivalence in text-editors and runtimes.
Modified output in SCM always has minimal changesets in diff reports; no extra lines due to an unstable sort.
Forgo meaningless peturbations and save time by sorting.
Why does stringify
use jsonld.flatten
?
Flattened form gives a stable sort on node order: lexicographically by @id
value.
It polarizes property direction by removing @reverse
aliases and objects.
Flattened form is also compacted form; it's more amenable to editing than expanded form.
Flattening collects all properties of a node in a single JSON object and labels all blank nodes with blank node identifiers. This ensures a shape of the data and consequently may drastically simplify the code required to process JSON-LD in certain applications. --JSON-LD 1.0
What does the output look like?
{
"@context": {
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"@graph": [
{
"@id": "_:b0",
"rdf:type": {
"@id": "http://localhost/o"
}
}
]
}
test/assets/src/default_graph.json
What should the input be?
With a single argument, the object should define the @context
property.
Otherwise, use options.ctx
.
Save test file in node_modules/jsonld-flatfile/test/assets/src
and run:
cd node_modules/jsonld-flatfile
npm install
gulp proc
npm test
Modules/API
plugin
stringify in a vinyl object transform.
var gulp = require( 'gulp' )
var stringify = require( 'jsonld-flatfile/plugin' )
gulp.task( 'myproc', function () {
var proc = stringify().on( 'error', log_json )
return gulp.src( [ 'test/assets/src/test.json' ] )
.pipe( proc )
.pipe( gulp.dest( 'test/assets/flatten1/' ) )
}
)
function log_json() {
var o = JSON.stringify( arguments[0], null, 2 )
console.log( o )
}
stringify
Flatten, compact, sort, and format JSON-LD as a String
using jsonld.flatten
and json-stable-stringify, and append a newline.
var stringify = require( 'jsonld-flatfile/stringify' )
stringify( jsonld, options, callback )
where:
jsonld
is an Object or Stringoptions
is an Object with the optional properties:cmp
, a Function synchronously called during stringification (default null)ctx
, a JSON-LD context applied during compacting (default undefined, uses the jsonld parameter)pre
, a Function asynchronously called before stringification (default nop)post
, a Function asynchronously called after stringification (default nop)replacer
, a filtering Function or whitelist Array forJSON.stringify
(default null)space
, the number of spaces to indent inJSON.stringify
(default 2)
callback
an asynchronous return function
and returns:
undefined
/ use acallback
argument
options.cmp
passed through, see opts.cmp
options.ctx
a JSON-LD context object
options.pre
must be a function with the signature:
function ( error, json, callback )
callback( error, json )
}
where:
error
will always benull
json
is an object instancecallback
is a function back intostringify
and returns:
undefined
/ usecallback
options.post
must be a function with signature:
function ( error, jsonld, callback )
callback( error, jsonld )
}
where:
error
may contain parsing errors from JSON-LDjsonld
is an object instancecallback
is a function back intostringify
options.replacer
passed through, see opts.replacer
options.space
passed through, see opts.space