UBL 2.1 explained without jargon for Moroccan businesses

UBL 2.1 is not software and it is not a PDF with a different extension. It is a public XML vocabulary that puts business data into named, predictable places. Software can locate the number, seller, buyer, VAT and total without visually reading a page. BelloPOS uses it as its structured export format. As of 29 August 2026, we do not present it as a national schema mandated by a published Moroccan DGI technical specification.

1. Read the UBL tree like an invoice

Picture a main folder named Invoice. Some labels contain one value: ID for the number, IssueDate for the date and DocumentCurrencyCode for MAD. Others open a subfolder: AccountingSupplierParty for the seller, AccountingCustomerParty for the buyer and InvoiceLine for each line. That organization separates structured invoices from ordinary PDFs.

UBL element	What it represents	Readable example
Invoice / CreditNote	Document type and root	Invoice or credit note
cbc:ID	Document number	FAC-2026-00418
cbc:IssueDate	Issue date	2026-08-29
cbc:DocumentCurrencyCode	Currency	MAD
cac:AccountingSupplierParty	Seller identity	Legal name, address, ICE
cac:AccountingCustomerParty	Buyer identity	Customer company and ICE
cac:InvoiceLine	One billed line	Quantity, item, price and tax
cac:TaxTotal	Grouped VAT	Base, rate and amount
cac:LegalMonetaryTotal	Legal totals	Net, VAT, gross and payable

The names are long to remove ambiguity between systems. cbc generally holds a basic component such as an identifier or date; cac holds an aggregate such as a party or line. You need not memorize them, but recognizing them makes an export easier to inspect.

---

2. Connect the visible page to the XML data

Take two chairs at MAD 500 net each with 20% VAT. The A4 page shows the buyer, two units, MAD 1,000 net, MAD 200 VAT and MAD 1,200 gross. XML must tell exactly the same story: quantity 2, unit price 500, line amount 1,000, tax rate 20, tax 200 and payable 1,200. Check the required Moroccan invoice fields in both views.

• Seller: Legal name, address and identifiers are grouped under the supplier party.
• Buyer: Applicable identity is structured instead of buried in a note.
• Lines: Every quantity, unit, description, price and amount remains tied to the item.
• VAT: Subtotals by category or rate allow the tax amount to be rebuilt.
• Totals: Bases, tax, rounding and payable amount must reconcile to the lines.
• Payment: Method, due date and reference can be structured without changing the invoice total.

An invoice may be readable but badly structured, or structured but fiscally wrong. Valid XML can hold an ICE in the right element; it cannot know whether that ICE truly belongs to the buyer. Quality still depends on input data, software rules and human review.

3. Four validation levels that are not interchangeable

The word valid is incomplete. Always ask: valid against what?

1. Well-formed XML: tags close correctly and special characters are escaped.
2. Valid against UBL 2.1 XSD: elements and data types follow OASIS’s generic schema.
3. Compliant with business rules: numbering, identity, calculations, references and taxes satisfy the required profile.
4. Accepted by the recipient: its portal or system receives the file and returns a receipt or status.

Check	What it detects	What it does not prove
XML parser	Broken tag or invalid character	Correct VAT treatment
XSD schema	Disallowed structure or data type	A Moroccan national profile
Business rules	Inconsistent total or missing field	That filing happened
Portal receipt	Receipt or rejection by that channel	Truth of every entered fact

A future Moroccan specification may restrict UBL, choose another syntax or add codes and signatures. Our guide to the current electronic-invoicing obligation therefore separates the tax code from technical details that still require an official text.

4. What BelloPOS writes into UBL 2.1

BelloPOS serializes an invoice under Invoice and a credit note under CreditNote. The export carries the issued number, date, MAD, seller and buyer parties with available ICEs, lines, quantities, prices, VAT grouped by rate, totals and payment data. An XML library escapes characters such as & and < rather than concatenating raw text.

At issue time, the application preserves the exact XML and calculates its SHA-256 fingerprint. It later exports those same bytes instead of rebuilding the invoice with details that may since have changed. The SHA-256 sealing guide explains that evidence.

The feature is included in BelloPOS Go and Pro. It prepares and exports locally; it neither applies a qualified certificate signature nor transmits directly to DGI. The merchant or accountant must confirm the available official channel and its current requirements.

5. A non-developer’s inspection checklist

Work on a copy and use a trusted editor that does not execute remote content.

• The file ends in .xml and opens without a syntax error.
• Its root matches the document: Invoice or CreditNote.
• Number, date and MAD match the visible invoice.
• Seller name, address and ICE are accurate.
• The business buyer and ICE match the approved record.
• Each line contains quantity, description, price and amount.
• VAT bases and amounts rebuild by rate.
• The payable amount matches what the customer received.
• The file hash matches the manifest when one is supplied.
• The recipient confirms the syntax and profile it expects.

Keep the PDF, XML, manifest and any receipt together under stable names. A readable and structured pair makes restitution, audit and future migration easier.

Mistakes to avoid

• Renaming a PDF to .xml.
• Assuming every UBL element is mandatory in every profile.
• Checking syntax without reconciling amounts.
• Treating CreditNote as an improvised negative invoice.
• Presenting UBL as proof of DGI filing.
• Editing sealed XML to fix the display.
• Uploading real customer data to an unknown online validator.
• Failing to retain the readable view and receipt.

---

Frequently asked questions

Is UBL 2.1 an electronic-invoice format?

Yes. OASIS publishes structured business documents including Invoice and CreditNote. A recipient profile can add its own constraints.

Is UBL 2.1 officially mandated by Morocco’s DGI?

We found no published national specification in the official sources checked by 29 August 2026 that supports that general claim. BelloPOS uses it as its export syntax.

Must a customer read the XML?

Usually not. PDF or print remains useful to a person while XML serves software. Both must describe the same invoice.

What is the difference between Invoice and CreditNote?

Invoice represents an invoice. CreditNote represents a credit note and can reference the corrected invoice. They are distinct UBL roots.

Is an XSD-valid file tax-correct?

Not necessarily. XSD checks generic structure. Real identity, VAT, numbering, business rules and recipient acceptance need other checks.

Does BelloPOS send UBL to the DGI?

No. Go and Pro prepare, seal and export it. Filing remains with the merchant or accountant through the available official channel.

What to take away

UBL 2.1 becomes understandable when read as a folder: document root, parties, lines, tax and totals. Its value is predictable data, not a compliance badge. Treat the visible invoice, XML, recipient profile and submission receipt as four separate proofs.

Sources

The figures and rules quoted above come from these pages, read on the date given in the article.

• Official Universal Business Language 2.1 specification, OASIS
• Moroccan General Tax Code 2026, DGI, read 29 August 2026
• BelloPOS electronic invoicing and UBL export, read 29 August 2026

Read next

Other practical guides on the same subject:

• How to export electronic invoices as XML and ZIP
• SHA-256 invoice sealing: what the fingerprint proves and what it does not
• Electronic invoice or PDF: what is the difference in Morocco?
• Electronic invoicing in Morocco: 50 common questions, verified answers