© Ribose Asia Limited 2025
This document is not a Ribose Standard. It is distributed for review and comment, and is subject to change without notice and may not be referred to as a Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
Ribose Asia Limited
Suite 1, 8/F, New Henry House
10 Ice House Street
Central
Hong Kong
www.ribose.com
This specification defines the Label Auto-assignment Definition Language (LADL), a
declarative modeling language for defining automatic label assignment requirements
across technical documentation and publishing systems. ”LADL” is pronounced as “ladel”.
Label auto-assignment is a critical component of structured documentation, enabling consistent referencing and organization of content elements throughout a document. The act is to automatically create correct Label objects that attach to the content element. A Labeller creates a string label from a Label object, depending on the usage context (e.g., the same item can be labelled differently in different parts of the content hierarchy).
LADL addresses these challenges with:
platform-independent labeling model that works consistently across rendering engines
built-in support for international labeling systems (including CJK)
hierarchical labeling with contextual awareness and scope binding
clear separation between semantic structure and presentation formatting
support for transformations to CSS, Word Styles, and XSLT labellers
string pattern interpolation for flexible label construction
LADL enables document architects and standards developers to define once and apply everywhere, ensuring that labeling schemes work predictably across all outputs while preserving both semantic structure and visual presentation requirements.
This document defines a label definition language called the “Label Auto-assignment Definition Language” (LADL) for defining auto-labeling schemes.
It also defines requirements for auto-labeling systems that can perform the necessary labeling activity based on the defined schemes.
It is a platform-independent, language-agnostic labeling model, allowing defined schemes to be deployed towards various rendering formats.
For the purposes of this document, the following terms and definitions apply.
machine-readable object that attaches to a content element for consistent and unambiguous reference of information in an information container
A label like “1.1.2” indicates it is the “first clause in document, first subclause, second subsubclause”, while “Figure A.2” means it is the second image in Annex A.
numeric or alphanumeric variable that tracks sequence position within a document context
ordered progression of values following defined rules for generation and formatting
rules for representing a labeller value in a particular alphanumeric system
Arabic numerals, Roman numerals, alphabetic characters.
document boundary within which a labeller operates, defining when the labeller resets or continues
process of substituting variable placeholders in a pattern with actual values to construct a rendered label
template combining labeller values and literal characters to form string labels
“Figure %n” is a template that generates labels like “Figure 1”, “Figure 2”, etc.
labeling system where elements inherit context from parent elements
In a labeling system, “1.1.2” can represent the locality of “section 1, subsection 1, clause 2”.
component that assigns labels to content elements based on their position in the document structure and labeling context, and generates a human-readable label in string form from a label object
general term for pointing to specific content elements using labels, enabling navigation, identification, and citation
reference to content within the same context or document section, using labels to provide precise location information
reference to content across different contexts or document sections, using labels to provide unambiguous identification regardless of location
formal reference to content using labels, enabling precise identification in both internal and external referencing systems
Labels serve as the foundation for consistent and unambiguous reference of information within documents.
Their primary purpose is to enable:
Precise navigation through hierarchical document structures
Unambiguous identification of content elements regardless of their position
Citation systems that work both internally and externally to the document
Labels provide machine-readable identifiers that can be rendered in human-readable form, allowing both automated systems and human readers to locate and reference specific content with precision.
A consistent, predictable auto-labeling language enables consistent, predictable auto-labeling with the following benefits:
Preserving semantic relationships between labeled elements
Adapting to different display requirements by format
Supporting internationalization requirements
Allowing for hierarchical labeling schemes
Enabling flexible formatting of labels
Managing labeller scopes across document boundaries
Ability to deploy to different rendering engines, such as CSS, Word Styles, and XSLT.
LADL follows these fundamental design principles:
Numbers represent both position in a sequence and visual labeling. These concerns must be separable for proper processing.
Labeling systems must understand their position within content hierarchies.
The model must define labeling in a way that can be consistently applied across multiple forms of media.
The defined labeling system must not depend on any specific rendering engine or language outside of LADL.
Non-Latin labeling systems, including right-to-left languages, must be fully supported.
Support for complex labeling schemes required by standards organizations.
The process of resolving references involves:
Identification: Determining the target element based on its label
Context mapping: Understanding the relationship between the reference context and the target context
Rendering: Presenting the reference in an appropriate format for the current context
The LADL model provides the foundation for this resolution process by ensuring that labels are:
Unique: Each label uniquely identifies a specific content element
Structured: Labels follow a consistent structure that reflects the document hierarchy
Context-aware: Labels can be interpreted correctly regardless of where they appear
Labels support different types of references depending on their scope and usage:
Global references point to content across different contexts
Local references point to content within the same context
Citations provide formal references to external content
A global reference label is a unique reference that refers to content scoped within an information container.
Global references require string labels that include all necessary context information to ensure unambiguous identification.
A label reference is considered fully-qualified as a global reference if:
All its labeling contexts are shown in the label
The label uniquely refers to a content element within the container
A reference from Annex A to “Figure 3.2” clearly identifies the second figure in Clause 3, regardless of where the reference appears.
A local reference label is a unique reference that refers to content scoped within a part of the information container.
Within Clause 3, a reference to a list item “a)” is a local reference instead of the global reference counterpart of “Clause 3, a)”.
Local references can be preferred over global references when referring content within the same context is more concise for the reader, due to omission of the duplicated self-reference.
Within a list, a reference to “a)” is more concise than “List 1, a)”.
Citations are external references to the information container that the labels are attached to.
Citations to labelled content in the current environment may be created by external document references or in bibliographic entries.
For external users to create consistent citations to the content, the labels must be predictable and consistent across different documents.
The LADL language runtime is responsible for interpreting and executing label auto-assignment definitions. The runtime:
Processes LADL definitions to create a label assignment model
Maintains labeller states and sequences throughout document processing
Manages context hierarchies and inheritance relationships
Executes label generation according to defined patterns
Handles format-specific rendering requirements
The LADL architecture consists of:
Core models
Hierarchical context management
Context hierarchy framework
Hierarchical pattern interpolation
This diagram demonstrates how:
The LabelingContext is different from the actual content hierarchy
Elements may be labeled according to a higher label context even if they belong to a lower document hierarchy
Some elements are labeled according to label contexts belonging to the document hierarchy
The diagram illustrates the critical distinction between content hierarchy and label context in the LADL model:
Double dashed lines represent content hierarchy (e.g., document containing clauses containing subclauses)
Unlabeled directional lines represent ownership (e.g., document owning a ClauseLabeller and an AnnexLabeller)
Lines labeled “Parent” show labeller inheritance relationships between parent and child labellers
Lines labeled “Labels” show where a Labeller/Labeller assigns a Label to a content element
The diagram also illustrates the 3 key model trees in the LADL model:
Content tree: Contains models that can be used to contain ContentElements that have Labels. These are boxes in white.
Context tree: Made of LabelContext objects that provide label contexts. These are the boxes in brown.
Labeller tree: Made of Labeller objects that allow hierarchical labeling. These are boxes in blue.
The core models in the LADL language framework are:
Label: Represents a label assigned to a content element
Labeller: Transforms a label template into a final label string
Sequence: Defines the progression of values for a labeller
LabelContext: Defines the scope and type of label context for labeling elements
LabelTemplate: Defines how labeller values are combined with fixed text to create labels
In this document, we define the following models for illustration purposes of the LADL language:
ContentElement: Represents a content element in an information container
The following 3 model trees exist in the LADL model:
Content tree: an object tree that contains models that can be used to contain ContentElements that have Labels.
Context tree: an object tree made of LabelContext objects (linked via the parent attribute) that provides label contexts.
Labeller tree: an object tree made of Labeller objects (linked via the parent attribute) that allows hierarchical labeling.
The following diagrams illustrate the key relationships in the LADL model.
The ContentElement class represents a content element in an information container that can potentially hold a LabelContext object.
The type attribute is used to match whether a Labeller can label it.
A ContentElement must be associated with a LabelContext object if it has children to be labeled.
Every ContentElement that can either:
Serve as a label context
Be labeled
A sequence defines the progression of values used for labeling.
There are two types of Sequence models that inherit from Sequence:
CharacterSequence: Defines a fixed sequence of characters
NumericSequence: Defines a monotonic sequence of numerical values
A LADL-compliant runtime should provide the following default labeling sequences:
Standard decimal numbers (1, 2, 3…)
Uppercase Roman numerals (I, II, III…)
Lowercase Roman numerals (i, ii, iii…)
Uppercase letters (A, B, C…)
Lowercase letters (a, b, c…)
Uppercase Cyrillic alphabet characters (А, Б, В, Г, Д, Е, Ж, З…)
Lowercase Cyrillic alphabet characters (а, б, в, г, д, е, ж, з…)
Uppercase Greek alphabet characters (Α, Β, Γ, Δ, Ε, Ζ, Η, Θ…)
Lowercase Greek alphabet characters (α, β, γ, δ, ε, ζ, η, θ…)
Chinese numerals (一, 二, 三…)
Japanese numerals (一, 二, 三…)
Korean numerals (일, 이, 삼…)
Arabic numerals in Arabic script (١, ٢, ٣…). This is a sequence of RTL numbers.
Hebrew numerals (א, ב, ג…). This is a sequence of RTL numbers.
The following definition describes a custom numeral sequence based on ArabicNumericSequence that jumps every 3 positions.
Produces a sequence of “1, 4, 7, 10, …”.
The following definition describes a custom numeric sequence based on Chinese numeric sequence only giving even numbers.
Produces a sequence of “二, 四, 六, 八, …”.
Certain ancient texts apply a labeling system of [”元“, “亨“, “利“, “貞“] as book labels if there are 4 books in a series. The following definition applies the expansion rule “prepend_prefix” to the sequence.
Produces a sequence of “元, 亨, 利, 貞, 乾元, 乾亨, 乾利, 乾貞, 坤元, 坤亨, …”.
Greek literature uses the Greek alphabet and numerals for labeling, which includes both letters and specific numeral characters for enumeration. The following definition applies the expansion rule “double_character” to the sequence.
Produces a sequence of “α, β, γ, δ, ε, ζ, η, θ, αα, ββ, γγ, δδ, εε, …”.
The LabelTemplate class defines how string labels are constructed from labeller values and fixed text.
The pattern attribute is a string that contains placeholders for labeller values and any fixed text necessary.
The following placeholders are supported:
Labeller value
The pattern "Figure %n" may generate labels like “Figure 1”, “Figure 2”, “Figure 3”, etc.
Parent labeller value
The pattern "Figure %pn.%n", where the parent is a labeller for an Annex context, may generate the labels “Figure A.1”, “Figure B.2”, “Figure C.3”.
Rendered global label value of parent.
The pattern “%parent, List %n”, where the parent is a labeller for a Clause context, may generate the labels “Clause 1, List 1”, “Clause 1, List 2”, “Clause 2, List 1”, etc.
Rendered local label value of self.
The pattern “%self” in a Clause labeller context, where the local reference template is “Clause %n”, may generate the label “Clause 1”, “Clause 2”, “Clause 3”.
The direction attribute defines the direction of the pattern string, which can be either “ltr” (left-to-right) or “rtl” (right-to-left).
The following definition describes a label template for unordered lists with no string interpolation.
The following definition describes a label template for figures that uses the labeller value.
Output: “Figure 1”, “Figure 2”, “Figure 3”, etc.
The following definition describes a label template for clauses that uses the labeller value.
If parent clause is labelled as “二“, the sequence is the JapaneseNumericSequence, the output would be “二の一“, “二の二“, “二の三“, etc.
If parent clause is labelled as “二の三“, the sequence is the JapaneseNumericSequence, the output would be “二の三の一“, “二の三の二“, “二の三の三“, etc.
A label template can be in a RTL direction. The following rules apply:
Numbers flow correctly from right-to-left
Hierarchical labels maintain proper RTL rendering
Global references preserve the RTL format when used in different contexts
Arabic documents use right-to-left (RTL) text direction.
The values would be:
The condition attribute is a LabelContextCondition object that defines the condition for selecting the pattern.
If the condition is met, the pattern is selected.
If multiple patterns have conditions that are met, the first pattern is selected.
It is crucial to note that it is possible to create multiple matching templates that have overlapping conditions.
A template with a condition of “element_count_gt” and a threshold of 1, and another template with a condition of “element_count_eq” and a threshold of 2, overlap when the count is equal to 2.
If no conditions are met, the first pattern is selected.
The LabelContextCondition class defines a context condition for a labeller to determine which pattern to use.
In some labeling systems, the labeller may need to switch between different conditions based on the defined thresholds.
In the ISO/IEC labelling system, a “NOTE” label takes on these forms depending on the number of notes in a clause:
“NOTE” if there is only one note
“NOTE 1”, “NOTE 2” if there are more than one notes
This is only used for conditional label templates.
The LabelContext class defines the scope of labeling (and a label hierarchy) within an information container.
The name attribute is a string that identifies the label context.
The parent attribute is a reference to the parent label context to which this label context relates.
The element attribute is a reference to the content element associated with the label context.
The labellers attribute is a collection of Labeller objects that are bound to this label context.
The following definition describes a label context for a document clause that contains a labeller for figures.
The Labeller model defines the fundamental mechanism for tracking sequence position within a label context.
The following definition describes a labeller for unordered lists with no string interpolation.
The values would be:
For hierarchical labeling, a Labeller may have a parent labeller that provides label context for the current labeller’s position in the parent labeller’s label context’.
Simple labeller for tracking Notes in a Clause.
The values would be:
Simple labeller for tracking Figures:
The values would be:
The following definition describes a labeller for tracking Notes in a Clause with a conditional label template.
The values would be:
The Label model represents a label assigned to a content element.
The following definition describes a label for a figure with the value “Figure 1”.
The LabelStyle class defines a full set of label models sufficient to implement a coherent labeling system for a publisher.
A label style (the LabelStyle class) represents a coherent collection of LADL models that define a coherent labeling system for a document.
Steps to creating a label style are detailed below.
Understand the ContentElement tree that will be labeled.
Consider the types of ContentElements to label.
In a content tree there may be clauses, annexes and notes.
Consider the label contexts of those ContentElements.
Consider whether a ContentElement type will have its label scoped by the document, or a subclause.
Consider the templates that will be used to format the labels.
A clause may be labeled as “Clause 1”, an annex as “Annex A”, and a note as “Note 1”.
Consider whether the label for a ContentElement will differ between global and local references.
The first ordered list item may be labelled locally as “a)”, but globally as “List N, a)”.
Define the LADL models from the bottom up, per type of ContentElement.
Specify the LabelTemplate for generating the label for the type of ContentElement.
A clause labeled as “Clause 1” is specified as a LabelTemplate with the pattern “Clause %n”, where the sequence used is ArabicNumericSequence.
Specify the Sequence for generating numbering formats if a custom implementation is required.
An Annex labeled as “Annex A” requires the sequence RomanUpperNumericSequence, which is available by default.
Specify the LabelContext for the type of ContentElement.
A clause numbered according to a document-level scope requires a LabelContext that is linked to the ContentElement(Document).
Construct the Labeller for the type of ContentElement using the defined models in previous steps.
A labeller requires a sequence, context, template (local and maybe global), potentially a parent labeller depending on whether the template incorporates the ContentElement’s parent’s label.
Construct the LabelStyle object with the defined models.
The following definition describes a label style for a document with a clause context and a figure labeller.
The desired outputs are:
“Clause 1” for the clause labeller, with label context of the document, identical global and local label.
“1.1” for the sub-clause labeller, with label context of the clause, identical global and local label.
“Figure 1” for the figure labeller, with label context of the document, identical global and local label.
Assume that we have this ContentElement tree:
The label contexts are:
The DocumentContext scopes the labels of clauses and figures
The ClauseContext scopes the labels of the first sub-clause level
The SubClauseContext scopes the labels of all other sub-clause levels
The Document scopes the labels of figures
The following algorithm describe how to resolve the label for a ContentElement object in a LADL-compliant runtime.
Before resolving a label, the following prerequisites must be met:
A valid LabelStyle must be defined with appropriate Labeller objects.
ContentElement objects must be correctly structured in a content tree.
LabelContext objects must be properly associated with ContentElement objects.
Each Labeller must have at least one valid LabelTemplate.
The label resolution algorithm also requires:
Access to the current element count of similar elements in the same context (for conditional templates)
Ability to track labeller state across the document
Proper parent-child relationships between Labeller objects
From the ContentElement, find its applicable LabelContext object. The applicable LabelContext object is one that has a Labeller that can label the type of the ContentElement.
If the LabelContext object is on it, use it.
If not, navigate through its parent attribute subsequently until the closest LabelContext object is obtained.
From the LabelContext object, find the Labeller object that is applicable to the ContentElement.
Ask the Labeller object to generate a label for the ContentElement.
The Labeller object will use its LabelTemplate object to generate the label.
If the Labeller has multiple LabelTemplate objects with conditions, evaluate each condition:
For each LabelTemplate, check if its LabelContextCondition evaluates to true for the current context.
Select the first LabelTemplate whose condition evaluates to true.
If no conditions evaluate to true, select the first LabelTemplate without a condition, or the first one if all have conditions
If the LabelTemplate requires a sequence element, it will ask its Sequence object to generate a value for the position of the ContentElement in the LabelContext.
If the LabelTemplate requires a parent labeller, it will ask its parent Labeller object to generate a label for the ContentElement.
Done.
Many types of content elements in technical documents are auto-labeled to provide a consistent structure and reference system.
This annex provides examples of common auto-labeled elements for the reader’s reference.
Lists are among the most commonly labeled elements in documents, with both ordered and unordered variants.
Ordered lists use sequential labellers to number items in a list, increasing in value with each new item. They may also include nested hierarchies for sub-items.
Item 1
Item 2
Sub-item 2.1
Sub-item 2.2
Item 3
Unordered lists use non-sequential markers for visual distinction.
Item A
Item B
Sub-item B.1
Sub-item B.2
Clauses form the primary structural elements of technical documents and use hierarchical labeling.
“Clause 1: Introduction”
“Clause 2: Background”
“Sub-clause 2.1: Context”
“Sub-clause 2.2: Importance”
Annexes and appendices typically use different labeling schemes than the main document.
“Annex A: Glossary”
“Annex B: References”
“Annex A, Appendix 1: Sample Data”
“Annex A, Appendix 2: Test Cases”
Figures typically use a combination of sequential and hierarchical labeling.
“Figure 1: System Architecture”
“Figure A.2: Data Flow Diagram”
Tables use labeling schemes similar to figures but often with different presentation.
“Table 1: Data Summary”
“Table A.2: Test Results”
Notes may appear throughout a document and are typically labeled within their label context.
“NOTE 1: Important Information”
“Clause 2, NOTE 1: Additional Details”
Examples often follow similar label templates to notes.
“EXAMPLE 1: Basic Usage”
“Clause 3, EXAMPLE 1: Advanced Features”
Requirements often need special labeling for traceability.
“REQ-1.1: System shall support multiple users”
“REQ-1.2: The system shall ensure data security”
The following instance model definitions illustrate the relationships shown in the diagram.
Add instance model definitions
This document defines the ISO/IEC label style using the Label Auto-assignment Definition Language (LADL) as specified in MN 112. The ISO/IEC label style originates from and implements the requirements of:
the ISO/IEC Directives, Part 2
the ISO House Style
This style defines the labeling scheme used by ISO/IEC deliverables.
The element labeling scheme for ISO/IEC is specified as follows.
| Element | Labeling specification | LabelContext |
|---|---|---|
| Clause | Local and global: “Clause 1”, “Clause 2”… | Document |
| Subclause | Local and global: “1.1”, “1.2”, “2.1.1”… Uses parent’s sequence number |
Parent Clause |
| Annex | Local and global: “Annex A”, “Annex B”, “Annex AA”… | Document |
| Annex clause | Local and global: “A.1”, “A.2”… | Annex |
| Figure | Local and global: “Figure 1”, “Figure A.1” Subfigure: “Figure A.1 a)” |
Document (for main document) Annex (for annex figures) |
| Table | Local and global: “Table 1”, “Table A.1” | Document (for main document) Annex (for annex tables) |
| NOTE | Local: “NOTE 1”, “NOTE 2”… Global: “Clause X, NOTE 1” Special case: If single note, simply “NOTE” without number |
Clause or Subclause |
| EXAMPLE | Local: “EXAMPLE 1”, “EXAMPLE 2”… Global: “Clause X, EXAMPLE 1”, “1.2.3, EXAMPLE 2” |
Clause or Subclause |
| Formula | Same pattern as Figure/Table | Clause |
| List | Local and global: “List 1”, “List 2”, “List A.1”… | Clause |
| List item (unordered) | All levels: “—” | List (first level), Parent ListItem (subsequent levels) |
| List item (ordered) | First level: a), b), c)… Second level: 1), 2), 3)… Third level: i), ii), iii)… Fourth level: a), b), c)… |
List (first level), Parent ListItem (subsequent levels) |
The clause labeling scheme for ISO/IEC documents follows a hierarchical structure with Arabic numerals.
Subclauses are labeled hierarchically, inheriting the parent clause number.
Annexes use uppercase alphabetic labeling.
Clauses within annexes combine the annex letter with an Arabic numeral.
Figures are labeled with “Figure” followed by a sequential number.
Figures in annexes combine the annex letter with a figure number.
Subfigures use lowercase alphabetic labels.
Tables are labeled with “Table” followed by a sequential number.
Tables in annexes combine the annex letter with a table number.
Notes use conditional labeling based on the number of notes in a context. A single note is labeled simply as “NOTE” without a number, while multiple notes in the same context are labeled as “NOTE 1”, “NOTE 2”, etc.
The condition property uses a LabelContextCondition object to determine which template to use based on element count. The condition element_count_gt with threshold 1 means “use this template when there are more than 1 notes in the context.”
Examples use conditional labeling similar to notes. A single example is labeled simply as “EXAMPLE” without a number, while multiple examples in the same context are labeled as “EXAMPLE 1”, “EXAMPLE 2”, etc.
Just like with notes, the LabelContextCondition determines which template to use based on the count of examples within the context.
Formulas are labeled with parenthesized numbers.
Formulas in annexes combine the annex letter with a formula number.
Lists are labeled with “List” followed by a sequential number.
Lists in annexes combine the annex letter with a list number.
Unordered list items use a dash character at all levels.
Ordered list items use different sequences at different levels.