Skip to main content

​
What is UBL?

Universal Business Language (UBL) is an international standard for electronic business documents developed by OASIS (Organization for the Advancement of Structured Information Standards). UBL 2.1 provides a library of XML schemas for common business documents like invoices, orders, and shipping notices.
UBL 2.1 is the foundation for electronic invoicing systems worldwide, including mandatory e-invoicing implementations in countries like Colombia (DIAN), Peru (SUNAT), and across the European Union.

​
Why UBL Matters

UBL standardizes the structure and semantics of business documents, enabling:

Interoperability

Systems from different vendors can exchange documents seamlessly without custom integrations

Compliance

Meet tax authority requirements for electronic invoicing in multiple jurisdictions

Automation

Machine-readable formats enable automated processing and validation

Global Adoption

Widely adopted standard supported by governments and enterprises worldwide

​
UBL 2.1 Key Features

​
Schema-Based Validation

UBL documents are validated against XML schemas that define:
  • Required and optional elements
  • Data types and formats
  • Business rules and constraints
  • Cardinality (min/max occurrences)

​
Hierarchical Structure

UBL documents follow a hierarchical organization: 
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <!-- Document metadata -->
  <cbc:ID>INV-001</cbc:ID>
  <cbc:IssueDate>2026-03-06</cbc:IssueDate>
  
  <!-- Parties -->
  <cac:AccountingSupplierParty>
    <!-- Supplier details -->
  </cac:AccountingSupplierParty>
  
  <cac:AccountingCustomerParty>
    <!-- Customer details -->
  </cac:AccountingCustomerParty>
  
  <!-- Line items -->
  <cac:InvoiceLine>
    <!-- Product/service details -->
  </cac:InvoiceLine>
  
  <!-- Totals and taxes -->
  <cac:TaxTotal>
    <!-- Tax calculations -->
  </cac:TaxTotal>
</Invoice>

​
Namespace Organization

UBL uses multiple XML namespaces to organize components:
Simple data elements like IDs, dates, amounts, and text fields.Namespace: urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2Examples: cbc:ID, cbc:IssueDate, cbc:TaxAmount
Complex structures that group related data elements together.Namespace: urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2Examples: cac:Party, cac:TaxTotal, cac:InvoiceLine
Allows custom extensions while maintaining UBL compliance.Namespace: urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2Used for: Country-specific requirements, digital signatures, custom fields

​
UBL Document Types

While this library focuses on invoices, UBL 2.1 defines many document types:
Document TypePurpose
InvoiceRequest for payment for goods or services
Credit NoteAdjustment reducing amount owed
Debit NoteAdjustment increasing amount owed
OrderPurchase order from buyer to seller
Despatch AdviceNotification of goods shipment
Receipt AdviceConfirmation of goods received

​
Country-Specific Implementations

​
Colombia (DIAN)

This library includes specialized support for Colombia’s DIAN (Dirección de Impuestos y Aduanas Nacionales) requirements:
  • CUFE calculation: Cryptographic hash for document uniqueness
  • QR code generation: For mobile verification
  • Digital signatures: Using XAdES standard
  • Software provider validation: PIN and security codes
const invoice = new Invoice('SETP990000001', {
  timestamp: Date.now(),
  enviroment: '2', // 1=production, 2=testing
  issuer: {
    resolutionNumber: '18760000001',
    technicalKey: 'fc8eac422eba16e22ffd8c6f94b3f40a6e38162c6b970d',
    prefix: 'SETP',
    startRange: '990000000',
    endRange: '995000000',
    startDate: '2019-01-19',
    endDate: '2030-01-19',
  },
  software: {
    id: 'software-id',
    pin: 'software-pin',
    providerNit: '800197268',
  },
});
CUFE (Código Único de Factura Electrónica) calculation must follow the exact formula specified by DIAN. The library handles this automatically when you call finalizeDocument().

​
Official UBL Resources

OASIS UBL TC

Official UBL Technical Committee page

UBL 2.1 Schemas

Download XSD schemas and documentation

UBL Library

Searchable schema documentation

DIAN Technical Annex

Colombia’s electronic invoicing specifications

​
Next Steps

1

Document Structure

Learn how UBL documents are organized in the libraryExplore Document Structure →
2

XML Generation

Understand how the library converts objects to valid UBL XMLLearn XML Generation →
3

Build Your First Invoice

Follow the quickstart guide to create a complete invoiceStart Building →

Build docs developers (and LLMs) love

Get started for freeTalk to us