JSON Schema

Consumers that are not written in TypeScript can validate and generate code from the output with three JSON Schemas (draft 2020-12), generated from the types and published with the site:

• canonical-invoice.v1.schema.json: one CanonicalInvoice
• convert-result.v1.schema.json: what convert() returns (outcomes[].invoices[] are CanonicalInvoices)
• inspect-result.v1.schema.json: what inspect() returns, including the Detection type

Decimals, dates and times are strings with a pattern; open code lists (currency, country, VAT category, unit…) are plain strings whose common values are listed under examples; the BT/BG comments are the descriptions. Objects are open (additionalProperties is not false), so a payload from a newer minor release still validates. bun run build:schemas rewrites the files (and schemas/formats.json and openapi/openapi.json) and the CI test job runs bun run check:schemas, which fails when the committed files differ from the types. Every test fixture’s converted output is validated against them in test/schema.test.ts.

Schema versioning

The library exports schemaVersion ('v1'), the major version in the schema file names and $ids.

• Additive changes keep v1: new optional fields, new extension blocks, new code-list examples, new formats, new warning codes. Files are regenerated in place.
• Breaking changes go to v2: removing or renaming a field, changing a field’s type or meaning, making an optional field required, or narrowing a pattern. *.v2.schema.json is published next to the v1 files, which stay available at their URLs.