Skip to content

AE regime updates for PINT AE - #1033

Open
miguelalvarezd wants to merge 27 commits into
en16931-charge-taxesfrom
en16931-pint-ae-preparation
Open

miguelalvarezd wants to merge 27 commits into
en16931-charge-taxesfrom
en16931-pint-ae-preparation

Conversation

@miguelalvarezd

@miguelalvarezd miguelalvarezd commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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.
    • TINs must be 10 digits starting with 1 (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.
    • Emirates ID numbers must be 15 digits starting with 784 (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 as 123456789012345 now fail. The AE tests and examples use numbers with a valid check digit.
    • The official PINT AE example invoices use placeholder TRNs that fail this check, such as 112345678900003 and 134567890123003. The PINT AE Schematron only checks the format and the trailing 03 (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 as TINPattern, TRNPattern and TINScheme (0235, also the scheme of UAE Peppol endpoints), so the PINT addon uses them instead of its own copies.
  • ae: margin-scheme tag 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 core exempt key, as margin scheme lines do in Italy, Greece and Portugal, so the invoice shows no VAT amount; see Margin scheme: tag plus exempt. Shown in the new invoice-ae-margin-scheme example.

Margin scheme: tag plus exempt

The margin scheme uses existing GOBL conventions only:

  • Document: the ae regime's margin-scheme tag. Its scenario adds the statement the FTA requires (VATGPM1; Executive Regulation Art. 29) as a VAT note, the way the ES second-hand-goods tag does.
  • Lines: the core exempt key, with no percent, so GOBL calculates no VAT and the payable is the selling price. IT tickets and PT do the same: exempt plus a code that says why.
  • PINT AE (gobl.peppol): with the tag, the addon maps exempt lines 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 key enum in data/schemas/tax/combo.json is built from tax.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 with exempt, 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

  • Opened this PR as a draft
  • Read the CONTRIBUTING.md guide.
  • Performed a self-review of my code.
  • Added thorough tests with at least 90% code coverage.
  • Modified or created example GOBL documents to show my changes in use, if appropriate.
  • Added links to the source of the changes in tax regimes or addons, either structured or in the comments.
  • Run go generate . to ensure that the Schemas and Regime data are up to date.
  • Reviewed and fixed all linter warnings.
  • Been obsessive with pointer nil checks to avoid panics.
  • Added a file to changes/unreleased with an overview of my changes, as described in changes/README.md.
  • Marked this PR as ready for review.

And if you are part of the org:

  • Requested a review from Copilot and fixed or dismissed (with a reason) all the feedback raised.
  • Requested a review from @samlown.

🤖 Generated with Claude Code

@codecov

codecov Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.94%. Comparing base (ac3a867) to head (a26856f).

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@miguelalvarezd
miguelalvarezd force-pushed the en16931-pint-ae-preparation branch from 9a524df to 1a6388a Compare November 12, 2026 10:44
@miguelalvarezd
miguelalvarezd marked this pull request as ready for review November 12, 2026 19:20
Copilot AI lite review requested due to automatic review settings November 12, 2026 19:20

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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-scheme VAT 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

miguelalvarezd added a commit to invopop/gobl.peppol that referenced this pull request Nov 16, 2026
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>
Copilot AI lite review requested due to automatic review settings November 16, 2026 16:23

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The identifier validation still accepts the prohibited all-zero business identifier because it checks only the Luhn digit, leaving an active moderate-severity issue.

1 open issue

Review effort: Lite

Comment thread regimes/ae/tax_identity.go Resolved
miguelalvarezd and others added 10 commits November 16, 2026 16:39
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>
@miguelalvarezd
miguelalvarezd force-pushed the en16931-pint-ae-preparation branch from 77ca482 to 711d4de Compare November 16, 2026 16:40
Copilot AI lite review requested due to automatic review settings November 16, 2026 16:40
@miguelalvarezd miguelalvarezd mentioned this pull request Nov 16, 2026
12 of 13 tasks
@miguelalvarezd
miguelalvarezd changed the base branch from main to address-street-third November 16, 2026 16:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two critical issues remain: BR-37 conflicts with the existing informative-charge tax restriction, and the AE margin-scheme key is missing from the generated tax combo schema.

3 open issues

Review effort: Lite

Comment thread addons/eu/en16931/bill.go Resolved
Comment thread regimes/ae/tax_categories.go Resolved
miguelalvarezd and others added 2 commits November 16, 2026 17:06
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>
@miguelalvarezd miguelalvarezd changed the title EN16931 preparation for PINT-AE AE regime and EN 16931 updates for PINT AE Nov 17, 2026
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@miguelalvarezd
miguelalvarezd changed the base branch from address-street-third to en16931-charge-taxes November 17, 2026 16:16
Copilot AI lite review requested due to automatic review settings November 17, 2026 16:16
@miguelalvarezd miguelalvarezd changed the title AE regime and EN 16931 updates for PINT AE AE regime updates for PINT AE Nov 17, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The validation still accepts the prohibited all-zero business identifier, allowing invalid organization TINs and tax TRNs through without the required rejection and regression coverage.

1 open issue

Review effort: Lite

Comment thread regimes/ae/tax_identity.go Resolved
Copilot AI lite review requested due to automatic review settings November 17, 2026 16:24

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The validation still accepts the prohibited all-zero business-identifier value for both TIN and TRN, so the predicate and regression coverage must be corrected.

1 open issue

Review effort: Lite

miguelalvarezd and others added 5 commits November 18, 2026 14:33
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>
Copilot AI lite review requested due to automatic review settings November 18, 2026 19:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported, and the change includes corresponding validation, scenario, identity, example, generated-data, and test updates.

No open issues 🎉

1 resolved since last review

Review effort: Lite

@miguelalvarezd
miguelalvarezd removed this pull request from stack #1041 November 18, 2026 19:48
miguelalvarezd and others added 2 commits November 19, 2026 13:07
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>
Copilot AI lite review requested due to automatic review settings November 19, 2026 15:05

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants