The JESS.jq module and the JESS validation script

Table of Contents

• Overview
• Customization
• Simple examples
• JESS Script

Overview

The jq module JESS.jq defines several jq filters for validating one or more JSON entities against a schema defined using the schema specification language JESS.

The jq function conforms_to(t) checks whether its input is of type t, that is, if it satisfies all the constraints specified by t, where t is a JSON entity specifying a JESS schema, which could be a schema of the form generated by schema.jq. conforms_to/1 simply returns true or false.

The jq function check(stream) checks a stream of JSON entities against a schema, $schema, which is usually specified on the command line. checks/1 provides some details about non-conforming items in the stream.

For convenience, as illustrated in the third example below, the function check is defined as check(inputs).

Customization

To specify that a file, say PRELUDE.json, contains a JESS prelude object, jq should be invoked using either the --argfile or --slurpfile command-line option, e.g.

  $ jq -n --slurpfile prelude PRELUDE.json --slurpfile schema MYSCHEMA.json '
      include "JESS"; check'  

Or if you have multiple schema files:

  $ jq -n --slurpfile prelude PRELUDE.json --slurpfile schema <(cat *.schema) '
    include "JESS"; check_schemas'

Simple examples

(i) An array of integers:

[1,2] | conforms_to( ["integer"] )

(ii) An object with a key "a" whose value must be an array of consisting of nulls and/or numbers

{"a": [null]} | conforms_to( {a: ["null", "number"] } )

(iii) Check a file of JSON objects against a given schema:

jq -n --argjson schema '{"answers": ["string","integer"]}' 'include "conforms"; check' input.json

(iv) An object with a key, "a", the value of which must be an integer in the range 0 to 10 inclusive:

{"a": 1} | conforms_to( {a: ["&", "integer", {"min":0, "max":10} ]})

JESS Script

The JESS script, located in the bin/ directory, requires bash. For help, run: JESS -h