Repository navigation
AE regime updates for PINT AE - #1033
miguelalvarezd wants to merge 27 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## en16931-charge-taxes #1033 +/- ##
=====================================================
Coverage 96.93% 96.94%
=====================================================
Files 336 337 +1
Lines 15412 15456 +44
=====================================================
+ Hits 14940 14984 +44
Misses 471 471
Partials 1 1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
9a524df to
1a6388a
Compare
There was a problem hiding this comment.
🔵 Needs a closer look
The PR encodes jurisdiction-specific UAE TIN/TRN and profit-margin VAT rules with generated data, so legal/source accuracy and end-to-end Peppol interoperability require domain-owner verification beyond static review.
No open issues 🎉
What changed in this PR
Prepares GOBL for UAE Peppol PINT-AE support by adding UAE-specific identity and VAT definitions, tightening tax-number validation, and correcting EN 16931 charge rules.
Changes:
- Adds UAE TIN, Emirates ID, trade licence, and Cabinet Decision identities with validation.
- Adds the UAE
margin-schemeVAT key and representative invoice examples. - Requires taxes on document-level EN 16931 charges and corrects charge and discount BR references.
| File | Description |
|---|---|
| regimes/ae/tax_identity.go | Validates UAE TRNs against TIN format, business-identifier, and Luhn requirements. |
| regimes/ae/tax_identity_test.go | Updates and expands UAE TRN validation tests. |
| regimes/ae/tax_categories.go | Defines the UAE profit margin scheme VAT key. |
| regimes/ae/tax_categories_test.go | Tests margin-scheme registration and tax behavior. |
| regimes/ae/scenarios_test.go | Updates UAE scenario fixtures with valid TRNs. |
| regimes/ae/org_identities.go | Adds UAE organization identity definitions and validation rules. |
| regimes/ae/org_identities_test.go | Tests UAE organization identity definitions and validation. |
| regimes/ae/ae.go | Registers UAE organization identity rules and definitions with the regime. |
| examples/ae/out/invoice-ae-simplified.json | Refreshes generated simplified invoice output with valid TRN data. |
| examples/ae/out/invoice-ae-margin-scheme.json | Adds generated output for a UAE margin-scheme invoice. |
| examples/ae/out/invoice-ae-ae-stnr.json | Refreshes generated standard invoice output with valid TRNs. |
| examples/ae/invoice-ae-simplified.yaml | Updates the simplified invoice source example with valid TRN data. |
| examples/ae/invoice-ae-margin-scheme.yaml | Adds a UAE margin-scheme invoice source example. |
| examples/ae/invoice-ae-ae-stnr.yaml | Updates the standard invoice source example with valid TRNs. |
| data/rules/eu-en16931.json | Regenerates EN 16931 rule metadata with corrected references and charge tax requirements. |
| data/rules/ae.json | Regenerates UAE validation rule metadata. |
| data/regimes/ae.json | Regenerates UAE identity and VAT regime definitions. |
| changes/unreleased/en16931-pint-ae-preparation.md | Documents the UAE and EN 16931 preparation changes. |
| addons/eu/en16931/bill.go | Corrects EN 16931 BR references and requires taxes on document-level charges. |
| addons/eu/en16931/bill_test.go | Updates charge fixtures and tests the new EN 16931 charge requirements. |
Review effort: Lite
Until invopop/gobl#1033 and invopop/gobl.ubl#189 are released, build against their head commits so the tests can run. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
EN 16931 requires a VAT category code on every document-level charge, as it does on allowances (BR-32). Add the matching rule to the eu-en16931-v2017 addon.
The document charge and line allowance reason rules cited BR-36 and BR-41, which are the amount rules. Point them at BR-38 and BR-42. Fault codes are unchanged.
Define identity keys for the Tax Identification Number (ae-tin), trade licence (ae-trade-license), Emirates ID (ae-emirates-id) and Cabinet Decision (ae-cabinet-decision), the commercial registration number types listed in the Ministry of Finance's e-invoice mandatory fields. Check their formats where an official source defines one: - TINs are 10 digits, the first 10 digits of the TRN (GOBL-AE-ORG-IDENTITY-01). - Emirates ID numbers are 15 digits (GOBL-AE-ORG-IDENTITY-02). Separators are removed from both before validation. Trade licence and Cabinet Decision numbers have no national format, so they are not checked.
The TIN is a tax registration, and the trade licence, Emirates ID, passport and Cabinet Decision are the commercial registration numbers the Ministry of Finance lists, so legal registrations. Identities without a scope now get the one their key implies.
Supplies under the UAE profit margin scheme are taxed on the supplier's margin, and the invoice shows no VAT amount. Add the margin-scheme VAT key, without a percent, so such lines carry no VAT.
The scope decides where a converter writes an identity, which is a format concern, and EN 16931 allows one identity per scope. Giving every trade licence, Emirates ID, passport and Cabinet Decision the legal scope made a party with two of them invalid, and changed existing documents with a passport. The AE regime now only removes the separators from TINs and Emirates ID numbers. The PINT addon sets the scopes PINT AE needs. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- Declare charge rule 01 (BR-38) before 02 (BR-37). - Move the breaking BR-37 entry from Added to Changed in the release notes, as it changes how existing documents validate. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The TIN and Emirates ID rules already require plain digits, so separators are rejected instead of removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Federal Tax Authority registered the TIN under ISO 6523 (ICD 0235) as 10 digits: a 1, an 8-digit business identifier that is not all zeros, and a Luhn check digit. The TRN is the TIN followed by 5 digits for the tax, so its first 10 digits follow the same rules. - The tax ID code must be 15 digits that start with a valid TIN. Made-up numbers such as 123456789012345 now fail. - TIN identities are checked the same way. - Emirates ID numbers must start with 784, the international code of the UAE. Their last digit is a verification digit, but its algorithm is not published, so it is not checked. The tests and examples use numbers with a valid check digit. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The TIN, trade licence, Emirates ID and Cabinet Decision become the identity types TIN, TL, EID and CD, as most regimes define theirs, instead of keys. Formats are checked with is.Matches and the check digit separately, so each has its own fault code. Drop the check that a TIN's business identifier is not all zeros: it only rejected one number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
77ca482 to
711d4de
Compare
The Federal Tax Authority never issues a TIN whose 8-digit business identifier, between the leading 1 and the check digit, is all zeros, as in 1000000008, which passes the Luhn check. TINs fail with GOBL-AE-ORG-IDENTITY-04, and TRNs starting with one with GOBL-AE-TAX-IDENTITY-03, after the format and check digit codes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Core GOBL forbids taxes on informative charges, so requiring them (BR-37) made every informative charge fail under EN 16931. Informative charges don't count towards the totals, so BR-37 doesn't apply to them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The PINT AE addon in gobl.peppol checks TINs in the Peppol endpoint and party identifiers with a copy of this pattern. Exporting it as TINPattern lets it reuse the regime's definition. The regime's checks are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Margin scheme lines use the exempt VAT key even though VAT is due on the margin. Say in the tag and regime descriptions that this matches how GOBL classifies margin scheme lines for Italy, Greece and Portugal, so the choice reads as deliberate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The PINT addon checks UAE TRNs outside a tax identity, such as the principal ID of disclosed agent invoices, and needs the same format the regime uses for tax IDs. Exporting it, as the TIN pattern already is, keeps one definition of the TRN in the regime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The PINT addon writes UAE Peppol endpoints and TIN identifications with the ISO 6523 ICD 0235, which the Federal Tax Authority registered for the TIN. Exporting it, as the TIN and TRN patterns already are, keeps one definition of the scheme in the regime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comments on the identity types, patterns and helpers go down to a line or two and say where the rules apply rather than listing them. The regime description drops the margin scheme paragraph and keeps one sentence on e-invoicing, and the margin scheme tag description loses the internal reasoning about the exempt key. Tests that only restated data or gobl's scenario engine are gone; coverage stays at 100%. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔵 Needs a closer look
The core contract is consumed by invopop/gobl.peppol#8, but that implementation and matching default-branch references are absent, so human review must verify the exported AE constants and margin-scheme tag/note interoperability with PINT AE mapping.
No open issues 🎉
Review effort: Lite


