Extension System

Relevant source files

• charges_parse.go
• charges_parse_test.go
• common.go
• invoice_test.go
• lines_parse.go
• lines_parse_test.go
• ordering_parse_test.go
• party_parse_test.go
• test/data/convert/peppol/out/peppol-reverse-charge.xml
• test/data/parse/france-cius/b2b-reg.xml
• totals.go
• utils.go

Purpose and Scope

The extension system provides a mechanism for preserving UBL-specific standardized codes within GOBL data structures during bidirectional conversion. When converting between UBL XML and GOBL JSON formats, many UBL fields use standardized code lists (UNTDID, CEF, ISO) that don't have direct equivalents in GOBL's domain model. Extensions allow these codes to be stored alongside GOBL's semantic fields, ensuring that information is preserved during round-trip conversions.

For information about the core conversion processes, see Conversion System. For details about specific document components that use extensions, see Document Components.

---

Extension Mechanism Overview

Extensions in GOBL are implemented through the tax.Extensions type, which is a map structure (map[cbc.Key]cbc.Code) that stores key-value pairs. Various GOBL entities include an Ext field of this type, allowing arbitrary metadata to be attached without modifying the core GOBL schema.

Extension Storage in GOBL Entities

Sources: payment_parse.go132-135 lines_parse.go161-163 party.go223-225 charges.go47-50

---

Standard Extension Keys

The system uses predefined extension keys from three main catalogues within the GOBL ecosystem. These keys are constants that identify the type of code being stored.

UNTDID Extension Keys

UNTDID (United Nations Trade Data Interchange Directory) provides standardized codes for international trade. The following keys are used:

Extension Key	Purpose	UBL Field	Example Value
untdid.ExtKeyPaymentMeans	Payment method code	PaymentMeansCode	"30" (credit transfer)
untdid.ExtKeyTaxCategory	Tax category classification	ClassifiedTaxCategory/ID	"S" (standard rate)
untdid.ExtKeyCharge	Charge reason code	AllowanceChargeReasonCode	"SAA" (service charge)
untdid.ExtKeyAllowance	Discount/allowance reason code	AllowanceChargeReasonCode	"95" (discount)

Sources: payment_parse.go16-25 lines_parse.go161-163 charges.go47-50 charges.go78-80

CEF Extension Keys

CEF (Core Invoice Vocabulary) codes are defined by the European Union for e-invoicing standards:

Extension Key	Purpose	UBL Field	Example Value
cef.ExtKeyVATEX	VAT exemption reason code	TaxExemptionReasonCode	"VATEX-EU-132" (intra-community supply)

Sources: lines_parse.go167-172

ISO Extension Keys

ISO codes provide international identifiers for various business entities:

Extension Key	Purpose	UBL Field	Example Value
iso.ExtKeySchemeID	Identification scheme code	schemeID attribute	"0088" (GLN), "0184" (DUNS)

Sources: lines_parse.go212-215 party.go223-225 party.go263-264

---

Extension Flow During Conversion

UBL to GOBL: Parsing and Extraction

When parsing UBL documents into GOBL, extension codes are extracted from UBL XML elements and stored in the corresponding GOBL entity's Ext field. This preserves information that would otherwise be lost in the semantic mapping.

Extension Extraction Flow

Sources: payment_parse.go129-155 lines_parse.go149-195 lines_parse.go197-232

Payment Means Code Extraction

Payment means codes are extracted from PaymentMeansCode elements and stored in payment instructions:

payment_parse.go129-135

• Function goblInvoiceInstructions creates payment instructions
• Stores UNTDID payment means code in instructions.Ext[untdid.ExtKeyPaymentMeans]
• Maps code to semantic GOBL key using goblPaymentMeansCode function

Tax Category Code Extraction

Tax category codes are extracted from ClassifiedTaxCategory elements:

lines_parse.go149-175

• Function goblConvertLineItemTaxes processes tax information on line items
• Stores UNTDID category code in line.Taxes[0].Ext[untdid.ExtKeyTaxCategory]
• Stores CEF exemption code in line.Taxes[0].Ext[cef.ExtKeyVATEX] if present

Scheme ID Extraction

Scheme identifiers are extracted from schemeID attributes on various ID elements:

party.go223-225 party.go263-264 party.go353-357

• Extracted from CompanyID, PartyIdentification/ID, and item identifiers
• Stored in identity.Ext[iso.ExtKeySchemeID]
• Preserves the standardized identification scheme used

lines_parse.go209-219

• Extracted from StandardItemIdentification/ID/@schemeID
• Stored in item identity extensions

---

GOBL to UBL: Code Injection

When converting GOBL documents to UBL XML, extension values are retrieved and injected into the appropriate UBL elements. This restores the original standardized codes in the output document.

Extension Injection Flow

Sources: payment.go charges.go36-122 party.go122-272

Payment Means Code Injection

payment.go (referenced but not shown in provided files)

• Retrieves inst.Ext.Get(untdid.ExtKeyPaymentMeans)
• Sets PaymentMeans.PaymentMeansCode.Value

Tax Category Code Injection

charges.go98-122

• Function makeTaxCategory retrieves extension codes
• t.Ext.Get(untdid.ExtKeyTaxCategory) populates TaxCategory.ID
• Ensures proper tax classification in output

