Document Formats

Relevant source files

• test/data/convert/peppol/out/invoice-with-contract-ref.xml
• test/data/parse/discount-taxes.xml
• test/data/parse/en16931/out/credit-note1.json
• test/data/parse/en16931/out/custom-namespace-prefixes.json
• test/data/parse/en16931/out/ubl-example5.json
• test/data/parse/france-cius/out/b2b-reg.json
• test/data/parse/peppol/out/Allowance-example.json
• test/data/parse/peppol/out/Vat-category-S.json
• test/data/parse/peppol/out/base-creditnote-correction.json
• test/data/parse/peppol/out/base-example.json
• test/data/parse/peppol/out/invoice-peppol.json
• test/data/parse/peppol/out/nbio-stuck-ubl.json
• test/data/parse/peppol/out/vat-category-E.json

This page provides an overview of the two document formats used by the gobl.ubl library: GOBL JSON and UBL XML. It explains their structural differences, serialization characteristics, and fundamental design philosophies.

The gobl.ubl library acts as a bridge between GOBL's JSON-based internal representation and UBL's XML-based exchange format. Understanding the differences between these formats is essential for working with the conversion system.

Related Pages:

• GOBL Envelope Structure - Detailed structure of GOBL envelopes and document payloads
• UBL Invoice Structure - Detailed UBL XML schema, namespaces, and elements
• Document Types and Tags - Invoice type codes and their mappings
• Data Transformation Rules - How data is transformed during conversion
• Document Components - Individual invoice components (parties, lines, etc.)

Format Comparison

The gobl.ubl library operates with two distinct document formats that serve complementary roles in the electronic invoicing ecosystem:

Aspect	GOBL Format	UBL Format
Serialization	JSON	XML
Primary Use	Internal representation, data processing, API exchange	International e-invoicing standard, regulatory compliance
Document Structure	Two-layer: gobl.Envelope wrapping bill.Invoice	Single-layer: flat Invoice or CreditNote document
Metadata Location	Separate head section in envelope	Inline fields like CustomizationID, ProfileID
Namespace Model	JSON $schema URLs for type identification	XML namespaces (7 required: cac, cbc, qdt, udt, ccts, UBL root, xsi)
Type System	Go structs from github.com/invopop/gobl package	Go structs defined in this package (invoice.go26-97)
Versioning	Schema-based (e.g., draft-0)	Fixed at UBL 2.1 (ubl.go26-28)
Tax Representation	Supports both tax-inclusive and tax-exclusive pricing	Tax-exclusive only
Regime Handling	$regime field specifies tax jurisdiction	Inferred from party tax IDs
Extension Mechanism	$addons array for validation rules	CustomizationID for profile-specific rules

Sources: ubl.go1-28 invoice.go14-97 test/data/parse/peppol/out/nbio-stuck-ubl.json1-22

Structural Overview

Title: GOBL vs UBL Document Architecture

The key structural difference is that GOBL separates document metadata (in head) from payload (in doc), while UBL embeds all information in a flat XML document. This affects how identifiers, validation, and versioning are handled.

Sources: ubl.go30-88 ubl.go90-120 invoice.go26-97 test/data/parse/peppol/out/nbio-stuck-ubl.json1-212

GOBL Document Structure

GOBL uses a two-layer envelope pattern where metadata and document content are strictly separated. The outer layer is a gobl.Envelope (from the github.com/invopop/gobl package), and the inner layer is a bill.Invoice.

Title: GOBL Envelope and Document Structure

Example JSON Structure:

Key Design Principles:

1. Separation of Concerns: Metadata (head) is separate from business data (doc)
2. Schema Identification: Both layers have $schema fields for type identification
3. Regime-First: The $regime field explicitly declares the tax jurisdiction
4. Extensibility: The $addons array allows attaching validation rules without modifying the core schema
5. Integrity: The dig (digest) ensures document integrity through cryptographic hashing

During conversion, the ubl.Convert() function calls env.Extract() to retrieve the inner bill.Invoice from the envelope.

Sources: test/data/parse/peppol/out/nbio-stuck-ubl.json1-22 test/data/parse/france-cius/out/b2b-reg.json1-28 ubl.go103-119

