@wmfs/j2119

j2119

A general-purpose validator generator that uses RFC2119-style assertions as input.

This package is derived from awslabs/j2119.

Usage

There is only one outward-facing function, J2119Validator.

const J2119Validator = require('@wmfs/j2119')

const validator = J2119Validator(schema-filename)

Where schema-filename is the name of a file containing text in the J2119 syntax described below. This returns a validator, which can be re-used, and should be, since its construction is moderately expensive:

const [json, problems] = validator.validate(json_source)

json_source is the JSON to be validated; it can be a JSON object, a filename or a file descriptor - J2119 tries to do the right thing. validate returns a tuple containing the the parsed JSON, and a string array containing messages describing any problems it found. If the array is empty, then there were no problems.

root returns the root "role" in the J2119 schema, a string that is useful in making user-friendly error messages.

J2119 Syntax

J2119's operations are driven by a set of assertions containing the words "MUST" and "MAY" used in the style found in IETF RFCs, and specified in RFC 2119. It is organized in lines, each terminated with a single full stop. There are three formalisms, "roles", "types" and "constraints". For example:

A Message MUST have an object-array field named "Paragraphs"; each member is a "Paragraph".

In the above assertion, "Message" and "Paragraph" are roles, "string-array" is a type; the whole line says that a JSON node with the role "Message" is required to have a field named "Paragraphs" whose value is a JSON array containing only object values. It further says that when validating the object members of the array, they are considered to have the role "Paragraph".

The first line of the J2119 schema must be of the following form:

This document specifies a JSON object called a "Message".

This gives the root object the role "Message". Descendant nodes can be given roles based on their parentage (as in the first J2119 example above) and the presence or value of certain fields, and nodes can have multiple roles simultaneously.

The J2119 syntax was invented for the purpose of constructing a validator for one specific JSON DSL, and at the time of writing of this document, there is no claim that it is suitable as a general-purpose JSON schema facility. At this point, the best way to understand J2119 is by example. In the data/ directory of this package there is a file AWL.j2119, which may be considered a complete worked example of how to specify a DSL.

To Do

At time of writing, the awslabs' package carries the following TODO

At the moment, the J2119 syntax is parsed via the brute-force application of overly complex regular expressions. It is in serious need of modularization, a real modern parser architecture, and perhaps the application of some natural-language processing techniques.

Aside from that, the framework of roles, conditionals, and constraints is simple enough and performs at acceptable speed.

Contributing

Bug reports and pull requests are welcome on GitHub. Please be aware of our Code of Conduct

License

Licensed under the terms of the MIT license. Copyright (c) 2018 West Midlands Fire Service