The logical structure of a PDF, from version 1.3, records what its content is rather than where it goes on the page: headings, paragraphs, lists, tables, figures, in reading order. Screen readers, text reflow and export to other formats use it. A tagged PDF is one whose logical structure follows the rules of tagged PDF, PDF 1.4 and later. The content streams stay as they are; marked-content operators tie stretches of content to elements of a separate tree of dictionaries.
The structure tree root
The catalog’s StructTreeRoot is a dictionary:
| Key | Since | Meaning |
|---|---|---|
Type | 1.3 | StructTreeRoot |
K | 1.3 | The top structure elements, one or an array |
IDTree | 1.3 | A name tree from element IDs to elements |
ParentTree | 1.3 | A number tree from each page’s StructParents and each object’s StructParent to the elements that own its content. Required when any structure element has content items |
ParentTreeNextKey | 1.3 | The next integer free to use as a key in ParentTree |
RoleMap | 1.3 | Maps a writer’s own structure types to standard ones, such as /Heading1 /H1 |
ClassMap | 1.3 | Maps class names to attribute objects shared by many elements |
Namespaces | 2.0 | An array of namespace dictionaries |
PronunciationLexicon | 2.0 | Streams of pronunciation lexicons, in PLS format |
AF | 2.0 | Associated files of the structure tree |
Structure elements
| Key | Since | Meaning |
|---|---|---|
Type | 1.3 | StructElem |
S | 1.3 | Required. The structure type: a standard type or a name mapped by RoleMap |
P | 1.3 | Required. The parent element or root |
ID | 1.3 | A byte string that identifies the element, for IDTree |
Ref | 2.0 | Other structure elements this one refers to, such as the body text behind a footnote mark |
Pg | 1.3 | The page that holds the content items directly below this element, unless they say otherwise |
K | 1.3 | The children: content items or other elements, one or an array |
A | 1.3 | Attribute objects, one or an array; each entry may be followed by a revision number |
C | 1.3 | Attribute class names, one or an array, also with revision numbers |
R | 1.3 | The element’s revision number, default 0. 2.0 deprecated |
T | 1.3 | A title, as text |
Lang | 1.4 | The language of the element |
Alt | 1.3 | Alternate text for those who cannot see it, such as a figure’s description |
E | 1.5 | The expansion of an abbreviation |
ActualText | 1.4 | The exact text of the content, replacing it |
AF | 2.0 | Associated files of the element (earlier in PDF/A-3) |
NS | 2.0 | The namespace of its structure type |
PhoneticAlphabet | 2.0 | The name of the alphabet of Phoneme: ipa, x-sampa, zh-Latn-pinyin or zh-Latn-wadegile |
Phoneme | 2.0 | How it is pronounced, in that alphabet |
Content items
An element’s K entries may be other elements or content items of three
kinds:
- A marked-content identifier: an integer, the MCID of a
marked-content sequence on the page
Pg. In the content stream the sequence is written/P <</MCID 3>> BDC … EMC. - A marked-content reference, a dictionary of
Type MCR:Pg, the page if not the element’s;MCID;Stm, the content stream the sequence is in, if it is a form XObject or annotation appearance;StmOwn, the object that owns that stream. - An object reference, a dictionary of
Type OBJR:Pg, the page, andObj, an object such as an image XObject, a form XObject or an annotation, which itself has aStructParentkey.
An image or annotation that is used in the structure has a StructParent
key, and a page or form with marked content has StructParents. A reader
looks that integer up in ParentTree to go from content back to its
element. For a page the value is an array indexed by MCID; for a single object it is
the element itself.
Attributes
An attribute object is a dictionary, or a stream with a dictionary, whose
O key names its owner, the application or standard that defines its other
keys, from PDF 2.0 sometimes with NS, a namespace. Standard owners:
O | Meaning |
|---|---|
Layout | Layout attributes |
List | List attributes |
PrintField | Attributes of a form field shown as text |
Table | Table cell attributes |
XML-1.00, HTML-3.20, HTML-4.01, HTML-5.00, OEB-1.00, RTF-1.05, CSS-1.00, CSS-2.00, CSS-3.00, RDFa-1.10, ARIA-1.1 | Attributes that follow those specifications, for conversion back to them. The later names came with PDF 2.0 |
NSO | 2.0: owned by the namespace in the object’s NS |
UserProperties | 1.6: user properties, in a P array of dictionaries with N name, V value, F formatted value and H hidden |
Attributes apply by revision. When an element’s revision has changed since an attribute
was attached, the attribute is out of date, which lets a writer’s editor leave a stale
attribute in place. A class named in C looks its attribute objects up in
ClassMap. An attribute given directly in A overrides one of
the same name from a class. C and A entries may each be
followed by a revision number.
MarkInfo
| Key | Since | Meaning |
|---|---|---|
Marked | 1.4 | true for a tagged PDF; default false |
UserProperties | 1.6 | true if the structure tree has user properties |
Suspects | 1.6 | true if the tagging may be wrong and should be checked. 2.0 deprecated |
Standard structure types
Tagged PDF defines a set of standard types. A reader understands any file written with
them. Where a writer uses its own names, RoleMap maps them to standard
ones, possibly in several steps.
| Kind | Types of PDF 1.7 |
|---|---|
| Grouping | Document Part Art Sect Div BlockQuote Caption TOC TOCI Index NonStruct Private |
| Paragraph and heading | P H H1 H2 H3 H4 H5 H6 |
| List | L LI Lbl LBody |
| Table | Table TR TH TD THead TBody TFoot |
| Inline text | Span Quote Note Reference BibEntry Code Link Annot |
| Ruby and warichu | Ruby RB RT RP Warichu WT WP |
| Illustration | Figure Formula Form |
PDF 2.0 namespaces
PDF 2.0 adds structure namespaces, so that different sets of types can be used in one
file and told apart. A namespace dictionary has Type Namespace,
NS, the namespace’s URI (required), Schema and
RoleMapNS, which maps its types to those of another namespace. The two
standard namespaces are http://iso.org/pdf/ssn, the PDF 1.7 types above,
and http://iso.org/pdf2/ssn, the PDF 2.0 types. A
StructElem with no NS is in the PDF 1.7 namespace.
ISO/TS 32005 defines how types of the two standard namespaces map to each other.
The PDF 2.0 set is organised differently from PDF 1.7. It adds, among others,
DocumentFragment, Aside, Title,
FENote (a footnote or endnote, replacing Note),
Sub, Em and Strong, and allows headings at any
level as Hn. The full table is in clause 14.8.4 of ISO 32000-2.
Standard attributes
Layout (O = Layout)
| Attribute | Applies to | Values |
|---|---|---|
Placement | any | Block, Inline, Before, Start, End |
WritingMode | any | LrTb (default), RlTb, TbRl; 2.0 adds further directions, such as TbLr |
BackgroundColor, BorderColor, Color | any | RGB colours as three numbers, or for BorderColor an array of four |
BorderStyle | any | None, Hidden, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, Outset, one or four |
BorderThickness, Padding | any | A number or four numbers |
SpaceBefore, SpaceAfter, StartIndent, EndIndent, TextIndent | block | Numbers |
TextAlign | block | Start, Center, End, Justify |
BBox | illustrations and tables | The bounding box on the page |
Width, Height | illustrations, table cells | Auto or a number |
BlockAlign | table cells | Before, Middle, After, Justify |
InlineAlign | table cells | Start, Center, End |
TBorderStyle, TPadding | tables | As BorderStyle and Padding, for table cell borders |
BaselineShift, LineHeight | inline | A number; LineHeight may be Normal or Auto |
TextDecorationColor, TextDecorationThickness | inline | An RGB colour; a number |
TextDecorationType | inline | None, Underline, Overline, LineThrough |
RubyAlign | Ruby | Start, Center, End, Justify, Distribute |
RubyPosition | Ruby | Before, After, Warichu, Inline |
GlyphOrientationVertical | inline | Auto, −180, −90, 0, 90, 180, 270, 360 |
ColumnCount, ColumnGap, ColumnWidths | grouping | Numbers or arrays |
List (O = List)
ListNumbering: None (default), Disc,
Circle, Square, Decimal,
UpperRoman, LowerRoman, UpperAlpha,
LowerAlpha. PDF 2.0 adds Ordered, Unordered
and Description.
PrintField (O = PrintField)
Role: rb radio button, cb check box,
pb push button, tv text value. checked (PDF
2.0 Checked): on, off, neutral.
Desc: the text.
Table (O = Table)
RowSpan, ColSpan, integers defaulting to 1;
Headers, element IDs of a cell’s header cells; Scope:
Row, Column, Both; Summary (1.7),
a description of the table; Short (2.0), a short form of a heading.
Artifacts
Content not part of the document’s text, such as page numbers or decorative
rules, is marked /Artifact in the content stream, so that it is left out
of the reading order. Its property list may say what kind:
| Key | Meaning |
|---|---|
Type | Pagination, Layout, Page, Background; PDF 2.0 adds Inline |
BBox | Its bounding box |
Attached | Top, Bottom, Left, Right, the edges of the page it is tied to |
Subtype | From 1.7: Header, Footer, Watermark; added in 2.0: PageNum, Bates, LineNum, Redaction |
Marks in the content stream
Property lists for BDC can carry MCID, tying a sequence to
structure; Lang, Alt, E and
ActualText, describing the sequence when the structure tree does not; and
for optional content OC as the tag. Span is the usual tag
for a stretch given only such properties.