UDT Types - UBL Builder

Overview

Unqualified Data Types (UDT) are the foundation of UBL 2.1 type system. These types extend Core Component Types (CCT) and provide concrete implementations for common business data elements. All UDT types are in the namespace urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2.

Type Hierarchy

UDT types inherit from CCT types, which in turn inherit from XML Schema simple types:

XSD Types (XsdString, XsdDecimal, XsdDate, XsdBoolean)
    ↓
CCT Types (CctTextType, CctAmountType, CctCodeType, etc.)
    ↓
UDT Types (UdtText, UdtAmount, UdtCode, etc.)

Text and String Types

UdtText

A character string, generally in the form of words of a language.

content

string

required

The text content

attributes

UdtTextAttributes

Optional attributes for the text element

languageID

string

The identification of the language (e.g., “en”, “es”)

languageLocaleID

string

The locale identifier (e.g., “en-US”, “es-MX”)

import { UdtText } from 'ubl-builder';

const description = new UdtText('Product description');

Extends: CctTextType → XsdString

UdtName

A character string that constitutes the distinctive designation of a person, place, thing or concept.

content

string

required

The name content

attributes

UdtNameAttributes

Optional attributes

languageID

string

Language identifier

languageLocaleID

string

Language locale identifier

import { UdtName } from 'ubl-builder';

const companyName = new UdtName('Acme Corporation');
const personName = new UdtName('John Doe');

Extends: CctTextType → XsdString

Identifier Types

UdtIdentifier

A character string to identify and uniquely distinguish one instance of an object in an identification scheme from all other objects in the same scheme.

content

string

required

The identifier value

attributes

UdtIdentifierAttributes

Optional attributes

schemeID

string

The identification scheme (e.g., “GLN”, “DUNS”)

schemeName

string

The name of the identification scheme

schemeAgencyID

string

The ID of the agency maintaining the scheme

schemeAgencyName

string

The name of the agency maintaining the scheme

schemeVersionID

string

The version of the identification scheme

schemeDataURI

string

URI where the scheme data is located

schemeURI

string

URI where the scheme is located

import { UdtIdentifier } from 'ubl-builder';

const orderId = new UdtIdentifier('ORD-2024-001');

Extends: CctIdentifierType → XsdNormalizedString

Code Types

UdtCode

A character string (letters, figures, or symbols) that for brevity and/or language independence may be used to represent or replace a definitive value or text of an attribute.

content

string

required

The code value

attributes

UdtCodeAttributes

Optional attributes

listID

string

The identification of the code list

listAgencyID

string

The agency maintaining the code list

listAgencyName

string

The name of the agency

listName

string

The name of the code list

listVersionID

string

The version of the code list

name

string

The textual equivalent of the code

languageID

string

The language identifier

listURI

string

URI where the code list is located

listSchemeURI

string

URI where the code list scheme is located

import { UdtCode } from 'ubl-builder';

const currencyCode = new UdtCode('USD', {
  listID: 'ISO4217',
  listAgencyID: 'ISO',
  name: 'US Dollar'
});

Extends: CctCodeType → XsdNormalizedString

Numeric Types

UdtNumeric

Numeric information that is assigned or determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.

content

string

required

The numeric value as a string

attributes

UdtNumericAttributes

Optional attributes

format

string

Whether the number is an integer, decimal, real number, or percentage

import { UdtNumeric } from 'ubl-builder';

const lineCount = new UdtNumeric('42');
const decimalValue = new UdtNumeric('3.14159', { format: 'decimal' });

Extends: CctNumericType → XsdDecimal

UdtPercent

A numeric type specifically for percentage values.

content

string

required

The percentage value

attributes

UdtPercentAttributes

Optional format attribute

format

string

The format of the percentage

import { UdtPercent } from 'ubl-builder';

const taxRate = new UdtPercent('15.5');
const discount = new UdtPercent('10.0');

Extends: CctNumericType → XsdDecimal

UdtRate

A numeric rate value.

content

string

required

The rate value

attributes

UdtRateAttributes

required

Attributes for the rate

format

string

The format of the rate

import { UdtRate } from 'ubl-builder';

const exchangeRate = new UdtRate('1.18', { format: 'decimal' });

Extends: CctNumericType → XsdDecimal

UdtValue

A numeric value type.

content

string

required

The value

attributes

AllowedAttributes

required

Attributes for the value

format

string

The format of the value

import { UdtValue } from 'ubl-builder';

const customValue = new UdtValue('100.50', { format: 'decimal' });

Extends: CctNumericType → XsdDecimal

Monetary and Quantity Types

UdtAmount

A number of monetary units specified using a given unit of currency.

content

string

required

The amount value

attributes

UdtAmountAttributes

Optional attributes

currencyID

string

The currency code (e.g., “USD”, “EUR”)

currencyCodeListVersionID

string

The version of the UN/ECE Rec9 code list

import { UdtAmount } from 'ubl-builder';

const price = new UdtAmount('1000.00', { currencyID: 'USD' });

Extends: CctAmountType → XsdDecimal

The currencyID should follow ISO 4217 currency codes (e.g., USD, EUR, GBP).

UdtQuantity

A counted number of non-monetary units, possibly including a fractional part.

content

string

required

The quantity value

attributes

UdtQuantityAttributes

Optional attributes

unitCode

string

The unit of measure (e.g., “EA”, “KG”, “LTR”)

unitCodeListID

string

The quantity unit code list identifier

unitCodeListAgencyID

string

The agency maintaining the unit code list

unitCodeListAgencyName

string

The name of the agency

import { UdtQuantity } from 'ubl-builder';

const itemCount = new UdtQuantity('100', { unitCode: 'EA' });

Extends: CctQuantityType → XsdDecimal

UdtMeasure

