Getting Started

Relevant source files

• LICENSE
• README.md
• examples_test.go
• go.mod
• go.sum
• ordering_test.go
• party_test.go

This page provides quick start instructions for using the gobl.ubl library to convert between GOBL JSON and UBL XML formats. It covers installation, basic conversion patterns in both directions, and command-line tool usage.

For detailed information about the conversion system architecture, see Conversion System. For information about specific document components like parties, line items, and taxes, see Document Components.

---

Installation

Go Package Installation

Add the library to your Go project using:

The package requires Go 1.24.4 or later (as specified in go.mod3) and depends on the core GOBL library (github.com/invopop/gobl v0.308.0).

Sources: README.md1-8 go.mod1-6 go.sum33-34

CLI Tool Installation

Install the command-line tool directly from source:

This installs the gobl.ubl executable to your $GOPATH/bin directory. Ensure this directory is in your system PATH.

Sources: README.md114-118

---

Conversion Workflow Overview

The library provides bidirectional conversion between GOBL and UBL formats through four primary API functions defined in the ubl package:

Core Conversion Functions:

Conversion Direction Decision Matrix:

Starting With	Need	Use Function	Defined In	Returns
GOBL Envelope	UBL struct	ubl.ConvertInvoice()	ubl.go	*ubl.Invoice
UBL struct	XML bytes	ubl.Bytes()	ubl.go	[]byte
UBL XML bytes	UBL struct	ubl.Parse()	ubl.go	*ubl.Invoice
UBL struct	GOBL Envelope	(*Invoice).Convert()	invoice_from.go	*gobl.Envelope

Sources: README.md10-110

---

GOBL to UBL Conversion

Converting a GOBL Envelope to UBL XML involves three steps: reading the envelope, converting to UBL structure, and marshaling to XML bytes.

Basic Conversion Pattern

Conversion Pipeline:

Example Code Reference

The complete pattern is demonstrated in README.md25-56 Key steps:

1. Load GOBL Envelope: Read JSON file and unmarshal into *gobl.Envelope
2. Convert to UBL: Call ubl.ConvertInvoice(env) to get *ubl.Invoice
   • Internally calls ubl.Convert() which extracts the invoice from the envelope
   • Applies the specified context (default: ContextEN16931)
   • Ensures required addons via ensureAddons() function
   • Removes included taxes as UBL does not support tax-inclusive pricing
   • Builds the UBL Invoice structure via ublInvoice() orchestrator function
3. Generate XML: Call ubl.Bytes(doc) to marshal to XML with XML declaration header

The ubl.ConvertInvoice() function is a convenience wrapper that:

• Accepts *gobl.Envelope directly
• Extracts the bill.Invoice document
• Delegates to ubl.Convert() for the actual conversion
• Returns *ubl.Invoice ready for serialization

Using Custom Contexts

The default conversion uses ContextEN16931. To use a different UBL profile (Peppol, XRechnung, etc.), pass a context option using the WithContext() function:

Available Context Constants (defined in context.go):

Constant	Standard	Addon Requirement	ProfileID
ContextEN16931	European EN 16931	en16931-v2017	urn:cen.eu:en16931:2017
ContextPeppol	Peppol BIS Billing 3.0	en16931-v2017	urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
ContextPeppolSelfBilled	Peppol Self-Billed	en16931-v2017	urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0
ContextXRechnung	German XRechnung	xrechnung-v3	urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0
ContextPeppolFranceCIUS	French CIUS	ctc-flow2-v1	urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0#conformant#urn:fdc:peppol.eu:2017:poacc:billing:3.0:extended:urn:fdc:aife.economie.gouv.fr:billing:1.0
ContextPeppolFranceExtended	French Extended	facturx-v1	Custom Output ID

Each context influences:

• CustomizationID: Identifies the business process specification
• ProfileID: Identifies the business process context
• Required Addons: GOBL extensions that must be present in the invoice
• VESID: Validation artifact ID for Phive validation

For more details on contexts and how they affect conversion, see Context and Profile System.

Sources: README.md58-62 examples_test.go56-68

---

UBL to GOBL Conversion

Converting UBL XML to GOBL format involves parsing the XML and converting the resulting structure to a GOBL Envelope.

Basic Parsing Pattern

Parsing Pipeline:

Example Code Reference

The complete pattern is demonstrated in README.md66-109 Key steps:

1. Parse UBL XML: Call ubl.Parse(inData) with XML bytes
   • Extracts root namespace via extractRootNamespace() to distinguish Invoice from CreditNote
   • Routes to appropriate document type constructor
   • Uses xmlctx.Unmarshal() for namespace-aware XML parsing
2. Type Assert: Cast result to *ubl.Invoice (both Invoice and CreditNote implement the same interface)
3. Convert to GOBL: Call inv.Convert() to get *gobl.Envelope
   • Calls FindContext() to detect context from CustomizationID/ProfileID
   • Extracts parties via goblParty() function
   • Extracts lines via goblAddLines() function
   • Extracts payment terms, charges, totals, attachments, delivery, and ordering information
   • Wraps the resulting bill.Invoice in a gobl.Envelope
4. Extract Attachments (Optional): Call inv.ExtractBinaryAttachments() for embedded binary files

Handling Binary Attachments

UBL documents may contain embedded binary attachments in AdditionalDocumentReference elements with EmbeddedDocumentBinaryObject nodes (Base64-encoded). Extract them separately using the ExtractBinaryAttachments() method:

Binary Attachment Structure:

The extraction method:

• Iterates through all AdditionalDocumentReference elements
• Checks for Attachment.EmbeddedDocumentBinaryObject (Base64 data)
• Decodes the Base64 content
• Returns slice of BinaryAttachment structs with Filename and Data fields

