Release notes for OIOUBL BIS 3 documents

v3.0.0 RC

OIOUBL BIS Billing with Response

While all reasonably practicable effort has been undertaken toward the completeness of the below changelog, OIOUBL 3 is a major revision. Some breaking changes may not have been identified. Users are strongly encouraged to conduct their own comprehensive testing.

Release	Issue	Description	Type
Version 3.0.0.RC	N/A	Initial update of OIOUBL 3 BIS Billing With Response	New
	Separation of message level and business level responses	In OIOUBL 2, message and business level responses both used the ApplicationResponse document. OIOUBL 3 has split these into different customization IDs and profiles, to improve clarity regarding choreography and parties. OIOUBL 3 Invoice Response follows the Peppol Invoice Response closely in syntax. However, there is a significant difference in choreography: A Peppol Invoice Response must be sent within three business days of receipt of the invoice. An OIOUBL Invoice Response must be sent without undue delay and no later than the parties to the invoice transaction have mutually agreed (if they have agreed on a deadline).	Breaking
	Two-way profiles only	In OIOUBL 2, several profiles were available for sending invoices without being able to receive an invoice response. This is not supported in OIOUBL 3, for business users. All institutional end users are expected and required to receive invoice responses at an endpoint registered to their business. An invoice profile and associated BIS will be published shortly for use by physical persons (who cannot have an endpoint for invoice responses, as this would expose their CPR number to the public). This profile will not be useable for institutional senders. This change is made in anticipation that it will within the lifetime of IT systems deployed today become mandatory to be able to account for the full life cycle of invoices in a structured manner.	Breaking
	Interpretations	The OIOUBL 2 documentation indicated which fields were possible to ingest in a structured manner. In OIOUBL 3, this is no longer indicated. Rather, OIOUBL 3 indicates which values must be shown to the end user, because these fields contain information that the recipient of a document will be deemed to have known in the event of a dispute. This means that a number of free text fields, which are not readily ingestible, are marked as read-mandatory, while a number of structured data fields no longer are.	Semantic change
		OIOUBL operates with three different inclusion levels for a data field: Supported fields have semantic definitions that are given in the relevant BIS and syntax documentation. All service providers implementing OIOUBL are expected to be familiar with these field definitions. Excluded fields are listed in the syntax documentation, but not usually in the BIS. These must not be used, and will cause validation errors if included. Unsupported fields are all other data structures that are schema-valid for the underlying UBL, but neither supported nor explicitly excluded. Unsupported fields are not shown in the syntax documentation nor in the BIS. It is permissible for parties to bilaterally agree to the use of unsupported fields, provided the implementation is schema-valid. However, neither end users nor service providers are required or expected to be familiar with these data structures, in the absence of an explicit prior agreement to that effect.	Clarification
		Prior versions of OIOUBL documentation used field definitions that were oriented toward technical implementation in EDI solutions, but did not prioritize making explicit the semantic content of the fields. OIOUBL 3 aims to provide field names and definitions which can be used directly in business user facing interfaces. It is hoped that this will contribute to standardizing the terminology that a user of e-procurement solutions faces across different platforms.	Clarification
	Re-mapped fields	Buyer’s reference has been re-mapped from cbc:BuyerCustomerParty.Party.Contact.ID to cbc:BuyerReference	Breaking change - EN16931 conformance
		Excise taxes have been moved from the Tax elements to the AllowanceCharge elements.	Breaking change - EN16931 conformance
	Calculation changes	Line level AllowanceCharge now enters into the calculation of the LineExtensionAmount, where before it was purely informative.	Breaking change - EN16931 conformance
		TaxExclusiveAmount was used incorrectly in OIOUBL 2. This has been revised to conform to the Norm.	Breaking change - EN16931 conformance
		Negative credit notes are no longer permitted. Previously this was permitted to support conversion from Peppol Credit Note, but in OIOUBL 3 negative Peppol credit notes should be converted to invoices instead.	Breaking change
		Invoice Due Date is now mandatory for documents where a due date is mandatory. PaymentMeans.PaymentDueDate is prohibited, PaymentTerms.PaymentDueDate is unsupported. PaymentTerms.PaymentDueDate only makes sense when there are multiple payment terms, which is currently unsupported in the Norm. If and when multiple payment terms are permitted, this will be revisited.	Breaking change - EN16931 conformance
		VAT calculations and labeling now follow the EN16931 definitions and calculation logic.	Breaking change - EN16931 conformance
		Only one tax total with tax subtotals may be provided. Tax subtotals are only used for the calculation of VAT in the document currency. The VAT amount in the tax currency is simply the VAT total converted into the tax currency.	Breaking change
		One or more TaxTotal classes must be present on line level.	Breaking change
		Document- and sub-totals now calculated according to the EN16931 calculation logic.	Breaking change - EN16931 conformance
		Use of OrderableUnitFactorRate is not supported under EN16931	Breaking change - EN16931 conformance
		Only one item price discount is supported under EN16931	Breaking change - EN16931 conformance
	Field definitions/data quality	A number of fields are now required to be non-negative. In particular, item net prices are no longer allowed to be negative.	Breaking change - EN16931 conformance
		Invoiced/credited quantities may no longer be 0.	Breaking change
		Empty fields are no longer permitted. All instances of classes and fields must have content.	Breaking change - EN16931 conformance
		Invoice.OrderReference is mandatory when OrderLineReference class is present	Breaking change
		Validation rules for completeness of address information have been substantially tightened. Addresses are now expected to be provided in structured format and fully specified. In particular, tests against historical production data have flagged incomplete DeliveryLocation.Address information. This will cause validation failure in OIOUBL 3.	Breaking change
		A number of fields are now bound to specific or different code lists. In particular, tests against anonymized historical production data have identified the following prohibited practices currently in use: BR-CL-03 currencyID MUST be coded using ISO code list 4217 alpha-3 BR-CL-17 Invoice tax categories MUST be coded using UNCL5305 code list BR-CL-23 Unit code MUST be coded according to the UN/ECE Recommendation 20 with Rec 21 extension OIOUBL-BIL-005 For Danish suppliers the following Payment means codes are allowed: 1, 10, 31, 42, 48, 49, 50, 58, 59, 93 and 97 OIOUBL-BIL-010For Danish Suppliers the PaymentID is mandatory and MUST start with 71#, 73# or 75# (kortartkode) and PayeeFinancialAccount/ID (Kreditornummer) is mandatory and must be exactly 8 characters long, when Payment means equals 93 (FIK) OIOUBL-COMMON-141 MathematicOperatorCode must be either 'multiply' or 'divide' PEPPOL-EN16931-R101 Element Document reference can only be used for Invoice line object	Breaking change
		cac:StandardItemIdentification/cbc:ID requires a schemeID attribute (to specify which standardized taxonomy is used).	Breaking change
		Money amounts must have no more than two decimal places, and exchange rates must have exactly four decimal places.	Breaking change
		Line IDs must now be unique to within the document. The schematron validates only to the first 5000 lines of a document, because this validation rule has very bad scaling properties, but the business rule applies to all line IDs in a given document.	Breaking change
		AdditionalDocumentReference may only have SchemeIdentifier for InvoiceObjectIdentifiers.	Breaking change - EN16931 conformance
	Allowance/charges	Allowances must now have a reason or a reason code.	Breaking change - EN16931 conformance
	Payment	For Danish suppliers PaymentMandate/ID and PayerFinancialAccount/ID are mandatory when payment means is 49	Breaking change
		It is now mandatory to distinguish between the bank branch to which a bank account is registered, and the corporate identity of the bank to which the branch belongs.	Breaking change
		Multiple payment terms not supported under EN16931	Breaking change - EN16931 conformance
		Multiple payment means with different payment means codes not supported under EN16931	Breaking change - EN16931 conformance
		For the sake of backward compatibility, PaymentChannelCode is retained for several PaymentMeansCodes where there is no ambiguity to resolve. This use is permitted, but is considered deprecated and may be removed in future revisions.	Formal notice
	Excluded fields	A number of fields have been excluded that were previously permitted. In particular, the Person class is universally banned (for reasons of data protection), and several fields that are duplicative of data structures found elsewhere in the schema have been excluded. For example, UBL contains a payment due date in both PaymentMeans and PaymentTerms, but the one in PaymentMeans has been excluded as duplicative in OIOUBL.	Breaking change
		Fields that were only excluded in OIOUBL 2 to maintain backwards compatibility (because they were introduced in a later UBL version than OIOUBL 2 supported) have been un-excluded.	Breaking change

