Overview

Relevant source files

• LICENSE
• README.md
• invoice.go
• ubl.go

Purpose and Scope

The gobl.ubl repository is a Go library that provides bidirectional conversion between GOBL JSON format and UBL XML format for electronic invoices. This document provides a high-level overview of the library's architecture, core concepts, and primary components.

For installation and basic usage examples, see Getting Started. For detailed information about the conversion pipelines, see Conversion System. For component-specific details, see Document Components.

What is GOBL.UBL?

The gobl.ubl package serves as a bridge between two invoice representation formats:

Format	Description	Use Case
GOBL	JSON-based invoice format from github.com/invopop/gobl	Internal processing, business logic, multi-regime support
UBL	XML-based Universal Business Language 2.1 standard	European e-invoicing compliance, B2B interchange

The library enables conversion in both directions, allowing systems to process invoices using GOBL's rich semantic model while exchanging them using UBL's standardized XML format.

Sources: README.md1-11 ubl.go1-2

Core Architecture

The library is structured around three main operations, exposed through a minimal public API:

Diagram: Core API and Conversion Flow - This diagram shows the primary entry points and how they connect to internal conversion pipelines. The Parse() function handles UBL→GOBL, while Convert() and ConvertInvoice() handle GOBL→UBL.

Sources: ubl.go30-120 invoice.go101-194 invoice.go203-215

Bidirectional Conversion Support

GOBL to UBL Direction

The conversion from GOBL to UBL follows this pipeline:

Diagram: GOBL to UBL Conversion Pipeline - The conversion begins with addon validation, removes tax-inclusive pricing (unsupported in UBL), then delegates to component converters.

Sources: ubl.go90-120 invoice.go101-194 ubl.go122-148

UBL to GOBL Direction

The parsing from UBL to GOBL follows this pipeline:

Diagram: UBL to GOBL Parsing Pipeline - Parsing begins with namespace detection, unmarshals to Go structs, detects the UBL profile, then delegates to component parsers.

Sources: ubl.go47-88 ubl.go150-166 invoice_parse.go18-110

Package Organization

The codebase is organized into functional modules:

File Pattern	Purpose	Key Entities
ubl.go	Public API and main conversion logic	Parse(), Convert(), ConvertInvoice(), Bytes()
invoice.go	Invoice struct and GOBL→UBL conversion	Invoice, ublInvoice(), ConvertInvoice()
invoice_parse.go	UBL→GOBL parsing	Invoice.Convert(), component parsers
context.go	Profile and standard definitions	Context, ContextEN16931, ContextPeppol, etc.
party.go	Party conversion GOBL→UBL	newParty(), newDeliveryParty(), newPayeeParty()
party_parse.go	Party parsing UBL→GOBL	goblParty()
lines.go	Line items conversion GOBL→UBL	addLines()
lines_parse.go	Line items parsing UBL→GOBL	goblAddLines()
payment.go	Payment conversion GOBL→UBL	addPayment()
payment_parse.go	Payment parsing UBL→GOBL	goblAddPayment()
charges.go	Charges/discounts conversion GOBL→UBL	addCharges()
charges_parse.go	Charges/discounts parsing UBL→GOBL	goblAddCharges()
totals.go	Totals and taxes conversion GOBL→UBL	addTotals()
totals_parse.go	Totals and taxes parsing UBL→GOBL	buildTaxCategoryMap()
ordering.go	Ordering references conversion GOBL→UBL	addOrdering()
ordering_parse.go	Ordering references parsing UBL→GOBL	goblAddOrdering()
attachments.go	Attachments conversion GOBL→UBL	addAttachments()
attachments_parse.go	Attachments parsing UBL→GOBL	goblAddAttachments(), ExtractBinaryAttachments()
delivery.go	Delivery information conversion GOBL→UBL	newDelivery()
delivery_parse.go	Delivery information parsing UBL→GOBL	goblAddDelivery()

Sources: ubl.go1-177 invoice.go1-216 invoice_parse.go1-110

Context System for Multiple Standards

The library supports multiple European e-invoicing standards through a context system. Each context defines:

