.PDF File Format – Document structure

The catalog

The page tree

Pages are kept in a balanced tree so that a reader can find page 500 of a long document without reading 499 page objects. Inner nodes are page tree nodes; leaves are pages. The order of the pages is the order of a depth-first walk through Kids.

Resources

A content stream refers to fonts, images and other objects by short names, such as /F1 or /Im3. The resource dictionary of the page, form or pattern maps the names to the objects:

Name trees and number trees

A name tree maps strings to objects, sorted by the bytes of the strings; a number tree maps integers. Each node is a dictionary:

A small tree is just a root with Names or Nums. To look a key up, follow the kid whose Limits contain it.

The name dictionary

The catalog’s Names holds name trees by kind:

Outlines

The outline, shown as bookmarks, is a tree of items held together by doubly linked lists. The root, the catalog’s Outlines, has Type Outlines, First, Last and Count. Each item has:

Destinations

A destination is a page and a view of it, written as an array whose first element is the page object (or, for a link into another file, a page number from 0):

A named destination is a name or string that stands for such an array, looked up in the Dests name tree (or the older catalog Dests dictionary for names). The value may also be a dictionary with the array in D, and in PDF 2.0 a structure destination in SD, which points at a structure element rather than a page.

Page labels

Page labels, from PDF 1.3, are the page numbers a viewer shows, such as i, ii, iii then 1, 2, 3. The catalog’s PageLabels number tree maps the index of the first page of each range (from 0) to a label dictionary:

Article threads

A thread, from PDF 1.1, links areas of text in reading order across pages, like a newspaper story continued on page 7. The catalog’s Threads lists thread dictionaries; each has F, its first bead, and I, information such as a title. Beads form a circular list with N (next), V (previous), T (the thread), P (the page) and R (the rectangle). PDF 2.0 adds Metadata to a thread.

Viewer preferences

Logical structure and tagged PDF

The structure tree, from PDF 1.3, records what the content is: headings, paragraphs, lists, tables, figures, in reading order. It is what screen readers, reflow and text export use. Content is tied to it by marked content: a BDC operator with an MCID number around each piece of page content.

• The catalog’s StructTreeRoot (Type StructTreeRoot) has K, the top elements; ParentTree, a number tree from each page’s StructParents to the elements that own its marked content; IDTree; RoleMap, which maps a writer’s own element types to standard ones; and ClassMap for shared attributes.
• Each structure element (Type StructElem) has S, its type (Document, H1, P, Table, Figure …), P, its parent, K, its children (other elements, MCIDs, or marked-content and object references), Pg, the page, and optional Alt, ActualText (1.4), Lang (1.4), E (1.5, the expansion of an abbreviation), T and A, its attributes.
• The catalog’s MarkInfo says Marked true for a tagged PDF (1.4). UserProperties (1.6) says the structure carries user properties; Suspects (1.6) is 2.0 deprecated.
• PDF 2.0 adds namespaces: the root’s Namespaces array and each element’s NS, so that the PDF 1.7 and the PDF 2.0 sets of standard element types can be told apart, along with Ref on elements, and PronunciationLexicon, PhoneticAlphabet and Phoneme for speech.

PDF/UA requires a complete structure tree, and PDF/A levels “a” require one too.

Optional content

Optional content, from PDF 1.5, is what programs call layers: parts of pages that can be shown or hidden, such as the languages of a manual or the floors of a plan.

• An optional content group (OCG), Type OCG, is one layer: Name (required), Intent (View or Design) and Usage, a dictionary that says when it should be on, by CreatorInfo, Language, Export, Zoom, Print, View, User and PageElement.
• An optional content membership dictionary, Type OCMD, combines groups: OCGs, and P, one of AllOn, AnyOn (default), AnyOff and AllOff; or from 1.6 VE, a visibility expression such as [/And ocg1 [/Not ocg2]].
• The catalog’s OCProperties has OCGs, every group in the file; D, the default configuration; and Configs, others. A configuration has Name, Creator, BaseState (ON, OFF or Unchanged), ON and OFF lists, Intent, AS (automatic states by usage), Order (how the layers panel shows the groups), ListMode, RBGroups (groups that act as radio buttons) and from 1.6 Locked.

Content is made optional in three ways: in a content stream between /OC /name BDC and EMC, with the name in the resources’ Properties; by an OC key on a form or image XObject; or by an OC key on an annotation.

Portable collections

A portable collection, from PDF 1.7, is a PDF that is mainly a container for its embedded files, which a viewer shows as a list or a set of folders, with the PDF’s own pages as a cover. The catalog’s Collection has Schema, the columns to show for each file, with names, types and order; D, the file to show first; View, D details, T tiles or H hidden (and C, custom, with Adobe’s extension level 3); and Sort. Each embedded file’s file specification carries CI, its values for the columns. Folders, colours and a navigator came in Adobe’s extension level 3 and are part of PDF 2.0.

Developer extensions

From PDF 1.7 a file can say that it uses extensions to its base version. The catalog’s Extensions dictionary is keyed by a four-character prefix registered with ISO, such as ADBE for Adobe or ISO_ for ISO extensions, and each value is a developer extensions dictionary:

A file that uses Adobe’s AES-256 encryption, for example, has /Extensions <</ADBE <</BaseVersion /1.7 /ExtensionLevel 3>>>>. PDF 2.0 also lets the value be an array, for several extensions under one prefix.