Release

Issue

Description

Type

Version 3.0.0.RC

N/A

Initial update of OIOUBL 3 BIS Billing With Response

New

Separation of message level and business level responses

In OIOUBL 2, message and business level responses both used the ApplicationResponse document. OIOUBL 3 has split these into different customization IDs and profiles, to improve clarity regarding choreography and parties.

OIOUBL 3 Invoice Response follows the Peppol Invoice Response closely in syntax. However, there is a significant difference in choreography: A Peppol Invoice Response must be sent within three business days of receipt of the invoice. An OIOUBL Invoice Response must be sent without undue delay and no later than the parties to the invoice transaction have mutually agreed (if they have agreed on a deadline).

Breaking

Two-way profiles only

In OIOUBL 2, several profiles were available for sending invoices without being able to receive an invoice response. This is not supported in OIOUBL 3, for business users. All institutional end users are expected and required to receive invoice responses at an endpoint registered to their business.

An invoice profile and associated BIS will be published shortly for use by physical persons (who cannot have an endpoint for invoice responses, as this would expose their CPR number to the public). This profile will not be useable for institutional senders.

This change is made in anticipation that it will within the lifetime of IT systems deployed today become mandatory to be able to account for the full life cycle of invoices in a structured manner.

Breaking

Interpretations

