# UBL-CR-002: Declare UBL version 2.1 or leave the version out

Warning: `cbc:UBLVersionID` names a version other than 2.1. The document stays valid; write `2.1` or leave the element out.

- Layer: EN 16931
- Severity: warning (the document stays valid)
- Topics: Core fields
- Official definition: https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/UBL-CR-002/
- Explanation last updated: 2026-09-29

## The short answer

`UBL-CR-002` is a warning raised when `cbc:UBLVersionID` is present with a value other than `2.1`. The document is UBL 2.1: write `2.1` there, or leave the element out.

The warning on its own does not make the document invalid, though other rules still check what is there.

## What the rule checks

The rule reads the value: `cbc:UBLVersionID` may be left out, or present with `2.1`; any other value raises it. The recorded example says `2.0`.

It runs once against the whole document, so it is reported once however many times the document has the element, and the finding points at the document root rather than at the element: look for `cbc:UBLVersionID` in the XML.

| Term | Meaning | UBL element |
|---|---|---|
| - | UBLVersionID with a value other than 2.1 (UBL only, no business term) | `cbc:UBLVersionID` |

## How an integration ends up here

Possible causes, from the shape of the rule rather than from measured usage:

- The document comes from a library or template written for another UBL version, and states that version.
- A general UBL 2.1 library writes every element and attribute it has a value for, whether or not EN 16931 uses it.
- A mapping built for another UBL-based document, such as an order, a despatch advice or a national profile, is reused for Peppol BIS Billing.

## How to fix it

1. Write `2.1` in `cbc:UBLVersionID`, or stop writing the element.
2. The specification a receiver validates against is named in `cbc:CustomizationID` (BT-24), not by the UBL version.
3. Validate again: the warning goes.

## Before and after

These are fragments, not complete documents. The complete synthetic documents they come from are linked below.

Fragment of the invoice with the warning: UBLVersionID in the document header

```xml
<cbc:UBLVersionID>2.0</cbc:UBLVersionID>
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>EXAMPLE-INV-002</cbc:ID>
```

Fragment of the corrected invoice: the same lines without it

```xml
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>EXAMPLE-INV-002</cbc:ID>
```

The invoice with the warning has `<cbc:UBLVersionID>2.0</cbc:UBLVersionID>` in the document header, and the corrected invoice is the same document without it. It reports only this warning and is valid on every layer, so it would be accepted as it stands.

### What the validator reported

- The invoice with the warning is valid, and reports the warning **UBL-CR-002**. The corrected document passes every layer with no findings.
  - [Download the XML with the warning](https://ironfang.com/finance/rule-examples/UBL-CR-002-warning.xml)
  - [Download the corrected XML](https://ironfang.com/finance/rule-examples/syntax-invoice-complete.xml)

Recorded on phive 12.1.0 / phive-rules-peppol 4.5.6 / Saxon-HE 12.10, the engine behind the free validator, using synthetic data. A recorded result is regression evidence for these documents; it is not a certification.

## Where it applies

- Applies to UBL `Invoice` and `CreditNote` alike; the recorded example is an invoice.
- The warning comes from the EN 16931 layer's rules for the UBL syntax. In the recorded example the schema layer passes: the element is valid UBL 2.1 and is only outside the EN 16931 model.

## Related rules

- [UBL-CR-001: UBLExtensions in the document header](https://ironfang.com/docs/finance/rules/UBL-CR-001.md)
- [UBL-CR-003: ProfileExecutionID in the document header](https://ironfang.com/docs/finance/rules/UBL-CR-003.md)
- [UBL-CR-004: CopyIndicator in the document header](https://ironfang.com/docs/finance/rules/UBL-CR-004.md)

## Scope and source

Written for Peppol BIS Billing 3.0.21 (May 2026), EN 16931 1.3.16, as applied to UBL 2.1 Invoice and CreditNote documents. Other profiles, syntaxes and releases can define this identifier differently. Guidance version 2026-09-29.1: source checked 2026-09-29, explanation last updated 2026-09-29.

[The official definition of UBL-CR-002](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/UBL-CR-002/) carries the normative wording and test. This page is our explanation of it, not a copy.

Guidance does not change the engine verdict. Fixing this finding does not mean the document passes every layer, and validation does not certify legal or tax compliance or transmit a document over Peppol.

## Links

- [This rule as a web page](https://ironfang.com/docs/finance/rules/UBL-CR-002)
- [Free Peppol invoice validator](https://ironfang.com/tools/peppol-validator)
- [Rule index](https://ironfang.com/docs/finance/rules.md)
- [Ironfang Finance API docs](https://ironfang.com/docs/finance)
- The same rule is available to MCP clients as the tool `finance.rule.get` on https://mcp.ironfang.com/mcp