PDF Name Tree
A PDF Name Tree is a sorted dictionary structure that maps string keys (names) to arbitrary PDF values, enabling efficient lookup by key across large collections. Name trees are used throughout PDF for named destinations (anchor links), embedded files, JavaScript actions, and alternate presentations — wherever a large, searchable mapping from string keys to objects is needed.
A PDF name tree is a balanced tree data structure that maps string keys to arbitrary PDF objects. Name trees are used throughout the PDF specification wherever a large collection of named objects must be stored and accessed efficiently — without loading the entire collection into memory.
Name trees are analogous to a dictionary or hash map — given a string key, they return the corresponding value. But unlike a simple flat dictionary (which would require loading all keys into memory to search), a name tree stores its keys in lexicographically ordered leaf nodes organised as a balanced tree, allowing binary search with O(log n) key lookups even for very large collections.
The primary use of name trees in PDF is in the document catalogue — the /Names entry of the PDF's root object contains a name dictionary that groups name trees by purpose: destinations, JavaScript, embedded files, forms data, and more.
Name tree structure
A name tree consists of intermediate nodes and leaf nodes:
<strong>Intermediate nodes</strong> — Have a /Kids array of references to child nodes (intermediate or leaf). Each intermediate node has a /Limits array: a two-element array [minimum_key, maximum_key] that defines the range of keys covered by this subtree. This allows the search algorithm to skip entire subtrees without visiting them.
<strong>Leaf nodes</strong> — Have a /Names array: a flat array alternating string key and value: [key1, value1, key2, value2, ...]. Keys within a leaf node are stored in lexicographic order. Leaf nodes also have a /Limits array.
The root node of the tree can be an intermediate node or a leaf node (for small trees). The root can also combine both /Kids and /Names (only at the root level — not at intermediate nodes).
A simple name tree example (shown as logical structure):
<code>Root node /Kids → [NodeA, NodeB]</code> <code> NodeA /Limits ["apple", "mango"] /Names ["apple" obj1, "banana" obj2, "mango" obj3]</code> <code> NodeB /Limits ["orange", "zebra"] /Names ["orange" obj4, "pear" obj5, "zebra" obj6]</code>
To look up the key "banana": check Root's /Kids; check NodeA's /Limits ["apple","mango"] — "banana" is within range; search NodeA's /Names array — find "banana" → return obj2.
<strong>Lexicographic ordering</strong> — Keys in name trees are sorted in PDF string comparison order, which is byte-by-byte comparison of the raw bytes of the string. This is not the same as Unicode alphabetical order for strings with high-byte characters. However, in practice, name tree keys are typically 7-bit ASCII strings (destination names, JavaScript action names, form field names), so the distinction rarely matters.
Name trees in the document catalogue
The /Names dictionary in the PDF document catalogue (the root object's /Names entry) contains name trees for several purposes. The most common:
<strong>/Dests — Named destinations</strong> — Maps string names to destination arrays (a page reference, view type, and coordinates). Named destinations are the stable, name-based alternative to numeric page destinations. Hyperlinks and bookmarks can target named destinations — if pages are reordered, the named destination still works correctly because it's resolved by name rather than page number. See <a href="https://pdftheguide.com/glossary/pdf-page-labels" target="_blank" rel="noopener">PDF Page Labels</a> for related page navigation concepts.
<strong>/JavaScript — Document-level JavaScript</strong> — Maps names to JavaScript actions that execute at document open or in response to document events. In interactive PDFs with complex form logic, this name tree contains the named JavaScript functions. PDF viewers that disable JavaScript skip these entries.
<strong>/EmbeddedFiles — Embedded file attachments</strong> — Maps file names to file specification dictionaries (embedded file streams). This is the registry of embedded attachments in the PDF — including the ZUGFeRD/Factur-X invoice XML in PDF/A-3 documents. See <a href="https://pdftheguide.com/glossary/pdf-a" target="_blank" rel="noopener">PDF/A</a> for the e-invoicing context.
<strong>/Forms — Form data resources</strong> — Maps names to form data resources in XDP (XML Data Package) form documents.
<strong>/AP — Annotation appearances</strong> — Maps appearance stream names used across multiple annotations.
<strong>/Pages — Named pages</strong> — Maps string names to page dictionaries. Used in interactive documents where cross-document links target pages by name rather than number.
<strong>/Templates — Named page templates</strong> — Maps template names to page content that can be instantiated in the document.
Number trees: the numeric key variant
Closely related to name trees, PDF also defines number trees — trees that map integer keys to values, using the same balanced-tree structure but with integers instead of strings as keys.
Number trees are used primarily for:
<strong>/ParentTree in the structure tree</strong> — Maps page numbers to structure tree nodes — the data structure that allows structure tree elements to be found from page objects. This is the navigation mechanism used by accessibility tools to find the structure tree element for a given page location. The /ParentTree allows a screen reader that has focus on a specific page location to quickly navigate to the corresponding structure element in the tag tree.
<strong>/PageLabels — Page label data</strong> — Maps page index numbers (0-based) to page label dictionaries. This defines human-readable page labels that differ from the physical page index — for example, a PDF with Roman numeral front matter (i, ii, iii) followed by Arabic numerals (1, 2, 3). See <a href="https://pdftheguide.com/glossary/pdf-page-labels" target="_blank" rel="noopener">PDF Page Labels</a> for a full explanation.
The structure of a number tree is identical to a name tree, except that /Limits arrays contain integers and /Nums arrays (instead of /Names arrays) store the key-value pairs as [integer, value, integer, value, ...]. The tree is sorted in ascending integer order.
<strong>Performance implications</strong> — For documents with thousands of named destinations, JavaScript functions, or embedded files, the tree structure provides efficient lookup. A flat array of key-value pairs in the document catalogue would require loading all keys into memory to perform a lookup — impractical for a document with tens of thousands of named destinations. The balanced tree structure allows PDF viewers to retrieve any named destination with a small, bounded number of indirect object dereferences.
Frequently asked questions
What is the difference between a named destination and a page number destination in PDF?
A page number destination (called an explicit destination in the PDF spec) is a direct array specifying a page object reference, view type (e.g., /XYZ for a coordinate position), and view parameters. It looks like: [page_object_ref /XYZ x y zoom]. The risk: if pages are inserted or deleted before the target page, the page number changes but the page object reference still works — however, if the page object itself is replaced (not just reordered), the destination breaks. A named destination is a string stored in the /Dests name tree that maps to an explicit destination array. The named destination provides an additional level of indirection: links and bookmarks reference the name, and the name-to-destination mapping can be updated independently. For large, frequently revised documents (technical manuals, legal documents), named destinations allow cross-document links to remain valid as the document is updated.
How do embedded file attachments work in PDF?
File attachments in PDF are stored as embedded file streams — stream objects with the /Type /EmbeddedFile key and an /Params dictionary containing file metadata (creation date, modification date, file size, checksum). The embedded file stream contains the actual file data (usually Flate-compressed). File attachments are registered in the /EmbeddedFiles name tree in the document catalogue (mapping file names to file specification dictionaries) and may also be referenced from the /Names array of file annotation objects (the visible attachment clip icon on a page). In PDF/A-3, associated files (the mechanism used by ZUGFeRD for embedded XML) use the /AF array rather than the traditional /Annots attachment mechanism — a distinction that matters for PDF/A-3 validation.
Can PDF name trees be used for custom application data?
Yes. The /Names dictionary can contain custom name trees for application-specific purposes alongside the standard ones. Developers building PDF-based applications sometimes store application metadata, session state, or cross-reference data in custom name trees within the document. However, this should be done carefully: name trees in the document catalogue are processed by PDF validators (including PDF/A and PDF/X validators), and unexpected entries may cause validation failures. The standard approach for application-specific data in PDF is to use the /PieceInfo dictionary (per-document and per-page private application data) with a registered application name, rather than adding custom entries to /Names. For embedded structured data, PDF/A-3 associated files are the preferred approach.