Charge/Discount Reason Code Injection

charges.go47-50 charges.go78-80

• ch.Ext.Get(untdid.ExtKeyCharge) populates AllowanceChargeReasonCode for charges
• d.Ext.Get(untdid.ExtKeyAllowance) populates AllowanceChargeReasonCode for discounts
• Preserves business reason codes

Scheme ID Injection

party.go223-225 party.go263-264 party.go353-357 party.go386-389

• Retrieved from id.Ext[iso.ExtKeySchemeID]
• Sets schemeID attribute on ID elements
• Applied to party identifiers, legal entity IDs, and payee identifications

---

Code-Level Implementation Patterns

Reading Extensions from GOBL

The standard pattern for reading extension values uses the Get method or direct map access:

Examples in Codebase:

• charges.go47-50 - Reading charge reason code
• charges.go78-80 - Reading allowance reason code
• charges.go104-107 - Reading tax category code
• party.go223-225 - Reading scheme ID from party identity

Writing Extensions to GOBL

The standard pattern for writing extension values creates the Extensions map if needed and assigns the code:

Examples in Codebase:

• payment_parse.go132-135 - Setting payment means code inline
• lines_parse.go161-163 - Setting tax category code inline
• lines_parse.go212-215 - Setting scheme ID for item identity

---

Extension Usage by Document Component

Payment Instructions Extensions

Payment instructions use extensions to preserve UNTDID payment means codes:

Extension Structure

Sources: payment_parse.go129-155 payment_parse.go16-25

The Key field stores a semantic identifier (e.g., pay.MeansKeyCreditTransfer), while the extension preserves the original UNTDID code ("30"). This allows round-trip conversion without information loss.

Tax Category Extensions

Tax categories on line items use two types of extensions:

Extension Structure

Sources: lines_parse.go149-195

The Category field identifies the tax scheme (e.g., "VAT"), while extensions store the specific UNTDID category code and CEF exemption reason code. This allows proper reconstruction of complex tax scenarios.

Charge and Discount Extensions

Charges and discounts use extensions to preserve business reason codes:

Extension Structure

Sources: charges.go47-50 charges.go78-80 charges.go104-107

The Reason field contains a human-readable explanation, while the extension preserves the standardized UNTDID code for machine processing.

Party Identity Extensions

Party and item identities use extensions to preserve identification scheme codes:

Extension Structure

Sources: lines_parse.go209-219 party.go223-225 party.go263-264 party.go353-357

The extension stores the ISO 6523 ICD (International Code Designator) which identifies the numbering scheme used for the identifier.

---

Round-Trip Preservation

The extension system ensures that UBL documents can be parsed to GOBL and converted back to UBL without losing standardized codes:

Round-Trip Data Flow

Sources: ubl.go47-88 (Parse), ubl.go90-120 (Convert), payment_parse.go129-155 lines_parse.go149-195 charges.go47-50 party.go223-225

---

Extension Key Reference Table

This table summarizes all extension keys used in the codebase with their corresponding UBL fields and usage contexts:

Extension Key	Catalogue	UBL Element Path	GOBL Entity	Conversion Direction	Example Value
untdid.ExtKeyPaymentMeans	UNTDID 4461	PaymentMeans/PaymentMeansCode	pay.Instructions	Both	"30", "48", "49"
untdid.ExtKeyTaxCategory	UNTDID 5305	ClassifiedTaxCategory/ID	tax.Combo	Both	"S", "E", "AE"
untdid.ExtKeyCharge	UNTDID 7161	AllowanceCharge/AllowanceChargeReasonCode	bill.Charge	Both	"SAA", "FC"
untdid.ExtKeyAllowance	UNTDID 5189	AllowanceCharge/AllowanceChargeReasonCode	bill.Discount	Both	"95", "100"
cef.ExtKeyVATEX	CEF	TaxCategory/TaxExemptionReasonCode	tax.Combo	Both	"VATEX-EU-132"
iso.ExtKeySchemeID	ISO 6523	ID/@schemeID	org.Identity	Both	"0088", "0184"

Sources: payment_parse.go16-25 lines_parse.go7-14 party.go1-10 charges.go1-8

---

Best Practices

When Parsing UBL to GOBL

1. Always store standardized codes in extensions when the UBL element uses a code list
2. Check for nil extensions before accessing: if entity.Ext != nil { ... }
3. Initialize extension maps during entity creation: Ext: tax.Extensions{}
4. Prefer inline initialization when creating entities with known extension values

When Converting GOBL to UBL

1. Use Get() method for safe extension access: entity.Ext.Get(key).String()
2. Check for empty strings after retrieval: if code != "" { ... }
3. Provide fallback behavior when extension is missing (use semantic field or default value)
4. Preserve extension data even if semantic fields are also populated

General Guidelines

1. Document extension usage in conversion functions with comments indicating which standard is being used
2. Use catalogue constants (untdid.ExtKeyX, cef.ExtKeyX, iso.ExtKeyX) rather than string literals
3. Test round-trip conversions to ensure extensions are properly preserved
4. Keep extensions synchronized with semantic fields when both represent the same concept

Sources: payment_parse.go129-155 lines_parse.go149-195 charges.go36-122 party.go122-272