Calling the parser

Three different options for parsing are available:

• lib.parse(json, options), for parsing the value of a complete JSON document (similar to JSON.parse);
• lib.parseInfo(json, options), for parsing the value and metadata of a complete JSON document; or
• new lib.StreamParser(options), for streaming a JSON document.

The options argument allows you to configure the syntax, validation, and the information that will be read.

Get a value from a JSON document

The parse function may be used with all the same functionality as the ECMAScript builtin JSON.parse:

const value = lib.parse('true');
assert(value === true);

Tokenize a JSON document or get information about how its written

The parseInfo function may be used like the parse function, but instead, it returns an object that has the document's parsed value as well as metadata including character position information, and annotations such as descriptions for each property. This is useful for cases like code completion.

const info = lib.parseInfo('true', schema);
assert(info.value === true);
assert(info.description === 'Indicates if the switch is on');

Stream parse a JSON document

The StreamParser constructor may be used to create a streaming parser.

const parser = new lib.StreamParser({
	parseValue: true,
	schema: { type: 'array', items: { type: 'string' } },
});
fs.createReadStream('largefile.json').pipe(parser);
parser.on('end', function(){
	if(parser.errors.length) console.error(parser.errors.join('\n'));
	console.log(parser.value);
});

Validating & Parsing a Schema

Invalid keywords

Schema instances are created from a native object, and validated when they are created.

const schema = new lib.Schema({
	type: 'array',
	items: { type: 'string' },
});

If there are any "fatal" errors, that prevent it from validating an instance, these will be thrown as an Error.

// This will throw an Error
new lib.Schema({
	minLength: -1,
});

Unknown keywords

Unknown keywords do not emit an error by default. If there are any keywords not known,

The allUnknown keyword not only looks at the current schema, but all subschemas (except through references).

console.log(schema.unknown.join('\n'));
console.log(schema.allUnknown.join('\n'));

Listing References

All $ref references are stored in the references property as an array.

The allReferences property is an array of references not just in the current schema, but all subschemas (except through references).

console.log(schema.references.join('\n'));
console.log(schema.allReferences.join('\n'));

Unresolved references

Additionally, all $ref references must be resolved at the time it is used. To get a list of unresolved references, read the Schema#unknown array:

console.log(schema.registry.unresolvedReferences.join('\n'));

Reporting Validation Errors

When a JSON document is parsed using the schema option, it will validate the incoming JSON against the schema:

lib.parse(json, { schema });
lib.parseInfo(json, { schema });
new lib.StreamParser({ schema });

When using lib.parse, the validation error will be thrown.

When using the other forms, by default, validation error will be added to the errors array.

Migrating from other parsers

ECMAScript builtin JSON.parse

Use lib.parse as a drop-in replacement for JSON.parse.

This library only parses, so there is no equivalent to JSON.stringify.

JSON5

Homepage: https://github.com/json5/json5

JSON5 is a library that supports a superset of the JSON syntax, with a JSON.parse compatible API.

In place of JSON5.parse, use lib.parse as follows:

const JSON5opts = {
	syntaxUnquotedKeys: true,
	syntaxTrailingComma: true,
	syntaxSingleQuote: true,
	syntaxEscapeLF: true,
	syntaxHexadecimal: true,
	syntaxBareDecimal: true,
	syntaxInf: true,
	syntaxNaN: true,
	syntaxPlus: true,
}
const parsed = lib.parse(text, JSON5Opts);

If you need the reviver function, add a "reviver" property to the options.

This library only parses, so there is no equivalent to JSON5.stringify.

JSONStream

Clarinet.js

Homepage: https://github.com/dscape/clarinet

Clarinet is a SAX-like streaming parser for JSON.

Oboe.js

Homepage: http://oboejs.com/

Oboe.js is a streaming parser for JSON, derived from Clarinet, that supports retrieval over the network, and an API to split a (potentially very large) document into subdocuments, for easier processing by the application.

This library does not perform any network or filesystem functions; get a readable stream, somehow, and pipe it into a . For example in Node.js, use fs.createReadStream.