Technical & Standards
Designing a JSON Invoice Schema for Reliable Format Mapping
Treat JSON as an internal model, not a universal e-invoice
An application can use JSON as its canonical internal representation for seller, buyer, invoice identifiers, dates, currency, lines, tax categories, totals, payment terms and references. This can make validation and user interfaces easier. But a JSON object called “invoice” is not automatically interchangeable with a UBL, CII or country-specific e-invoice. Required syntax bindings and profile rules determine how each business term is represented and constrained.
The European eInvoicing standard defines a semantic core model and syntax bindings for UBL 2.1 and UN/CEFACT CII. If your internal model omits a mandatory term—or collapses multiple tax breakdowns into one field—export can be lossy even if the JSON parses.
Design safeguards
- Version the schema and document all field meaning, datatype, cardinality and units.
- Preserve original source values and references alongside normalized values.
- Represent currency, tax category, tax rate, unit, rounding and allowances explicitly.
- Keep unknown source fields when safe instead of silently discarding them.
- Validate business semantics before mapping into a selected target profile.
- Record export warnings when fields cannot be represented.
- Test round-trips with real sample documents and authoritative validators.
InvoiceConvertor’s JSON export is a generic browser data representation. It is not a certified EN 16931 JSON syntax or tax-authority payload.
Standards sources
- European Commission eInvoicing standard documentation
- OASIS UBL 2.1 specification
- UNECE UN/CEFACT Cross Industry Invoice
Frequently asked questions
Is there one universal JSON invoice standard accepted by tax systems?
No. JSON may be an internal format, while recipients and authorities can require a specific XML syntax, profile and submission process.
Can I convert JSON to UBL by renaming fields?
No. A correct conversion requires semantic mapping, required terms, code lists and profile validation.