For detailed information about envelope fields, UUID generation, and digest algorithms, see GOBL Envelope Structure.

UBL Document Structure

UBL uses a flat XML document structure where all information is embedded in a single root element (Invoice or CreditNote). The Go representation is the Invoice struct (invoice.go26-97), which handles both document types through conditional fields.

Title: UBL XML Document Structure

Example XML Structure:

Key Design Principles:

1. Namespace-Based Typing: Element types are determined by namespace prefixes (cbc for basic, cac for aggregate)
2. Flat Hierarchy: All invoice data is at the same document level
3. Profile-Based Validation: CustomizationID and ProfileID specify which validation rules apply
4. Dual Document Type: The same Invoice struct handles both invoices and credit notes via conditional fields
5. Schema Validation: xsi:schemaLocation attribute points to XSD schemas for validation

During parsing, the ubl.Parse() function calls extractRootNamespace() (ubl.go150-166) to determine whether the document is an Invoice or CreditNote based on the root element's namespace.

Sources: invoice.go26-97 test/data/convert/peppol/out/invoice-with-contract-ref.xml1-12 ubl.go150-166

For detailed information about UBL elements, namespace handling, and schema locations, see UBL Invoice Structure.

Serialization Characteristics

JSON Serialization (GOBL)

GOBL documents are serialized as standard JSON with the following characteristics:

Format Properties:

• Human-readable text format
• Nested object structure with clear hierarchy
• Field names use snake_case convention (e.g., issue_date, tax_id)
• Special fields prefixed with $ indicate schema metadata ($schema, $regime, $addons)
• Arrays use square brackets: "lines": [...], "$addons": [...]
• Monetary values stored as strings with fixed decimal precision: "amount": "195.00"

Example:

Sources: test/data/parse/peppol/out/nbio-stuck-ubl.json1-212

XML Serialization (UBL)

UBL documents are serialized as XML with namespace-qualified elements:

Format Properties:

• Verbose XML structure with namespace prefixes
• Element names use PascalCase convention (e.g., IssueDate, TaxTotal)
• Namespace prefixes distinguish element types: cbc: for basic, cac: for aggregate
• Attributes specify metadata: currencyID, schemeID, unitCode
• Monetary values stored as element text with currencyID attribute: <cbc:Amount currencyID="EUR">195.00</cbc:Amount>
• Generated with 2-space indentation by ubl.Bytes() (ubl.go168-176)

Example:

Sources: test/data/convert/peppol/out/invoice-with-contract-ref.xml1-125 ubl.go168-176

Document Serialization

XML Output Generation

The Bytes function serializes UBL documents to XML with proper formatting:

The function performs these steps:

1. Calls xml.MarshalIndent(in, "", " ") for readable XML with 2-space indentation
2. Prepends the standard XML header: <?xml version="1.0" encoding="UTF-8"?>
3. Returns the complete XML document as bytes

Sources: ubl.go168-176

JSON Envelope Structure

GOBL documents are always wrapped in an envelope structure. The conversion process extracts the inner document:

Key Operations:

• env.Extract() - Retrieves the inner document from the envelope
• ensureAddons() - Validates and adds required addons from context (e.g., eu-en16931-v2017)
• RemoveIncludedTaxes() - Converts tax-inclusive amounts to tax-exclusive (UBL requirement)
• ublInvoice() - Performs the actual document conversion

Sources: ubl.go90-120 ubl.go122-148

Schema Locations and Validation

UBL documents include schema location attributes for XML validation:

Document Type	Schema Location Constant	Value
Invoice	SchemaLocationInvoice	urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd
CreditNote	SchemaLocationCrediteNote	urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2 https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd

These are set in the Invoice struct's SchemaLocation field during conversion. The schema locations enable validators to fetch the appropriate XSD schemas for document validation.

Sources: invoice.go20-24 invoice.go122-148

Version Constants

The library defines a single UBL version constant:

This value is used to populate the UBLVersionID field in generated Invoice documents, ensuring compliance with UBL 2.1 specifications.

Sources: ubl.go26-28