Every standard structure type in PDF 1.7, grouped the way the specification groups them, with the version that added it and where it stands in PDF 2.0.
A structure element’s type is the name in its /S entry. Readers know what the standard types mean. A file can use other names too, and the /RoleMap in the structure tree root says which standard type each one stands for. The Tagged PDF page in Learning explains the structure tree and how marked content ties its elements to the page.
The PDF 2.0 column says whether a type is in PDF 2.0’s standard namespace: Kept;
Grouping elements
Grouping elements hold other structure elements and never content directly. In PDF 1.7, the structure tree root of a tagged file has exactly one child: Document for a complete document, or Part, Art, Sect or Div for a fragment of one.
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
Document | A complete document. The usual top-level element.PDF 2.0: Document elements can nest, for example one per letter in a mail merge. | Kept | |
Part | A large division of a document, grouping articles or sections.PDF 2.0: Redefined as a grouping that implies no hierarchy, the semantic equivalent of Div. | ||
ArtArticle | A self-contained piece of writing, such as one story in a magazine. Articles shouldn’t contain other articles. | ||
SectSection | A container for related content, such as a heading, its paragraphs and nested subsections. | Kept | |
DivDivision | A generic block-level element or group of elements. | Kept | |
BlockQuoteBlock quotation | One or more paragraphs quoted from someone other than the author. | ||
Caption | A short text describing a table or figure.PDF 2.0: Can caption any element: at most one, as its first or last child. | ||
TOCTable of contents | A table of contents, made of TOCI entries and nested TOC elements. Lists of figures or tables and bibliographies can use it too. In PDF 1.4 the entries were wrapped in L and LI.PDF 2.0: Tables of contents are among the listed uses of L. | ||
TOCITable of contents item | One entry in a TOC. Its children can be an Lbl, a Reference to the title and page number, a P, a NonStruct around the dot leader, or a nested TOC. | ||
Index | An index: entries of text, each with Reference elements pointing to where it occurs.PDF 2.0: Indexes are among the listed uses of L. | ||
NonStructNonstructural element | Groups elements for convenience only. Unlike Div, it isn’t exported to other formats, but its children are processed normally. | Kept | |
PrivatePrivate element | Content private to the application that wrote it. Neither it nor its children are exported. |
Block-level structure elements
A block-level structure element (BLSE) is laid out in the block direction, top to bottom in Western text: a paragraph, heading, list or table. The block-level types are the paragraphlike, list and table elements below, except that TR, TH, TD, THead, TBody and TFoot are neither block-level nor inline-level: they only organize a table. An element of any other type becomes block-level when its Placement attribute is anything but Inline.
Paragraphlike elements
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
HHeading | A heading whose level comes from how deeply its section is nested. It should be the first child of the element it heads.PDF 2.0: At most one H per parent, and a document uses either H or numbered headings, not both. | Kept | |
H1–H6 | Headings with an explicit level, for writers that can’t nest sections to show it.PDF 2.0: Generalized to Hn, so H7 and deeper are standard too. | ||
PParagraph | A low-level division of text. | Kept |
Structure can be deep or flat. A strongly structured document nests Sect elements as deep as its outline, each starting with an H. A weakly structured one, typical of HTML, keeps headings and paragraphs as siblings under one or two grouping elements and shows the outline with H1–H6.
List elements
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
LList | A list: an optional Caption, then LI items. | Kept | |
LIList item | One item of a list: an Lbl, an LBody, or both. | Kept | |
LblLabel | The bullet, number or term that identifies an item.PDF 2.0: A general inline type, also used for heading numbers, caption numbers and form field labels. | ||
LBodyList body | The item’s content, either directly or as block-level children such as a nested list. | Kept |
The ListNumbering attribute, owned by List, says how the labels were made: Disc, Decimal, UpperRoman and so on. The Lbl elements should still contain the actual bullets or numbers.
Table elements
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
Table | A table: TR rows, or an optional THead, one or more TBody and an optional TFoot. A Caption can be its first or last child. | Kept | |
TRTable row | A row of TH and TD cells. | Kept | |
THTable header cell | A cell whose text describes one or more rows or columns. | Kept | |
TDTable data cell | A cell of the table’s data. | Kept | |
THeadTable header row group | The header rows. When a table splits across pages, they can be repeated at the top of each part. | Kept | |
TBodyTable body row group | Rows of the table’s body. A table can have several, for example to give a set of rows its own border. | Kept | |
TFootTable footer row group | The footer rows. When a table splits across pages, they can be repeated at the bottom of each part. | Kept |
Without help, readers guess which headers belong to which cells. The Table attributes make it explicit: Headers and Scope (PDF 1.5) link cells to their headers, and RowSpan and ColSpan mark cells that span several rows or columns.
Inline-level structure elements
An inline-level structure element (ILSE) is laid out along a line inside a block, left to right in Western text: a run of text with a role of its own, such as a quotation or a link. Ruby and Warichu, also in this table in ISO 32000-1, are listed with their parts below.
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
Span | A generic inline run with no meaning of its own, for example to carry layout attributes. Font and color changes don’t need one: readers can get them from the content. | Kept | |
QuoteQuotation | A quotation inside a paragraph. Whole quoted paragraphs use BlockQuote. | ||
Note | A footnote or endnote that the text refers to. It may have an Lbl child, and can sit next to the text that refers to it or elsewhere, reached through a Reference.PDF 2.0: Footnotes and endnotes use FENote. | ||
Reference | A citation of content elsewhere in the same document. | ||
BibEntryBibliography entry | An entry identifying the source of cited content. It may have an Lbl child. | ||
Code | A fragment of computer program text. | ||
Link | Ties content to a link annotation: its children are the content and an object reference to the annotation. | Kept | |
AnnotAnnotation | Ties content to an annotation other than a link or a widget, in the same way. | Kept |
A Link or Annot element points at its annotation with an object reference dictionary, << /Type /OBJR /Obj 30 0 R >>, among its children. From PDF 1.7, a link whose text wraps onto a second line uses one link annotation whose /QuadPoints cover both pieces; enclosing several link annotations in one Link is deprecated.
A marked-content sequence tagged /Span in a content stream, with no /MCID, is a different thing: it only carries properties such as /Lang or /ActualText for the content it wraps (see BDC).
Ruby and warichu elements
Ruby is small text set next to base text, used in Japanese and Chinese to show how a word is read. Warichu is a comment in small text set on two lines within the height of one line, right after the text it comments on, used in Japanese. All seven types came in PDF 1.5; PDF 1.4 has no table for them.
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
Ruby | Wraps a whole ruby assembly: one RB, then an RT or the three elements RP, RT, RP. It never breaks across lines. | Kept | |
RBRuby base text | The full-size text the ruby applies to. | Kept | |
RTRuby annotation text | The small text set next to the base text. | Kept | |
RPRuby punctuation | A parenthesis around the ruby text, used when the ruby is set as a plain comment or as warichu instead of as ruby. | Kept | |
Warichu | Wraps a whole warichu assembly: WP, WT, WP. It can wrap across lines. | Kept | |
WTWarichu text | The small comment text, set on two lines. | Kept | |
WPWarichu punctuation | A parenthesis or similar bracket around the warichu text. | Kept |
The Layout attributes RubyAlign and RubyPosition control how the ruby text is placed.
Illustration elements
An illustration is moved as a unit when content reflows, so it needs a BBox attribute. Its content is one or more whole graphics objects, never part of a text object between BT and ET. Without a Placement attribute, it is laid out inline.
| Type | What it’s for | Added | PDF 2.0 |
|---|---|---|---|
Figure | Graphical content, such as an image or drawing. | Kept | |
Formula | A mathematical formula as a whole, laid out like a figure.PDF 2.0: The math itself can be tagged with MathML elements, in the MathML namespace. | Kept | |
Form | A form field’s widget annotation. Its only child is an object reference to the annotation. From PDF 1.7, a Form with a PrintField Role attribute can instead hold the content of a non-interactive field.PDF 2.0: Listed with Link and Annot, and required for every widget annotation that is real content. | Kept |
Give Figure and Formula elements an /Alt description, or /ActualText when the graphic shows text, in the structure element dictionary. See Interactive features for form fields and widget annotations.
New in PDF 2.0
These nine types exist only in the PDF 2.0 standard structure namespace, so an element that uses one must be in that namespace (see below). PDF 2.0 also sorts all its types into four categories, document level, grouping, block and inline, and lets many types act as more than one depending on what contains them.
| Type | What it’s for | Added |
|---|---|---|
DocumentFragment | Part of a document, for example an extract inserted into another one. Its structure can start anywhere, such as at a third-level heading. | |
Aside | Content set apart from what surrounds it: a sidebar, a callout, commentary on an article. | |
Title | The title of a document or of a large division such as a chapter, once, at or near the start of its parent. | |
Hn | A heading at level n: H1, H2 and so on with no upper limit. Only an uppercase H and digits, with no leading zero. Annex M counts only n > 6 as new. | |
FENote | A footnote or endnote, read only when the reader chooses. The text should refer to it, for example through a Link. | |
SubSubdivision of a block | One part of a block, such as a verse of a poem, a line of source code or a line of an address. If one child of a block is a Sub, the rest should be too. | |
EmEmphasis | Stress that changes the meaning of a sentence. Nested Em elements stress more. | |
Strong | Strong importance, seriousness or urgency. | |
Artifact | Content that isn’t real content but needs a place in the tree, such as line numbers. Readers normally skip it and its descendants. Not the same as the /Artifact marked-content tag. |
Role maps
A file can name its structure types after its own source, such as /Chapter, if the structure tree root’s /RoleMap maps each name to a standard type. A reader that doesn’t know a name looks it up, and keeps following the chain until it reaches a type it knows or comes back to one it has already seen: chains and even cycles are allowed. The original names still count. An export to XML can keep them, while conversion to HTML, reflow and screen readers use the standard types they map to.
- From PDF 1.5, the role map applies to standard names too. If
/Pis a key in the role map, elements with/S /Pare mapped like any others. Before 1.5, standard names were never remapped. - PDF 2.0 makes mapping compulsory. In a tagged PDF 2.0 file, every element has a standard type or is mapped to one. For custom types with no close match, PDF 2.0 suggests
Divfor groups andSpanfor inline content.
Here the custom types Chapter and ChapterTitle are read as Sect and H1:
10 0 obj % the catalog's /StructTreeRoot points here
<< /Type /StructTreeRoot
/K 11 0 R % one top-level element
/RoleMap << /Chapter /Sect % custom type → standard type
/ChapterTitle /H1 >>
/ParentTree 20 0 R
/ParentTreeNextKey 1 >>
endobj
11 0 obj
<< /Type /StructElem /S /Document /P 10 0 R /K 12 0 R >>
endobj
12 0 obj % read as Sect
<< /Type /StructElem /S /Chapter /P 11 0 R /K [13 0 R 14 0 R 15 0 R] >>
endobj
13 0 obj % read as H1: MCID 0 on page 3
<< /Type /StructElem /S /ChapterTitle /P 12 0 R /Pg 3 0 R /K 0 >>
endobj
14 0 obj % /S /P is a paragraph, /P its parent
<< /Type /StructElem /S /P /P 12 0 R /Pg 3 0 R /K [1 2] >>
endobj
15 0 obj
<< /Type /StructElem /S /Figure /P 12 0 R /Pg 3 0 R /K 3
/Alt (Map of the walking route) >>
endobj
20 0 obj % page 3 has /StructParents 0
<< /Nums [0 [13 0 R 14 0 R 14 0 R 15 0 R]] >> % MCIDs 0 to 3 → their elements
endobjPDF 2.0 namespaces
PDF 2.0 adds namespaces, so tag sets with clashing names can live in one file. The structure tree root’s namespace array, /Namespaces, lists namespace dictionaries. Each has an /NS string naming the namespace, usually a URI, and may have a /Schema file and a /RoleMapNS dictionary. A structure element joins a namespace with its own /NS entry, an indirect reference to one of those dictionaries. PDF 2.0 names three namespaces:
| Namespace | What it holds |
|---|---|
http://iso.org/pdf/ssn | The PDF 1.7 standard types, as listed on this page. It is the default: an element without /NS is in it. |
http://iso.org/pdf2/ssn | The PDF 2.0 standard types: the kept and changed types above, plus the new ones. |
http://www.w3.org/1998/Math/MathML | MathML 3.0, for the structure of mathematics. Its elements need no role map; the top one is math, in lowercase. |
An element without /NS is mapped by /RoleMap. An element in a namespace is mapped by that namespace’s /RoleMapNS, whose values are either a type name in the default namespace or an array of a type name and the target namespace dictionary. Through mapping, one element can be in both standard namespaces, which helps a file work with readers of either version.
10 0 obj
<< /Type /StructTreeRoot /K 11 0 R /ParentTree 20 0 R
/Namespaces [30 0 R 31 0 R] >>
endobj
30 0 obj % the PDF 2.0 standard namespace
<< /Type /Namespace /NS (http://iso.org/pdf2/ssn) >>
endobj
31 0 obj % a custom namespace, mapped into it
<< /Type /Namespace /NS (https://example.com/ns/book)
/RoleMapNS << /Chapter [/Sect 30 0 R]
/Sidebar [/Aside 30 0 R] >> >>
endobj
12 0 obj % a Chapter from the custom namespace
<< /Type /StructElem /S /Chapter /NS 31 0 R /P 11 0 R /K 13 0 R >>
endobj
13 0 obj % a Title, which only PDF 2.0 defines
<< /Type /StructElem /S /Title /NS 30 0 R /P 12 0 R /Pg 3 0 R /K 0 >>
endobjStandard attribute owners
Attributes such as a paragraph’s alignment live in attribute objects: in the element’s /A entry, or in a class named by /C and looked up in the structure tree root’s /ClassMap. Each attribute object has an owner, its /O entry, which says how to read the attributes in it.
| Owner | What its attributes describe | Added |
|---|---|---|
Layout | How content is laid out: Placement, WritingMode, SpaceBefore, TextAlign, BBox and more. | |
List | List numbering: ListNumbering. | |
PrintField | Form elements for non-interactive form fields: Role, checked, Desc. | |
Table | Table cells: RowSpan, ColSpan, Headers, Scope, Summary. | |
Artifact | Artifact structure elements: Type, BBox, Subtype. |
The other standard owners apply only when exporting to one format, and then override the ones above. They are XML-1.00, HTML-3.20, HTML-4.01, OEB-1.00, RTF-1.05, CSS-1.00 and CSS-2.00. PDF 2.0 renames the CSS owners CSS-1 and CSS-2, adds HTML-5.00, CSS-3, RDFa-1.10 and ARIA-1.1, and lets a namespace own attributes: /O /NSO with an /NS entry. The entries /Lang, /Alt, /ActualText and /E aren’t attributes: they go straight in the structure element dictionary.
Checked against §9.6.2 and §9.7.4–9.7.5 (Tables 9.9 and 9.18–9.25) of the Adobe PDF Reference, third edition (PDF 1.4); §14.7.3 and §14.8.4–14.8.5 (Tables 322 and 333–341) of ISO 32000-1:2008 (PDF 1.7); and §14.7.3–14.7.4, §14.8.4–14.8.6 (Tables 354–356 and 364–376) and Annex M of ISO 32000-2:2020 (PDF 2.0).