200OIOUBL General Design Principles

v3.0.0 RC

1. Document Structure

This document is structured as follows:

  • Chapter 2 Outlines the purpose of this document.

  • Chapter 3 Describes special profiles for use by physical persons.

  • Chapter 4 Provides general principles for syntax bindings

  • Chapter 5 Describes the primitive and semantic data types

  • Chapter 6 Statement of license and copyright

  • Chapter 7 Link to the main site for additional documentation

2. Purpose of this document

A number of design principles, specifications and rules apply across the entire OIOUBL 3 set of Business Interoperability Specifications. Rather than reiterate these in every BIS document, they are collected here.

In the event of conflict between an individual BIS document and this document, the rules and specifications in this document prevail, unless it is explicitly noted in the BIS that the divergence is intentional, in which case the rule or specifiation in the BIS prevails. Readers are encouraged to report any conflicts to the Danish Business Authority’s Nemhandel team, so they may be resolved.

3. One-way profiles for physical persons

The standard OIOUBL 3 profile for exchange of electronic business documents (and the namesake of most of the corresponding BISes) is the Document with Response, in which it is mandatory for all senders of business documents to be capable of receiving the corresponding business level response.

This is problematic for the use of OIOUBL 3 documents by physical persons, as registering for receiving business level responses requires exposing the sender’s legal identifier. The legal identifiers of physical persons are protected personal information, which ought not be exposed in a public dynamic discovery database.

For this reason, where relevant, OIOUBL 3 BISes include profiles for use by physical persons. These profiles do not require (or permit) the use of structured business level responses through the Nemhandel network. Such business level responses must be communicated through other channels.

The choreography of private-without-response profiles is as follows:

  • The receiver of the primary business document (the customer in an invoice transaction, the supplier in an order transaction, etc.) registers to receive on the profile.

  • The sender of the primary business document (the supplier in an invoicing transaction or the buyer in an ordering transaction) does not register anything, as no business level response is supported by the profile.

  • The sender sends the primary business document to the receiver, but any business level response must be communicated from receiver to sender through other channels (e.g. e-mail).

  • Semantic errors in the business document must likewise be communicated to the sender’s service provider through other channels, as the Message Level Response shares the endpoint identifier of the business level response.

  • Syntax errors in the business document are communicated through the Message Level Response - Network as normal, as the business document must still have passed through a Nemhandel access point, which should have performed syntax validation.

One-way profiles for physical persons MUST NOT be used by non-physical legal persons to send business documents.

4. Principles for syntax documentation

OIOUBL operates with three different inclusion levels for UBL elements:

Supported elements 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 elements 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 elements 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.

4.1. Syntax bindings

The OIOUBL 3 syntax documentation consists of the following information for supported elements:

  • UBL element name: The XML tag used to enclose the element in a file. This tag is identical to the OASIS UBL.

  • Parent and daughter element(s): Element names are prefixed by either cac:, cbc: or @.

    • cac: indicates that the element is an aggregate, consisting of other elements. Aggregates are used to structure and group fields.

    • cbc: indicates that the element is a field. Fields contain data points.

    • @ indicates the element is an attribute. Attributes are properties of fields. Attributes provide context for the field value, such as a unit of measure or an address scheme.

  • Cardinality: An element may be limited in how many times it may or must appear within each instance of its parent element.

    • Cardinality for classes and fields is indicated by either an integer or a range. Ranges are indicated as [integer]..[integer or 'n'], where 'n' indicates no upper limit.

    • Cardinality for attributes is indicated as either O (Optional) or M (Mandatory).

  • Exclusion indicator: Indicates that a field is excluded, and may not be used.

  • Read-mandatory indicator: Indicates that the field is read-mandatory.

  • Data type: Specifies the semantic data type of the field.

  • Description: The semantic content of the field. Provided in Danish and English. In the event of discrepancies between the Danish and English descriptions, the reader is asked to contact the Danish Business Authority for clarification and errata.

  • Rules: Schematron rules applying to the field or aggregate.

Read-mandatory fields contain information that must be shown to the end user, by the receiving service provider(s). These fields contain information that the recipient of a document will be deemed to have known in the event of a dispute between the end users party to the communication.

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.

5. Data types

Semantic data types are used to bridge the gap between the semantic concepts expressed by the information elements and the technical implementation. The semantic data types define the allowed value domain for the content, and any additional information components (attributes) needed in order to ensure a precise interpretation of the content.

5.1. Primitive data types

Semantic data type content may be of the following primitive types. These primitive types were taken from ISO 15000-5:2014, Annex A.

Primitive type Definition

Binary

A set of finite-length sequences of binary digits.

Date

Time point representing a calendar day on a time scale consisting of an origin and a succession of calendar ISO 8601:2004.

Decimal

A subset of the real numbers, which can be represented by decimal numerals.

String

A finite sequence of characters.

5.2. Semantic data types

