Skip to content

schema-calc v0.6.0

Latest

Choose a tag to compare

@fMindstormer fMindstormer released this 14 Nov 17:22
· 2 commits to main since this release

Why a record fails. A rejected record now comes with the constraint it breaks: validate.py prints it under REJECT, with nothing installed but jsonschema, and the playground and the JavaScript API give the same report. A contract can name its constraints, and the EN 16931 schemas name theirs after the rules they compile, so each rejected invoice's report names exactly the BR-CO rules the official Schematron finds broken. Try it in any browser; nothing is sent to a server.

What's new

  • Failure reports. The compiler marks each constraint's subschema with its source in $comment, and examples/validate.py finds those marks from Python jsonschema's own errors:

    REJECT  invoice.invalid.json
      fails: total = subtotal + shipping - discount
    

    A constraint on each line lists the lines that break it: fails: lines.amount = lines.net + lines.tax at /lines/0. When the record's format is wrong its arithmetic means nothing, so the report lists the format problems instead, at JSON Pointers: missing: /total, unexpected: /note, invalid: /lines/2/net. The verdict never depends on the report, and only a rejected record needs one; it costs about one more validation.

  • Named constraints. A contract entry may be {"name": "BR-CO-13", "constraint": "…"}, and the report prints fails BR-CO-13: …. The name goes into the constraint's title, changes no verdict and costs a few bytes. Names have 1 to 64 printable characters, without spaces at either end.

  • The playground explains its verdict. The status line names the failing constraint, as in "Fails: total = subtotal + shipping - discount.", and the expected output it prints for the downloaded files includes the report, word for word as validate.py prints it.

EN 16931

The EN 16931 contracts name their constraints BR-CO-10 to BR-CO-17, and the comparison now checks reports as well as verdicts. On all 804 test invoices the verdicts agree with the official Schematron, as in 0.5.0, and on each of the 645 it rejects, the report names exactly the rules the Schematron reports broken, in Ajv and in validate.py.

Check it without Schema Calc

Python 3 and jsonschema only, in an empty directory:

python3 -m pip install jsonschema==4.25.1
base=https://github.com/fMindstormer/schema-calc/releases/download/v0.6.0
for f in validate.py invoice.schema.json invoice.valid.json invoice.invalid.json; do curl -fLO "$base/$f"; done
python3 validate.py invoice.schema.json invoice.valid.json invoice.invalid.json
ACCEPT  invoice.valid.json
REJECT  invoice.invalid.json
  fails: total = subtotal + shipping - discount

The line-items schema and records work the same way with lines.schema.json, lines.valid.json and lines.invalid.json; the report names the line: fails: lines.amount = lines.net + lines.tax at /lines/0.

How the reports are checked

  • Every report in the tests is compared with schemas compiled from one constraint at a time, including schemas whose constraints the resource packer moved into root $defs, the $defs layout and the tally encoding.
  • On every rejected record of the two test corpora, 55,605 of them, validate.py gives the same report as Ajv. npm run check:python and check:tally recheck an evenly spaced sample of 12,868 on each run.
  • The test corpus is unchanged at 45,451 records across 92 schemas, and in the twelve-validator compatibility run on this release's code, again none gave a wrong answer.

For library users

  • prepareValidator(schema) returns a validator with a failures(record) method: {format: [{problem, at}], constraints: []} when the format is wrong, else {format: [], constraints: [{source, name?, list?, items?}]}. describeFailures(report), from src/failures.mjs, prints it as validate.py does.
  • normalizeSpec accepts a constraint as {name, constraint} and returns constraints as strings, plus names, with null for an unnamed one, when any is named.
  • Compiled output changes only for a named constraint, which gains a title. The shipped example schemas are byte-for-byte the same as in 0.5.0; validate.py is the file that changed.

Files

invoice.schema.json is the compiled invoice contract, unchanged from 0.5.0; invoice.valid.json and invoice.invalid.json are the correct record and the one a cent off. validate.py is the standalone validator: it needs only jsonschema and never imports the compiler. schema-calc-0.6.0.zip is the source, with a MANIFEST.sha256 inside; schema-calc-0.6.0.zip.sha256 is its checksum and SHA256SUMS covers every file.

Scope

Unchanged from 0.5.0: sums and differences of decimal strings, signed if declared, their whole-number multiples, abs(), products by a field with listed values, and sums over lists, related by =, <=, >=, < or > and joined by and and or with presence tests, on the record or on each line: up to 16 fields, 4 lists of 20 items, 8 constraints, 12 digits and 32 listed values per field. No other products of fields, division, !=, parentheses, not, indexing into a list or other nested objects. A research prototype; it is not published to npm.