Skip to main content

​
Overview

UBL Extensions allow you to add custom content to UBL documents. The extension system consists of two main components:
  • UBLExtensions - Container for multiple extension entries
  • UBLExtensionType - Individual extension with metadata and content
Extensions enable you to include vendor-specific data, regulatory requirements (like DIAN extensions), or any custom information not covered by standard UBL fields.

​
UBLExtensions

The main container class for managing extension entries in a UBL document.

​
Constructor

import { UBLExtensions } from 'ubl-builder';

const extensions = new UBLExtensions({
  UBLExtensions: extensionType // Optional
});
​
UBLExtensions
UBLExtensionType
A single extension for private use. Can be added using the constructor or the addUBLExtension() method.

​
Methods

​
addUBLExtension()

Add an individual extension to the container. 
addUBLExtension(value: UBLExtensionType | UBLExtensionTypeParams): void
​
value
UBLExtensionType | UBLExtensionTypeParams
required
Extension instance or parameters object to add to the extensions container.
Example: 
import { UBLExtensions, UBLExtensionType } from 'ubl-builder';

const extensions = new UBLExtensions();

extensions.addUBLExtension({
  id: 'extension-001',
  name: 'Custom Extension',
  extensionContent: customContent
});

​
getDianUblExtension()

Retrieve the first extension from the container (commonly used for DIAN extensions). 
getDianUblExtension(): UBLExtensionType | null
Returns: The first UBLExtensionType in the container, or null if no extensions exist. Example: 
const dianExtension = extensions.getDianUblExtension();
if (dianExtension) {
  console.log('DIAN extension found:', dianExtension);
}

​
UBLExtensionType

Represents a single extension with metadata and content.

​
Constructor

import { UBLExtensionType } from 'ubl-builder';

const extension = new UBLExtensionType({
  id?: string | UdtIdentifier,
  name?: string | UdtName,
  extensionAgencyID?: string | UdtIdentifier,
  extensionAgencyName?: string | UdtText,
  extensionVersionID?: string | UdtIdentifier,
  extensionAgencyURI?: string | UdtIdentifier,
  extensionURI?: string | UdtIdentifier,
  extensionReasonCode?: string | UdtCode,
  extensionReason?: string | UdtText,
  extensionContent?: AnyExtensionContent  // Required
});

​
Parameters

​
id
string | UdtIdentifier
An identifier for the extension assigned by the creator.UBL Field: cbc:ID
​
name
string | UdtName
A name for the extension assigned by the creator.UBL Field: cbc:Name
​
extensionAgencyID
string | UdtIdentifier
Identifier for the agency that maintains the extension.UBL Field: ext:ExtensionAgencyID
​
extensionAgencyName
string | UdtText
Name of the agency that maintains the extension.UBL Field: ext:ExtensionAgencyName
​
extensionVersionID
string | UdtIdentifier
Version identifier for the extension.UBL Field: ext:ExtensionVersionID
​
extensionAgencyURI
string | UdtIdentifier
URI for the agency that maintains the extension.UBL Field: ext:ExtensionAgencyURI
​
extensionURI
string | UdtIdentifier
URI for the extension.UBL Field: ext:ExtensionURI
​
extensionReasonCode
string | UdtCode
Code indicating why the extension is being included.UBL Field: ext:ExtensionReasonCode
​
extensionReason
string | UdtText
Description of the reason for including the extension.UBL Field: ext:ExtensionReason
​
extensionContent
AnyExtensionContent
required
The actual extension content. This is where custom data is stored.UBL Field: ext:ExtensionContent

​
Methods

​
setExtensionContent()

Set or update the extension content. 
setExtensionContent(value: AnyExtensionContent): void
​
value
AnyExtensionContent
required
Extension content instance (e.g., DianExtensions or custom content).
Example: 
import { UBLExtensionType, DianExtensions } from 'ubl-builder';

const extension = new UBLExtensionType({
  id: 'dian-001',
  name: 'DIAN Extension'
});

const dianContent = new DianExtensions({
  dianExtensions: dianExtensionsContent
});

extension.setExtensionContent(dianContent);

​
getExtensionContent()

Retrieve the extension content. 
getExtensionContent(): AnyExtensionContent
Returns: The extension content object.

​
Usage Examples

​
Creating a Basic Extension

import { UBLExtensions, UBLExtensionType } from 'ubl-builder';

// Create extension container
const extensions = new UBLExtensions();

// Add a custom extension
extensions.addUBLExtension({
  id: 'custom-001',
  name: 'Custom Metadata',
  extensionAgencyName: 'My Company',
  extensionContent: customContent
});

​
Adding Multiple Extensions

import { UBLExtensions, UBLExtensionType } from 'ubl-builder';

const extensions = new UBLExtensions();

// Add first extension
extensions.addUBLExtension({
  id: 'ext-001',
  name: 'Extension 1',
  extensionContent: content1
});

// Add second extension
extensions.addUBLExtension({
  id: 'ext-002',
  name: 'Extension 2',
  extensionContent: content2
});

​
Using Extensions in a Document

import { Invoice, UBLExtensions, DianExtensions } from 'ubl-builder';

// Create extensions
const extensions = new UBLExtensions();
extensions.addUBLExtension({
  extensionContent: new DianExtensions({
    dianExtensions: dianContent
  })
});

// Add to invoice
const invoice = new Invoice({
  UBLExtensions: extensions,
  // ... other invoice fields
});
The extensionContent parameter is required for UBLExtensionType. All extension content must extend the AnyExtensionContent base class.
When using setExtensionContent(), the value must be an instance of AnyExtensionContent. Passing any other type will throw an error.

Build docs developers (and LLMs) love

Get started for freeTalk to us