• CustomizationID: Identifies the business rules applied
• ProfileID: Identifies the process specification
• Required Addons: GOBL addons needed for compliance
• VESID: Validation artifact ID for external validators

Diagram: Context System Architecture - The context system allows the same GOBL invoice to generate different UBL variants by specifying the target standard.

Sources: context.go1-150 README.md58-62

Key Features

1. Automatic Document Type Detection

The Parse() function automatically detects whether the input XML is an Invoice or CreditNote by examining the root namespace:

• urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 → Invoice
• urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2 → CreditNote

Both document types are represented using the same Invoice struct, with the document type indicated by which fields are populated (InvoiceTypeCode vs CreditNoteTypeCode).

Sources: ubl.go47-88 invoice.go16-20 invoice.go28-99

2. Component-Based Architecture

Both conversion directions use a modular architecture where specialized functions handle different invoice components:

Component	GOBL→UBL Function	UBL→GOBL Function
Parties	newParty()	goblParty()
Line Items	addLines()	goblAddLines()
Charges/Discounts	addCharges()	goblAddCharges()
Payment	addPayment()	goblAddPayment()
Totals/Taxes	addTotals()	Tax data extracted inline
Ordering	addOrdering()	goblAddOrdering()
Attachments	addAttachments()	goblAddAttachments()
Delivery	newDelivery()	goblAddDelivery()

This separation allows each component to evolve independently. For details on each component, see Document Components.

Sources: invoice.go101-194 invoice_parse.go18-110

3. Pre-processing and Validation

Before conversion, the library performs validation and normalization:

GOBL→UBL Pre-processing:

• Validates required addons are present via ensureAddons() ubl.go122-148
• Removes tax-inclusive pricing via RemoveIncludedTaxes() because UBL only supports tax-exclusive amounts ubl.go112-114
• Calculates and validates the invoice after adding missing addons ubl.go141-146

UBL→GOBL Pre-processing:

• Builds a tax category map using buildTaxCategoryMap() to distribute exemption codes to lines and charges totals_parse.go
• Detects the UBL profile using FindContext() for proper semantic interpretation context.go

Sources: ubl.go106-114 ubl.go122-148

4. Binary Attachment Handling

Binary attachments embedded in UBL documents are handled separately from the main conversion flow:

• The Invoice.ExtractBinaryAttachments() method attachments_parse.go extracts embedded binary objects
• During GOBL→UBL conversion, attachments can be embedded as base64-encoded binary objects attachments.go
• This separation allows large embedded documents to be processed independently of the main invoice structure

For detailed attachment handling, see Attachments.

Sources: README.md101-102 attachments.go attachments_parse.go

CLI Tool

The library includes a command-line tool installed via:

The tool automatically detects input format and performs the appropriate conversion:

For CLI usage details, see CLI Tool.

Sources: README.md112-129

Standards Compliance

The library implements mappings defined in the EN 16931 standard for European e-invoicing:

• EN 16931-1: Semantic data model defining invoice structure
• EN 16931-3-2: UBL 2.1 syntax binding specification
• UBL 2.1: OASIS Universal Business Language specification
• Peppol BIS Billing 3.0: Pan-European e-invoicing framework
• XRechnung: German e-invoicing standard
• Chorus Pro/France CIUS: French e-invoicing requirements

The Version constant ubl.go26-28 indicates this library generates UBL 2.1 documents.

Sources: README.md152-157 ubl.go26-28

Known Limitations

Certain UBL features are lost during UBL→GOBL conversion due to semantic differences:

1. ProfileID and CustomizationID: Not preserved in GOBL structure (used only for context detection)
2. Multiple Invoice Periods: GOBL supports only one period; additional UBL periods are discarded
3. AccountingCost fields: Converted to notes rather than structured data
4. Embedded Additional Documents: Not supported in GOBL's current attachment model
5. Payment Advance Tax Rates: Use the global invoice tax rate rather than advance-specific rates

For a complete list of limitations and workarounds, see Known Limitations.

Sources: README.md141-149

Next Steps

• For installation and basic usage: Getting Started
• For detailed conversion mechanics: Conversion System
• For component-specific mappings: Document Components
• For GOBL/UBL format details: Document Formats
• For testing and examples: Examples and Testing