Sources: README.md101-102

---

Command Line Tool

The gobl.ubl CLI tool provides automatic format detection and bidirectional conversion without writing code.

Automatic Format Detection Flow

CLI Detection Logic (cmd/gobl.ubl/convert.go):

Basic Usage

Convert any supported file by providing input and optional output paths:

Command Structure:

The convert command is implemented using the Cobra CLI framework:

• Command definition: Creates convertCmd with usage, description, and argument validation
• Execution function: runConvert() handles the actual conversion logic
• Format detection: Uses json.Valid() from the standard library to detect JSON vs XML
• Output handling: Writes to specified file or stdout if no output path provided

The implementation in cmd/gobl.ubl/convert.go:

• For JSON input: Unmarshals to gobl.Envelope → calls ubl.Convert() → calls ubl.Bytes() → writes XML
• For XML input: Calls ubl.Parse() → calls invoice.Convert() → marshals JSON → writes JSON

Sources: README.md112-129

---

Example Documents

The repository includes comprehensive example documents for testing and reference:

Directory Structure

Directory	Purpose	Format
test/data/convert/	GOBL → UBL conversion examples	Input: .json, Output: .xml
test/data/parse/	UBL → GOBL parsing examples	Input: .xml, Output: .json

Context-Specific Examples

Examples are organized by UBL profile in separate subdirectories:

Example Directory Structure:

Subdirectory	Context Constant	Standard	Test Function
en16931/	ContextEN16931	European EN 16931 standard	TestConvertToInvoice
peppol/	ContextPeppol	Peppol BIS Billing 3.0	TestConvertToInvoice
peppol-self-billed/	ContextPeppolSelfBilled	Peppol self-billed variant	TestConvertToInvoice
xrechnung/	ContextXRechnung	German XRechnung	TestConvertToInvoice
france-cius/	ContextPeppolFranceCIUS	French CIUS	TestConvertToInvoice
france-extended/	ContextPeppolFranceExtended	French extended	TestConvertToInvoice

Test Data Usage

Test Automation in examples_test.go:

The test suite uses filepath.Glob() to automatically discover and process all example files in each context directory:

Test file categories include:

• invoice-minimal.json: Basic required fields only
• invoice-complete.json: All optional fields populated
• credit-note examples: Negative invoice scenarios
• invoice-partial.json: Invoices referencing specific order line items
• Documents with charges/allowances: Discounts and surcharges at document and line level
• Documents with attachments: Embedded binary files

Each test:

1. Loads the input file (JSON for convert tests, XML for parse tests)
2. Performs the conversion using the appropriate context
3. Compares output against expected results in the out/ subdirectory
4. Optionally validates against XSD schema or Phive service

For detailed example analysis, see Example Documents.

Sources: examples_test.go42-122 examples_test.go124-220

---

Testing Your Conversions

The library includes a comprehensive test framework for validating conversions:

Test Flags

Command-Line Flags (defined in examples_test.go):

Flag Variable	Purpose	Usage Example
updateOut	Regenerate expected output files in out/ directories	go test -update ./...
validate	Run Phive gRPC validation on generated XML documents	go test -validate ./...

Running Tests

Test Framework Validation (examples_test.go):

The test framework validates:

1. Round-trip consistency: GOBL → UBL → GOBL preserves data integrity
2. Schema compliance: Generated XML matches UBL 2.1 XSD schemas (via libxml2)
3. Context correctness: CustomizationID, ProfileID, and VESID values match context specifications
4. Component accuracy: Parties, lines, taxes, payments, charges, and totals convert correctly
5. Phive validation: Optional external validation via Phive gRPC service on port 9091

Test Helper Functions:

• testInvoiceFrom(): Converts GOBL JSON to UBL Invoice
• testInvoiceFromContext(): Converts with specific context
• loadTestEnvelope(): Loads and validates GOBL envelope
• testParseInvoice(): Parses UBL XML to GOBL envelope
• ValidateXML(): Validates XML against XSD schema using libxml2

For details on the test framework, see Test Framework.

Sources: examples_test.go36-41 examples_test.go42-122 examples_test.go368-381

---

Important Conversion Considerations

Be aware of these limitations when converting between formats:

Data Loss During UBL → GOBL Conversion

UBL Field	BG/BT Code	Impact	Mitigation
AdditionalReferencedDocument	BG-24	Not supported in GOBL	Lost in conversion
Multiple InvoicePeriod	BG-14	Only first period used	Additional periods ignored
ProfileID	BT-23	Not stored in GOBL	Detected but not preserved
CustomizationID	BT-24	Not stored in GOBL	Detected but not preserved
AccountingCost	BT-19, BT-133	No GOBL equivalent	Added as notes

Special Handling

• Payment advances: Do not include individual tax rates; use global invoice tax rate
• Tax categories: Built from TaxTotal and enriched into lines/charges
• Base quantities: Price amounts divided by BaseQuantity when converting from UBL

For complete data transformation rules, see Data Transformation Rules.

Sources: README.md141-150

---

Next Steps

After getting started with basic conversions, explore these topics:

1. Context and Profile System - Learn how to use different UBL profiles (Peppol, XRechnung, etc.)
2. Document Components - Understand how parties, line items, taxes, and payments are converted
3. UBL to GOBL Parsing - Deep dive into the parsing pipeline and component extraction
4. GOBL to UBL Generation - Understand the generation pipeline, validation, and tax handling
5. Example Documents - Review comprehensive examples for different scenarios

For development and contribution information, see Development.

Sources: README.md1-158