Prepares GOBL for Peppol PINT AE (UAE e-invoicing), which invopop/gobl.peppol#8 implements on top of these changes.
Based on invopop/gobl#1040, the EN 16931 rules split out of this PR (BR-37, BR-7, BR-CO-04, and BR-CO-25 removed). This PR doesn't use them in its code: the base is there so that gobl.peppol#8 can pin one commit with everything it needs. Once #1040 is merged, this PR's base becomes
main.ae: identity types for the Tax Identification Number (TIN), trade licence (TL), Emirates ID (EID) and Cabinet Decision (CD), the commercial registration number types in the Ministry of Finance's e-invoice mandatory fields. Except for the TIN, they are the codes PINT AE uses.GOBL-AE-ORG-IDENTITY-01) and end in a Luhn check digit (GOBL-AE-ORG-IDENTITY-02). This is how the Federal Tax Authority registered the TIN under ISO 6523 (ICD 0235); the Peppol participant scheme list has the same text.GOBL-AE-ORG-IDENTITY-03). Their last digit is a verification digit, but its algorithm is not published, so it is not checked.ae: breaking: the tax ID code (TRN) must be 15 digits starting with 1 (GOBL-AE-TAX-IDENTITY-01), and its first 10 digits, the TIN, must end in a Luhn check digit (GOBL-AE-TAX-IDENTITY-02). The Ministry of Finance defines the TIN as "the first 10 digits of the 15-digit TRN" (UAE Electronic Invoice Mandatory Field Requirements, definition 11), so TRNs get the TIN's check digit. Made-up numbers such as123456789012345now fail. The AE tests and examples use numbers with a valid check digit.112345678900003and134567890123003. The PINT AE Schematron only checks the format and the trailing03(IBR-132-AE), not the check digit, so documents copied from those examples pass Peppol validation but fail in GOBL. Use real TRNs, or placeholders with a valid check digit.ae: the TIN and TRN formats and the TIN's ISO 6523 scheme are exported asTINPattern,TRNPatternandTINScheme(0235, also the scheme of UAE Peppol endpoints), so the PINT addon uses them instead of its own copies.ae:margin-schemetag for supplies under the UAE profit margin scheme, with a scenario that adds the statement the invoice must carry ("VAT charged under the Profit Margin Scheme") as a VAT note. Lines use the coreexemptkey, as margin scheme lines do in Italy, Greece and Portugal, so the invoice shows no VAT amount; see Margin scheme: tag plusexempt. Shown in the newinvoice-ae-margin-schemeexample.Margin scheme: tag plus
exemptThe margin scheme uses existing GOBL conventions only:
aeregime'smargin-schemetag. Its scenario adds the statement the FTA requires (VATGPM1; Executive Regulation Art. 29) as a VAT note, the way the ESsecond-hand-goodstag does.exemptkey, with no percent, so GOBL calculates no VAT and the payable is the selling price. IT tickets and PT do the same:exemptplus a code that says why.exemptlines to category N and writes the statement as the N breakdown's exemption reason.Why not a VAT key: a key defined only in a regime fails the published JSON schema, as the VAT
keyenum indata/schemas/tax/combo.jsonis built fromtax.GlobalVATKeys()(tax/combo.go,JSONSchemaExtend), even though GOBL's own validation would accept it. Supporting it would mean changing how GOBL generates its schemas, for what would be the first regime-specific VAT key.Trade-off: in GOBL data the lines say
exempt, while legally the supply is standard-rated on the margin; the tag is what qualifies it. Anything reading GOBL data (reports, VAT return tooling) must identify margin scheme lines by the tag together withexempt, never by the key alone. The regime doesn't reject mixed invoices, as the law allows them; only PINT AE does (IBR-116-AE).Pre-Review Checklist
go generate .to ensure that the Schemas and Regime data are up to date.changes/unreleasedwith an overview of my changes, as described inchanges/README.md.And if you are part of the org:
🤖 Generated with Claude Code