The OIOUBL 2 documentation indicated which fields were possible to ingest in a structured manner. In OIOUBL 3, this is no longer indicated. Rather, OIOUBL 3 indicates which values must be shown to the end user, because these fields contain information that the recipient of a document will be deemed to have known in the event of a dispute. This means that a number of free text fields, which are not readily ingestible, are marked as read-mandatory, while a number of structured data fields no longer are.

Semantic change

OIOUBL operates with three different inclusion levels for a data field:
Supported fields have semantic definitions that are given in the relevant BIS and syntax documentation. All service providers implementing OIOUBL are expected to be familiar with these field definitions.
Excluded fields are listed in the syntax documentation, but not usually in the BIS. These must not be used, and will cause validation errors if included.
Unsupported fields are all other data structures that are schema-valid for the underlying UBL, but neither supported nor explicitly excluded. Unsupported fields are not shown in the syntax documentation nor in the BIS. It is permissible for parties to bilaterally agree to the use of unsupported fields, provided the implementation is schema-valid. However, neither end users nor service providers are required or expected to be familiar with these data structures, in the absence of an explicit prior agreement to that effect.

Clarification

Prior versions of OIOUBL documentation used field definitions that were oriented toward technical implementation in EDI solutions, but did not prioritize making explicit the semantic content of the fields. OIOUBL 3 aims to provide field names and definitions which can be used directly in business user facing interfaces. It is hoped that this will contribute to standardizing the terminology that a user of e-procurement solutions faces across different platforms.

Clarification

Re-mapped fields

Buyer’s reference has been re-mapped from cbc:BuyerCustomerParty.Party.Contact.ID to cbc:BuyerReference

Breaking change - EN16931 conformance

Excise taxes have been moved from the Tax elements to the AllowanceCharge elements.

Breaking change - EN16931 conformance

Calculation changes

Line level AllowanceCharge now enters into the calculation of the LineExtensionAmount, where before it was purely informative.

Breaking change - EN16931 conformance

TaxExclusiveAmount was used incorrectly in OIOUBL 2. This has been revised to conform to the Norm.

Breaking change - EN16931 conformance

Negative credit notes are no longer permitted. Previously this was permitted to support conversion from Peppol Credit Note, but in OIOUBL 3 negative Peppol credit notes should be converted to invoices instead.

Breaking change

Invoice Due Date is now mandatory for documents where a due date is mandatory. PaymentMeans.PaymentDueDate is prohibited, PaymentTerms.PaymentDueDate is unsupported. PaymentTerms.PaymentDueDate only makes sense when there are multiple payment terms, which is currently unsupported in the Norm. If and when multiple payment terms are permitted, this will be revisited.

Breaking change - EN16931 conformance

VAT calculations and labeling now follow the EN16931 definitions and calculation logic.

Breaking change - EN16931 conformance

Only one tax total with tax subtotals may be provided. Tax subtotals are only used for the calculation of VAT in the document currency. The VAT amount in the tax currency is simply the VAT total converted into the tax currency.

Breaking change

One or more TaxTotal classes must be present on line level.

Breaking change

Document- and sub-totals now calculated according to the EN16931 calculation logic.

Breaking change - EN16931 conformance

Use of OrderableUnitFactorRate is not supported under EN16931

Breaking change - EN16931 conformance

Only one item price discount is supported under EN16931

Breaking change - EN16931 conformance

Field definitions/data quality

A number of fields are now required to be non-negative. In particular, item net prices are no longer allowed to be negative.

Breaking change - EN16931 conformance

Invoiced/credited quantities may no longer be 0.

Breaking change

Empty fields are no longer permitted. All instances of classes and fields must have content.

Breaking change - EN16931 conformance

Invoice.OrderReference is mandatory when OrderLineReference class is present

Breaking change

Validation rules for completeness of address information have been substantially tightened. Addresses are now expected to be provided in structured format and fully specified. In particular, tests against historical production data have flagged incomplete DeliveryLocation.Address information. This will cause validation failure in OIOUBL 3.

Breaking change

