The UBL file: what it looks like and how to read it

What a UBL file is

UBL stands for Universal Business Language. It is a standard published by OASIS to describe business documents — orders, despatch advices, invoices — in a form software can exchange without prior agreement. The version used across Europe for invoicing is UBL 2.1.

A UBL file is an XML document: plain text organised by nested tags. It starts with <Invoice> for an invoice, or <CreditNote> for a credit note. That is the simplest way to tell what you are holding.

Like the other syntax, UBL complies with the European EN 16931 standard: it expresses the same information as CII or a hybrid PDF, with a different vocabulary.

Why it has no visual rendering

A PDF describes a page: fonts, positions, rules. A UBL file describes nothing of the sort. It holds no logo, no colour, no frame, no display order. It does not say how to present the invoice; it says what each piece of information is worth.

That is a choice, not an oversight. The same invoice must be importable automatically by any accounting software, anywhere in Europe. Layout would make the file nicer for you and far less usable for the machine.

In practice, opening a UBL file in a browser shows a collapsible tree of tags; in a text editor, a long run of lines. Either way the information is there, but you have to hunt for it by hand.

What the content looks like

Tag names follow two families: cbc: for simple values, cac: for blocks that group several. The prefixes themselves are free — an issuer may pick others — only the name that follows really counts.

• cbc:ID — the invoice number (BT-1)
• cbc:IssueDate — the issue date (BT-2)
• cbc:DueDate — the due date (BT-9)
• cac:AccountingSupplierParty — the seller block
• cac:AccountingCustomerParty — the buyer block
• cac:InvoiceLine — one invoice line, repeated as often as needed
• cac:TaxTotal — VAT, in total and per rate
• cac:LegalMonetaryTotal — the totals, including cbc:PayableAmount, the amount due (BT-115)

Amounts are written for machines: decimal point, no thousands separator, currency given as an attribute. So 1234.50 reads as 1,234.50.

How to read a UBL file

1. Drop the .xml file on the drop zone.
2. The syntax is recognised automatically from the first tag.
3. The invoice appears laid back out: parties, lines, VAT breakdown, totals, payment.
4. The findings follow, with the amounts concerned.

A UBL file may also declare a more precise profile, for instance Peppol BIS Billing 3.0 or XRechnung. That profile is shown as declared: it states which variant of the standard the issuer claims to follow. The format comparison puts those profiles back in context.

What the file will not tell you by itself

A UBL file can be perfectly well-formed and still wrong. XML guarantees structure, not correctness: an IBAN with a missing digit, a company number whose check fails, a VAT amount that does not match its base, or a due date before the issue date all produce a technically valid and commercially unusable file.

That is precisely what the BR-xx rules of EN 16931 are for, and what Lekteo checks on every read. If these files are new to your inbox, the page on who must comply explains where they come from.