DEKRA 1.0 — structure and rules

Normative companion to STANDARD.md. Everything here is enforced by App\Services\Dekra\DekraValidatorService; every rule names the code the validator reports, so a finding in the console can be traced straight back to a line in this document.

The machine-readable form of this document is dekra-1.0.schema.json, generated from the same constants the validator enforces. It carries shape, presence and enumerated values. It cannot carry the arithmetic cross-checks or the signatures — a file that satisfies the schema is well-formed, and only the validator can say it is valid.

Conventions used below:

• required — the key must be present. A key whose value may be null is still required to be present: absent keys are an error, null values are not. This is what keeps every document the same shape regardless of type, and what lets null mean "the document does not say" instead of being indistinguishable from "nobody wrote this field".
• decimal — an exact decimal string ("12.10"), never a JSON number. See §10.
• money — a decimal string with exactly as many places as the currency's ISO 4217 minor unit.
• percent — a decimal string, 2 places, 0.00…100.00.
• Levels: E = error (file invalid), W = warning (file valid, data suspicious).

Closed value lists live in registry/ and are named per field below.

1. Container (root object)#

Any other top-level key: W key.unknown. Readers must ignore unknown keys, never fail on them.

Whole-file failures: E file.unreadable, E json.invalid, E json.not_object.

2. Document (documents[i])#

Any other key inside a document: W key.unknown.

2.1 Document types#

invoice, credit_note, debit_note, corrective_invoice, self_billed_invoice, proforma, receipt, contract, waybill, other.

A credit note is a type, not a subtype. As free text no consumer could tell a refund from a charge, so every sum over an archive was too high by the value of its returns.

Amounts are always positive. Direction is carried by the type: a consumer summing an archive negates credit_note (DekraRegistry::CREDIT_TYPES) and nothing else. A sign convention is the fastest way to get two implementations disagreeing about a refund. The rule binds the producer; the validator does not check the sign of an amount outside payment (§7.4), so a negative figure elsewhere is a wrong file that still validates.

2.2 What a document never describes#

No field describes the archive holding the document, or the software that wrote the file. One invoice is incoming to the buyer and outgoing to the seller, and it arrives on a different day in each of their archives: a field carrying either would make the same signed bytes assert two different things depending on who opened the file. Which side of a transaction you are on is answered by comparing issuer and recipient with your own identity — a question only the holder can answer. Likewise a producer's own record number: it means something in exactly one database and carries out how many records that database holds.

3. Party (issuer, recipient)#

The same key set for both sides and both directions — this is the rule that lets a reader treat invoices and receipts identically.

Codes: E party.missing, E party.key_missing, E party.type, E party.type_bool, E party.country_invalid, E party.bank_missing, E party.bank_key_missing, E party.bank_type, E address_parts.type, E address_parts.key_missing, E address_parts.type_field, E identifiers.missing, W party.name_missing, W party.country_missing, W party.email_invalid, W party.endpoint_scheme_missing, W party.endpoint_scheme_invalid.

country is never inferred. Not from the address text, not from the document's language, not from the producer's own location. Without it a consumer cannot decide which tax rules the document falls under, and a guessed country decides them wrongly while looking exactly as confident as a read one. subdivision is not decoration either: in the United States, Canada, Brazil and India the rate is decided by the subdivision rather than the country.

3.1 Identifiers (identifiers[k])#

Codes: E identifiers.missing, E identifier.not_object, E identifier.key_missing, E identifier.type, E identifier.scheme_malformed, W identifier.scheme_unknown.

Why a list and not two fields. registration_number plus vat_number is a European company's paperwork written into a format that claims to be international: it holds no EIN, no TIN, no GSTIN, no ABN, no CNPJ, no UEN, no CUIT, and no company that has three at once. And an unqualified string says nothing about whose register it came from — short numbers collide across countries, and a consumer matching one against its own database is matching two different things.

A scheme outside registry/identifier-schemes.json is a warning, not an error: there are more registers in the world than in that list, and refusing a document because a country is missing from it would be exactly the provincialism the qualifier exists to remove. The shape is still required.

