Schema Calc

An invoice that checks its own arithmetic—with an ordinary JSON Schema.

Write an equation. Compile it once. Hand the resulting .schema.json to a standard validator in another language. It can reject a one-cent error without installing Schema Calc.

total = subtotal + shipping - discount
                   │
                   ▼
          invoice.schema.json
                   │
                   ▼
     Ajv (JavaScript) / jsonschema (Python)

127.50 + 4.95 - 10.00 = 122.45     ✓ accepted
127.50 + 4.95 - 10.00 = 122.46     ✗ rejected

The input stays a normal flat JSON object:

{"subtotal":"127.50","shipping":"4.95","discount":"10.00","total":"122.45"}

JSON Schema has no built-in operator for adding values from different properties. Schema Calc compiles bounded decimal equations and inequalities into a finite carry machine, then expresses that machine using standard conditionals, digit patterns and references. The validator becomes the execution engine.

The example schema is 41,391 bytes, down from 284,300 bytes for the first construction, with the same input and numeric bounds. No gzip, custom keywords, $data, arithmetic callbacks, or remotely fetched schemas are involved. Both independent validators check the actual exported file.

Try it in your browser · Download v0.5.0: the invoice schema, both records and a standalone Python validator.

One cent, two validators · Computational model · Compression · Verification · Research notes

One cent, two validators

1. The playground accepts the correct invoice.
2. Add one cent changes only the total, to 122.46, and the generated schema rejects it.
3. Download the schema, the record and validate.py.
4. Stock Python jsonschema rejects the record too, in a fresh environment where Schema Calc was never installed.

The captions are added by the recording; the terminal panel replays the commands and their output as captured from that run, on the files the browser had just downloaded (scripts/demo/record.mjs). scripts/check-handoff.mjs repeats the handoff in CI for accepted and one-cent records in both encodings.

Reproduce it without cloning

You need Python 3 and jsonschema 4.25.1; not Node, and not this repository:

python3 -m pip install jsonschema==4.25.1
base=https://github.com/fMindstormer/schema-calc/releases/download/v0.5.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

validate.py is a short script that never imports the compiler; it exits with 1 when any record is rejected. For a record you edited yourself, use the playground's two download buttons: the page prints the matching command and the output to expect.

Run it locally

Requires Node.js 20 or newer; Node 24 is the reference development version.

npm ci
npm run demo

The demo loads the checked-in invoice schema directly into stock Ajv. It prints ACCEPT for the correct total and REJECT for the one-cent error. It never imports the compiler. The equivalent independent Python example is examples/validate.py.

For the browser playground:

npm run build
npm start

Open localhost:4173, change the record, click Add one cent, and download the schema. Try an allocation that must sum to 100, 999.99 + 0.01 = 1000.00 to exercise a long carry, an even split, where two inequalities hold each share to a third of the total rounded down to the cent, or line items, each its net plus tax, that add up to the total. Compilation and validation run locally in a browser worker; the built playground needs no external assets or services.

What is it useful for?

A schema can travel with a dataset, configuration file or API contract. Schema Calc lets that artifact carry exact reconciliation rules too: totals, percentage budgets, balances, or quantities that must add up. A receiving system needs a compatible Draft 2020-12 validator, rather than an implementation of each rule in each host language.

Eight rules of EN 16931, the European e-invoicing standard, compile into one schema for each of its two syntaxes, stating each rule as the official Schematron checks it: the document totals, BR-CO-10 to BR-CO-16, and BR-CO-17, each VAT category's tax as its taxable amount times its rate, for a listed set of rates. On the official example invoices and 770 changed copies of them, the schemas give the Schematron's verdict on all 804, rule by rule; see EN 16931 totals in plain JSON Schema.

This is a research prototype with a working compiler, CLI and playground. Its advantage is the portable contract. A handwritten arithmetic check is much smaller and usually faster when you control the receiving application. Schema Calc checks a supplied answer; it does not fill in a missing total.

Compile your own contract

examples/invoice.contract.json:

{
  "title": "Invoice arithmetic",
  "integerDigits": 4,
  "scale": 2,
  "fields": ["subtotal", "shipping", "discount", "total"],
  "constraints": ["total = subtotal + shipping - discount"]
}

node bin/schema-calc.mjs examples/invoice.contract.json invoice.schema.json

Omit the output path to write JSON to stdout. Diagnostics go to stderr. The JavaScript API is dependency-free and works in Node or a browser:

This is the beginning of the README. Read the rest at the original. Read the full README ↗