A number of fields are now bound to specific or different code lists. In particular, tests against anonymized historical production data have identified the following prohibited practices currently in use:
BR-CL-03 currencyID MUST be coded using ISO code list 4217 alpha-3
BR-CL-17 Invoice tax categories MUST be coded using UNCL5305 code list
BR-CL-23 Unit code MUST be coded according to the UN/ECE Recommendation 20 with Rec 21 extension
OIOUBL-BIL-005 For Danish suppliers the following Payment means codes are allowed: 1, 10, 31, 42, 48, 49, 50, 58, 59, 93 and 97
OIOUBL-BIL-010For Danish Suppliers the PaymentID is mandatory and MUST start with 71#, 73# or 75# (kortartkode) and PayeeFinancialAccount/ID (Kreditornummer) is mandatory and must be exactly 8 characters long, when Payment means equals 93 (FIK)
OIOUBL-COMMON-141 MathematicOperatorCode must be either 'multiply' or 'divide'
PEPPOL-EN16931-R101 Element Document reference can only be used for Invoice line object

Breaking change

cac:StandardItemIdentification/cbc:ID requires a schemeID attribute (to specify which standardized taxonomy is used).

Breaking change

Money amounts must have no more than two decimal places, and exchange rates must have exactly four decimal places.

Breaking change

Line IDs must now be unique to within the document. The schematron validates only to the first 5000 lines of a document, because this validation rule has very bad scaling properties, but the business rule applies to all line IDs in a given document.

Breaking change

AdditionalDocumentReference may only have SchemeIdentifier for InvoiceObjectIdentifiers.

Breaking change - EN16931 conformance

Allowance/charges

Allowances must now have a reason or a reason code.

Breaking change - EN16931 conformance

Payment

For Danish suppliers PaymentMandate/ID and PayerFinancialAccount/ID are mandatory when payment means is 49

Breaking change

It is now mandatory to distinguish between the bank branch to which a bank account is registered, and the corporate identity of the bank to which the branch belongs.

Breaking change

Multiple payment terms not supported under EN16931

Breaking change - EN16931 conformance

Multiple payment means with different payment means codes not supported under EN16931

Breaking change - EN16931 conformance

For the sake of backward compatibility, PaymentChannelCode is retained for several PaymentMeansCodes where there is no ambiguity to resolve. This use is permitted, but is considered deprecated and may be removed in future revisions.

Formal notice

Excluded fields

A number of fields have been excluded that were previously permitted. In particular, the Person class is universally banned (for reasons of data protection), and several fields that are duplicative of data structures found elsewhere in the schema have been excluded. For example, UBL contains a payment due date in both PaymentMeans and PaymentTerms, but the one in PaymentMeans has been excluded as duplicative in OIOUBL.

Breaking change

Fields that were only excluded in OIOUBL 2 to maintain backwards compatibility (because they were introduced in a later UBL version than OIOUBL 2 supported) have been un-excluded.

Breaking change

OIOUBL BIS Message Level Response

Release	Issue	Description	Type
Version 3.0.0.RC	N/A	Initial update of OIOUBL 3 BIS Message Level Response	New
	Separation of message level and business level responses	In OIOUBL 2, message and business level responses both used the ApplicationResponse document. OIOUBL 3 has split these into different customization IDs and profiles, to improve clarity regarding choreography and parties. OIOUBL 3 Message Level Response follows Peppol Message Level Response closely, with the significant exception that the OIOUBL 3 MLR distinguishes between validation errors (use MLR-Network to report to the sending service provider in C2) and semantic errors that are not caught by schema- or schematron validation (use MLR to report to the sending party’s business system in C1).	Breaking
	Mandatory support for message level responses at business and service provider level	In OIOUBL 2, it is possible to send documents without being able to receive an application response. In OIOUBL 3 this is no longer the case. In OIOUBL 3, it is mandatory for all senders to be able to receive MLRs at two endpoints: A business level endpoint, corresponding to the business level sender (C1), and a service provider technical endpoint (C2). This is to ensure that documents can be repudiated for syntax and semantic errors in a provable and authoritative manner.	Breaking

Release

Issue

Description

Type

Version 3.0.0.RC

N/A

Initial update of OIOUBL 3 BIS Message Level Response

New

Separation of message level and business level responses

In OIOUBL 2, message and business level responses both used the ApplicationResponse document. OIOUBL 3 has split these into different customization IDs and profiles, to improve clarity regarding choreography and parties.

OIOUBL 3 Message Level Response follows Peppol Message Level Response closely, with the significant exception that the OIOUBL 3 MLR distinguishes between validation errors (use MLR-Network to report to the sending service provider in C2) and semantic errors that are not caught by schema- or schematron validation (use MLR to report to the sending party’s business system in C1).

Breaking

Mandatory support for message level responses at business and service provider level

In OIOUBL 2, it is possible to send documents without being able to receive an application response. In OIOUBL 3 this is no longer the case.

In OIOUBL 3, it is mandatory for all senders to be able to receive MLRs at two endpoints: A business level endpoint, corresponding to the business level sender (C1), and a service provider technical endpoint (C2). This is to ensure that documents can be repudiated for syntax and semantic errors in a provable and authoritative manner.

Breaking