A numeric value determined by measuring an object using a specified unit of measure.

content

string

required

The measurement value

attributes

UdtMeasureAttributes

required

Attributes for the measure (unitCode is required)

unitCode

string

required

The unit of measure (e.g., “MTR”, “KGM”)

unitCodeListVersionID

string

The version of the measure unit code list

import { UdtMeasure } from 'ubl-builder';

const length = new UdtMeasure('150.5', { unitCode: 'MTR' });

Extends: CctMeasureType → XsdDecimal

Unlike UdtQuantity, UdtMeasure requires the unitCode attribute to be specified.

Date and Time Types

UdtDate

A particular point in the progression of time, together with relevant supplementary information.

content

string

required

The date in ISO 8601 format (e.g., “2024-03-15”)

import { UdtDate } from 'ubl-builder';

const issueDate = new UdtDate('2024-03-15');
const dueDate = new UdtDate('2024-04-15');

Extends: XsdDate

UdtTime

An instance of time that occurs every day.

content

string

required

The time in ISO 8601 format (e.g., “14:30:00”)

import { UdtTime } from 'ubl-builder';

const issueTime = new UdtTime('14:30:00');
const deliveryTime = new UdtTime('09:00:00+01:00');

Extends: XsdDate

UdtDateTime

A particular point in the progression of time, combining date and time.

content

string

required

The datetime in ISO 8601 format (e.g., “2024-03-15T14:30:00”)

import { UdtDateTime } from 'ubl-builder';

const timestamp = new UdtDateTime('2024-03-15T14:30:00');
const utcTime = new UdtDateTime('2024-03-15T14:30:00Z');

Extends: XsdDate

Boolean Type

UdtIndicator

A list of two mutually exclusive boolean values that express the only possible states of a property.

content

string | boolean

required

The boolean value (“true”/“false” or true/false)

import { UdtIndicator } from 'ubl-builder';

const isChargeable = new UdtIndicator(true);
const isActive = new UdtIndicator('false');
const hasTaxExemption = new UdtIndicator(false);

Extends: XsdBoolean Methods:

parseToJson(): Returns the indicator in JSON format with #text property

Binary Data Type

UdtBinaryObject

A set of finite-length sequences of binary octets.

content

string

required

The binary data (typically base64 encoded)

attributes

UdtBinaryObjectAttributes

required

Attributes for the binary object (mimeCode is required)

format

string

The format of the binary content

mimeCode

string

required

The MIME type (e.g., “application/pdf”, “image/png”)

encodingCode

string

The decoding algorithm (e.g., “base64”)

characterSetCode

string

The character set if mime type is text

uri

string

URI where the binary object is located

filename

string

The filename of the binary object

import { UdtBinaryObject } from 'ubl-builder';

const pdfDoc = new UdtBinaryObject('JVBERi0xLjQKJeLjz9...', {
  mimeCode: 'application/pdf',
  encodingCode: 'base64',
  filename: 'invoice.pdf'
});

Extends: CctBinaryObjectType → XsdNormalizedString

Common Patterns

Importing Types

import {
  UdtAmount,
  UdtCode,
  UdtText,
  UdtIdentifier,
  UdtDate,
  UdtTime,
  UdtQuantity,
  UdtIndicator
} from 'ubl-builder';

Type Attributes

All attribute types are also exported and can be used for type safety:

import { 
  UdtAmountAttributes,
  UdtCodeAttributes,
  UdtTextAttributes 
} from 'ubl-builder';

const attributes: UdtAmountAttributes = {
  currencyID: 'USD',
  currencyCodeListVersionID: '2001'
};

const amount = new UdtAmount('1000.00', attributes);

Method Chaining

Some types support method chaining for setting attributes:

import { UdtText } from 'ubl-builder';

const text = new UdtText('Hello')
  .setLanguageID('en')
  .setLanguageLocaleID('en-US');

JSON Serialization

Most types provide a parseToJson() method:

import { UdtAmount } from 'ubl-builder';

const amount = new UdtAmount('1000.00', { currencyID: 'USD' });
const json = amount.parseToJson();
// { "#text": "1000.00", "@currencyID": "USD" }

CCT Types

Core Component Types that UDT types extend

Invoice Builder

Using UDT types in invoice documents

References

UBL 2.1 Specification
Datypic UBL 2.1 Reference
UBL Schema: common/UBL-UnqualifiedDataTypes-2.1.xsd
Namespace: urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2

Schema Documents

Common Aggregate Components

Data Types

Extensions

Utilities

​Overview

​Type Hierarchy

​Text and String Types

​UdtText

​UdtName

​Identifier Types

​UdtIdentifier

​Code Types

​UdtCode

​Numeric Types

​UdtNumeric

​UdtPercent

​UdtRate

​UdtValue

​Monetary and Quantity Types

​UdtAmount

​UdtQuantity

​UdtMeasure

​Date and Time Types

​UdtDate

​UdtTime

​UdtDateTime

​Boolean Type

​UdtIndicator

​Binary Data Type

​UdtBinaryObject

​Common Patterns

​Importing Types

​Type Attributes

​Method Chaining

​JSON Serialization

​Related Documentation

CCT Types

Invoice Builder

​References

Build docs developers (and LLMs) love

Overview

Type Hierarchy

Text and String Types

UdtText

UdtName

Identifier Types

UdtIdentifier

Code Types

UdtCode

Numeric Types

UdtNumeric

UdtPercent

UdtRate

UdtValue

Monetary and Quantity Types

UdtAmount

UdtQuantity

UdtMeasure

Date and Time Types

UdtDate

UdtTime

UdtDateTime

Boolean Type

UdtIndicator

Binary Data Type

UdtBinaryObject

Common Patterns

Importing Types

Type Attributes

Method Chaining

JSON Serialization

Related Documentation

References