Empty strings are not allowed as "unknown". A producer must emit null. The validator enforces this on identifiers[].scheme and value (E identifier.type) and reports an empty name (W party.name_missing); an empty string in any other party field passes the type check and is simply a wrong file.

Neither party may be inferred. Both blocks describe what the source document says. A producer that fills recipient from whoever happens to be filing the document is writing a claim the paper does not make into a signed record — and a cash receipt names no buyer at all, so "not stated" has to be representable. An all-null party block is the correct output in that case.

4. References (references[k])#

Codes: E references.missing, E reference.not_object, E reference.key_missing, E reference.number_required, E reference.type_unknown, E reference.date_format, E reference.signature_malformed, W references.correction_unlinked.

A credit_note, debit_note or corrective_invoice with no reference of type corrects or replaces gets W references.correction_unlinked: the receiver can book the amount and can tie it to nothing.

signature is the strongest field in this block. A number can be reused, reissued or typed wrongly; a signature pins the reference to one exact prior version. With it, a chain of corrections is verifiable by anyone holding the documents, without access to the issuer's database — which is what an archive needs and what a bare document number cannot give.

5. Item (items[j])#

Codes: E item.not_object, E item.key_missing, E item.type, E item.unit_code, E key.missing_number, E key.not_decimal, E key.scale, E percent.range, W item.description_empty, W item.total_mismatch, W item.unit_unknown, W key.unknown.

item.total_mismatch is a warning, tolerance ±0.02: sources round differently, and an incoming document's lines come from a parser. The total semantics above are nevertheless normative — a producer that puts a tax-inclusive figure there is producing a wrong file, and the warning is how it shows up.

Why the unit is a code. A document prints gab., vnt., tk, шт or pcs and means the same thing every time; stored as printed, that fact is available to a human reader and to nobody else — quantities cannot be summed across two documents, and a billing message cannot be produced without guessing. So the code is normative and a readable word is kept beside it: the document's own where it printed one, because a producer does not get to overwrite what the paper said. A malformed unit is an error; a well-formed code outside a reader's table is a warning, since Rec 20 has some 1800 codes and no implementation carries all of them. unit_name is checked for type only — a producer that repeats the code there is not caught, only wrong.

comment is a note, not data. It is where a person writes what the paper does not say — why a quantity looks wrong, which order it belongs to, that the price was agreed by phone. Free text, no rule beyond its type, and a reader must not parse it. Like the document's own comment it is outside the signature (STANDARD §4), so a filed document can be annotated without becoming unverifiable.

5.1 Tax (items[j].taxes[t])#

Codes: E taxes.missing, E tax.not_object, E tax.key_missing, E tax.type_unknown, E tax.category_unknown, E tax.zero_category_rate, E tax.jurisdiction_invalid, E tax.type_field, W tax.exemption_unexplained.

Why an array. One rate per line is a European assumption. A Canadian line carries GST and a provincial tax at once; a Brazilian line carries ICMS, IPI, PIS and COFINS with different bases; a United States line carries state, county and city rates that are not a VAT at all and are not recoverable by the buyer. A single rate field cannot express any of them, and a format that requires one is a European format wearing an international name.

A category meaning "no tax is due" (Z, E, AE, K, G, O) with a rate above zero asserts two opposite things at once: E tax.zero_category_rate. A category of E, AE or O with neither exemption_reason nor exemption_code gets W tax.exemption_unexplained — a tax authority asks for the provision, and a receiver cannot invent it.

6. Allowances and charges (allowances_charges[c])#

Codes: E allowances_charges.missing, E charge.not_object, E charge.key_missing, E charge.type_bool, E charge.type_field, E key.not_decimal, E key.scale, W charge.reason_unknown.

Delivery, packing and insurance are not goods. While they had to be written as line items they distorted both the item list and the tax base, and an absolute discount had to be converted into a percentage, losing what was printed. An unlisted reason is stated in reason with a null reason_code rather than forced into the nearest match.