The semantic data types are described in the tables below, where various features such as attributes, format, and decimals as well as the basic type are defined for each semantic data type. They are based on ISO 15000-5:2014.

When used in an instance document, each data element will contain data. In the tables below this is identified as the “content”. Whenever a business term is used this term shall always have content and therefore the content is always mandatory.

5.2.1. Integer

Signed integer of up to 12 digits.

The sign may be restricted by semantic context.
Component Use Primitive Type Example

Content

Mandatory

Decimal

-123456789012

5.2.2. Numeric

Signed floating point with up to twelve significant figures.

The sign and number of decimal places may be limited by the semantic context.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.2515

5.2.3. Amount

An amount states a numerical monetary value. The currency of the amount is defined as a separate business term.

Amount is floating up to two fraction digits.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.25

5.2.4. Unit Price Amount

A unit price amount states a numerical monetary amount value for data elements that contain item prices that may be multiplied by item quantities. The currency of the amount is defined as a separate business term.

Unit price amount does not set restrictions on number of decimals, as contrast to the Amount type
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

5.2.5. Rate

Unsigned floating point with up to four decimal places precision.

Component Use Primitive Type Example

Content

Mandatory

Decimal

12.3456

5.2.6. Percentage

Percentages are given as fractions of a hundred (per cent) e.g. the value 34.78 % in percentage terms is given as 34.78.

No restriction on number of decimals for percentages.
Component Use Primitive Type Example

Content

Mandatory

Decimal

34.7812

5.2.7. Quantity

Quantities are used to state a number of units such as for items. The code for the Unit of Measure is defined as a separate business term.

No restriction on the number of decimals for quantities.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

5.2.8. Code

Codes are used to specify allowed values in elements as well as for lists of options. Code is different from Identifier in that allowed values have standardized meanings and gives clarity to the recipient.

Codes shall be entered exactly as shown in the selected code list
Component Use Primitive Type Example

Content

Mandatory

String

Abc123

5.2.9. Identifier

Identifiers (IDs) are keys that are issued by the sender or recipient of a document or by a third party.

The use of the attributes is specified for each information element.
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

Scheme identifier

Conditional

String

0088

Scheme version identifier

Conditional

String

1.0

5.2.10. Date

Dates shall be in accordance to the 'Calendar date complete representation' as specified by ISO 8601:2004, format YYYY-MM-DD.

Dates shall not include timezone information.
Table 1. EN 16931_ Date. Type
Component Use Primitive Type Example

Content

Mandatory

Date

2024-12-01

5.2.11. Time

Time shall be in accordance with the 'Extended time format' as specified by ISO 8601:2004, format [hh]:[mm]:[ss].

Time shall not include time zone information. Decimal fraction on seconds SHALL not be used.
Table 2. EN 16931_ Time. Type
Component Use Primitive Type Example

Content

Mandatory

Time

09:30:12

5.2.12. Document Reference

Document Reference Types are identifiers that were assigned to a document or document line.

Table 3. Document Reference. Type
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

5.2.13. Short String

Text is the actual wording of anything written or printed. Line breaks in the text must not be present. Maximum length of short string is 64 characters.

Short String shall contain only charactes supported by the UTF-8 character set.

Component Use Primitive Type Example

Content

Mandatory

String

Product Name

5.2.14. Long String

Free text field for longer descriptions or annotations. Line breaks in the text may be present, and any line breaks must be preserved and respected by the receiver’s system. Maximum length of a Long String is 1024 characters.

Long String shall contain only charactes supported by the UTF-8 character set.

Component Use Primitive Type Example

Content

Mandatory

String

5% allowance when paid within 30 days

5.2.15. Text

Text is the actual wording of anything written or printed. Line breaks in the text may be present, and any line breaks should be preserved and respected by the receiver’s system.

Text fields have no length limits.

Text data type should not be used in OIOUBL, but is included here for completeness/compatibility reasons.

Component Use Primitive Type Example

Content

Mandatory

String

5% allowance when paid within 30 days

5.2.16. Binary objects

Binary objects can be used to describe files which are transmitted together with the business document. Attachments shall be transmitted together with the business document. The binary object has two supplementary components: a Mime Code, which specifies the Mime type of the attachment and a Filename that is provided by (or on behalf of) the sender of the business document.

Component Use Primitive Type Example

Content

Mandatory

Binary

QmFzZTY0IGNvbnRlbnQgZXhhbXBsZQ==

Mime Code

Mandatory

String

image/jpeg

Filename

Mandatory

String

drawing5.jpg

5.2.17. Indicator

Boolean used to specify whether the property is true or false. Must have either true or false as their value. The semantic meaning of the truth or falsity of the property is described in the field description.

Component Use Primitive Type Example

Content

Mandatory

String

true

6. OIOUBL License and Statement of Copyright

License & Copyright Statement

7. Links to main site of documentation

OIOUBL 3 Main documentation site