feat: Add Japan (JP) tax regime

[miguelsaddress]

Summary

Adds the Japanese tax regime to GOBL, implementing the Consumption Tax (消費税, Shōhi zei) system and Corporate Number (法人番号, Hōjin Bangō) validation.

Note

I am not a tax professional. The tax rates, checksum algorithm, and regulatory details in this PR are based on publicly available sources (listed below). I recommend having someone with Japanese tax expertise verify the data before merging.

What's included

• Consumption Tax with standard (10%) and reduced (8%) rates, effective since October 2019. The previous 8% flat rate (April 2014) is also included.
• Corporate Number validation — 13-digit format with check digit verification using the official NTA algorithm.
• Registration Number normalization — the Qualified Invoice System uses a T prefix on the Corporate Number; normalization strips it so the same underlying number is validated consistently.
• Reverse charge scenario — injects a legal note when the invoice is tagged with reverse-charge, for cross-border B2B services.
• Credit note support — allows credit-note as a correction type (Qualified Return Invoice / 適格返還請求書).
• Three working examples — standard invoice (both tax rates), credit note, and reverse charge, with generated envelope outputs.

Scope decisions

These are deliberate choices to keep this PR focused:

1. Withholding Tax is not included. Japan's withholding tax (源泉徴収, Gensen Chōshū) uses tiered rates: 10.21% up to ¥1,000,000 and 20.42% on the excess. This cannot be expressed with a single RateValueDef.Percent. Other regimes that implement withholding (ES, IT, MX) use flat rates that fit the current model. This could be added in a follow-up if the model is extended to support tiered rates.

2. Only current and previous tax rates. The full history (3% in 1989, 5% in 1997) is omitted. Only the rates relevant for active invoicing are included: 10%/8% since 2019-10-01 and 8% since 2014-04-01.

3. Registration Number normalized to Corporate Number. The Qualified Invoice System assigns Registration Numbers as T + Corporate Number. Since the base number is identical, normalization strips the prefix and validates the underlying 13 digits.

4. Corrections defined inline in jp.go. Only one correction type is needed (credit note), so a separate corrections.go file is not warranted. This follows the UAE regime pattern.

5. Translations limited to EN and JA. Consistent with other regimes (e.g., AE uses EN + AR, GR uses EN + EL).

Verification

• mage lint — passes
• mage test — all 69 packages pass, no regressions
• mage generate — regenerated, no unexpected changes
• go vet ./... — no warnings
• go test ./regimes/jp/... -cover — 91.7% coverage

Sources

Note

Last verified: 2026-03-21 16:00 CET (UTC+1)

• NTA — Consumption Tax overview
• NTA — Corporate Number publication site
• OECD — Japan Consumption Tax Trends (PDF)
• EU-Japan Centre — Qualified Invoice System
• NTA — Cross-border digital services (PDF)

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.
• Updated the CHANGELOG.md with an overview of my changes.
• 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.

[Copilot]

Pull request overview

Adds a new Japan (JP) tax regime to GOBL, including Consumption Tax (standard/reduced) configuration, Corporate Number validation/normalization, and working invoice examples.

Changes:

• Register the new JP regime and generate its regime data + schema enum update.
• Implement JP Consumption Tax category/rates, reverse-charge scenario note, and credit-note correction support.
• Add JP Corporate Number normalization + checksum validation with accompanying tests and examples.

Reviewed changes

Copilot reviewed 12 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
regimes/regimes.go	Registers the JP regime via blank import so it’s available at runtime.
regimes/jp/jp.go	Defines the JP tax.RegimeDef (metadata, categories, scenarios, corrections, validator/normalizer hooks).
regimes/jp/tax_categories.go	Adds Consumption Tax (VAT) category with standard/reduced rates and effective dates.
regimes/jp/scenarios.go	Adds a reverse-charge scenario that injects a legal note when tagged.
regimes/jp/tax_identity.go	Implements normalization (strip separators + T prefix) and Corporate Number checksum validation.
regimes/jp/tax_identity_test.go	Tests normalization and checksum validation behavior.
data/schemas/tax/regime-code.json	Adds JP to the regime code schema enum.
data/regimes/jp.json	Generated JSON representation of the JP regime definition.
examples/jp/*.yaml	Adds JP invoice examples (standard, reverse charge, credit note).
examples/jp/out/*.json	Adds generated envelope outputs for the JP examples.
CHANGELOG.md	Documents the addition of the JP tax regime.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 94.31818% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.06%. Comparing base (191636d) to head (39d6441).
⚠️ Report is 155 commits behind head on main.

Files with missing lines	Patch %	Lines
regimes/jp/tax_identity.go	88.57%	2 Missing and 2 partials ⚠️
regimes/jp/jp.go	98.11%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #768   +/-   ##
=======================================
  Coverage   93.05%   93.06%           
=======================================
  Files         333      335    +2     
  Lines       17806    17894   +88     
=======================================
+ Hits        16570    16653   +83     
- Misses        870      873    +3     
- Partials      366      368    +2     

☔ View full report in Codecov by Sentry.
📢 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.

[samlown]

Thanks for this @miguelsaddress! I'd review the tax category details as I don't think VAT is the right choice here.

We've just made a new major release of GOBL to the new rules based validation, so that would need updating for a final release also.

[samlown]

Are you sure this should be VAT? I'd expect the consumption tax to be more like a sales tax and it might make sense to add a new CT type.

[samlown]

Are you sure this applies here? Does JP support reverse-charge and similar things?