7. Totals, dates, payment, fiscal, source#

7.1 Totals (totals)#

Two cross-checks:

• E totals.mismatch — |total_without_tax + total_tax − total_amount| > 0.01. Pure self-consistency, independent of any source convention, therefore an error.
• W totals.items_mismatch — the line nets after the document discount disagree with total_without_tax by more than 0.02. A warning: rounding and discount conventions legitimately differ between sources.

tax_currency set with no exchange_rate → W totals.exchange_rate_missing. An amount in another currency with no rate is a claim nobody can check and nobody can reproduce.

Other codes: E totals.missing, E totals.key_missing, E totals.currency, E totals.tax_currency, E totals.exchange_rate_date, E key.missing_number, E key.not_decimal, E key.scale, E percent.range. The currency is read first: it sets the scale every money field in the document is checked against, and a document with no readable currency is checked at 2 places.

7.2 Tax breakdown (totals.tax_breakdown[b])#

{ type, category, rate, jurisdiction, taxable_amount, tax_amount } — the same vocabulary as §5.1.

The rows must sum to total_tax within 0.01, or E tax_breakdown.mismatch. A document with tax and an empty breakdown is E tax_breakdown.empty. Each row's type, category and rate are checked with the §5.1 rules and codes; the block's own are E tax_breakdown.missing, E tax_breakdown.not_object, E tax_breakdown.key_missing. The sum is only compared when every row parsed — a row with an unreadable amount produces its own error, not a second one for the total.

This is what a tax return is filed from. A document with lines at 21 % and 12 % cannot state its base per rate with a single total: it cannot be filed, cannot be checked, and cannot be converted to a billing message without the reader re-deriving the split and hoping it matches.

Where a producer cannot honestly decompose the tax — no lines, or lines whose rates do not explain the printed total — it emits one row at the effective rate covering the whole base. That keeps the rate and the amount agreeing with each other and with the totals. Bending one group's amount to close the gap would leave a row whose rate contradicts its own figure.

7.3 Dates (dates)#

Dates are calendar dates without a time zone. Anything with a time in it is E dates.format. Codes: E dates.missing, E dates.key_missing, E dates.format, E dates.invoice_date_required, E dates.period_reversed, W dates.due_before_invoice.

tax_point_date is separate because in most tax regimes it is legally distinct from the date the document was written, and it is the one that decides which period the document is filed in.

Both dates are dates printed on the document. When a copy arrived somewhere is not one: two archives holding the same invoice disagree about that and both are right.

7.4 Payment (payment)#

Payment state is deliberately outside the signature — a document that gets paid must not become "corrupt".

{ method, status, paid_amount, remaining_amount }. method and status are free text as stored by the source, not code lists. Amounts are money, ≥ 0 — the one place the validator checks a sign (E payment.negative). paid_amount exceeding total_amount by more than 0.01 → W payment.overpaid.

Codes: E payment.missing, E payment.key_missing, E payment.type, E payment.negative, E key.missing_number, E key.not_decimal, E key.scale, W payment.overpaid.

7.5 Fiscal (fiscal)#

null when the document is not fiscal. Otherwise:

Codes: E fiscal.type, E fiscal.key_missing, E fiscal.type_field, E fiscal.scheme_unknown, E fiscal.empty, E fiscal.issued_at_format.

A scheme naming neither an id nor a qr names nothing: E fiscal.empty.

This block is inside the signature, and nothing in it is normalised. It is the only part of a DEKRA body that is not the producer's reading of paper but another party's claim about the document — and it is the only thing that lets a holder prove the document against the authority that issued the identifier. A "tidied up" Portuguese QR payload or a reformatted Brazilian access key no longer verifies against the issuer, which destroys the one property that makes a stored document evidence rather than a transcript.

7.6 Source document (source_document)#

null, or { hash_algorithm, hash, media_type, byte_size, filename } — every key present, byte_size an integer or null, the rest a string or null. hash is lowercase hex, 32–128 characters.

Codes: E source_document.type, E source_document.key_missing, E source_document.type_field, E source_document.algorithm_missing, E source_document.hash_malformed.

Not an attachment — DEKRA carries data, not scans. But without the fingerprint the .dkr record and the file it was read from are two unrelated objects that happen to share a folder, and an archive cannot show that one came from the other. A hash with no algorithm named is not verifiable: E source_document.algorithm_missing.

8. Signature profiles#

The profile is written into the file rather than left for a reader to infer from the algorithm, because the difference between "this file is intact" and "this file came from them" is the whole question a signature is asked, and a reader that guesses wrong guesses in the dangerous direction.

key_id names the key so a compromised one can be retired without invalidating everything signed before it. A retired public key stays published for as long as files signed with it must verify.

9. Conformance profiles#

A collection is only as strong as its weakest document. A batch claiming fiscal with one document inside carrying nothing from an authority would be exactly the false assurance the profiles exist to prevent.

10. Numbers#

Money and quantities are decimal strings, never JSON numbers.

A JSON number is an IEEE-754 double: it cannot represent 0.10 exactly. A format whose entire purpose is proving an amount did not change cannot store that amount in a type that changes it. The danger is not theoretical — it appears the first time an implementation in another language parses and re-serialises a file, and it appears as a signature that no longer verifies.

Scale comes from the currency, not from a constant. "Two decimal places" is a statement about the euro: JPY and KRW have no minor unit, KWD, BHD, OMR and TND have three. A money field must carry exactly the number of places ISO 4217 gives its currency — E key.scale otherwise, in both directions. Quantities carry 4 places, unit prices 4, percentages 2.

Rounding is half-up, applied at the scale of the field being written. The rule is stated because without it two implementations differ by a cent and the signature stops matching for a reason neither can see.

11. Rules a producer must follow#

1. Emit every key, using null for unknown — never omit and never use "".
2. items[].total is net, pre-document-discount. Getting this wrong is the single most common way to produce a file that validates as "warnings only" but means something else. The second is a negative amount: outside payment the validator does not check the sign, so a refund written as -100.00 instead of as a credit_note produces a file that validates and sums wrongly.
3. Sign after building, never edit a signed field afterwards. The exceptions are payment, generated_at, the comments and extensions, which are outside both signatures by design.
4. Make the breakdown add up. A file whose tax_breakdown does not sum to total_tax cannot be filed by its receiver.
5. Never infer a country, a recipient or an electronic address. All three look exactly as confident when guessed as when read.
6. One file, one collection signature. Concatenating two .dkr files is not a valid file.
7. Cap at 1000 documents in the container form; larger batches use the streaming form (STANDARD §6), which carries the same two signature levels without holding the batch in memory.

12. Extensions#

extensions is an object whose keys are reverse-DNS namespaces (^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z0-9-]+)+$ — pl.gov.ksef, br.gov.nfe). It exists at the container level and per document.

Without namespaces, "a reader ignores unknown keys" means that sooner or later Poland and Brazil add their own field and name it the same thing. With them a collision is impossible.

Extensions are outside both signatures. An unknown key must never be a reason a file fails to verify — that is the whole point of the ignore-unknown-keys rule, and signing extension content would quietly reverse it.

Codes: E extensions.type, E extensions.namespace.

13. Rules a reader must follow#

1. Reject an unknown MAJOR version. Accept an unknown MINOR — it only adds keys that may be null.
2. Ignore unknown keys. They are a warning at most, never a reason to refuse a file.
3. Verify both signature levels before trusting anything, and check signature_profile: a local signature is a corruption check and proves nothing about who produced the file.
4. Read the profile before the content. If you need fiscal and the file says billing, refuse at the door.
5. Treat the codes as authoritative. The format carries no display text: translate the codes.
6. Do not parse the comments. Free text written by a person, in whatever language they used.
7. Do not infer accounting treatment. DEKRA carries no ledger account; book the document under your own rules.