Repository navigation
PDF Spec 14 Metadata
Part of: PDF-Spec-14-Document-Interchange
Navigation: ← Previous | PDF-Spec-Index | PDF-Spec-14-Page-Piece
The features described in this clause do not affect the final appearance of a document. Rather, these features enable a document to include higher-level information that is useful for the interchange of documents among conforming products:
- Procedure sets (14.2, 'Procedure Sets') that define the implementation of PDF operators
- Metadata (14.3, 'Metadata') consisting of general information about a document or a component of a document, such as its title, author, and creation and modification dates
- File identifiers (14.4, 'File Identifiers') for reliable reference from one PDF file to another
- Page-piece dictionaries (14.5, 'Page-Piece Dictionaries') allowing a conforming product to embed private data in a PDF document for its own use
- Marked-content operators (14.6, 'Marked Content') for identifying portions of a content stream and associating them with additional properties or externally specified objects
- Logical structure facilities (14.7, 'Logical Structure') for imposing a hierarchical organization on the content of a document
- Tagged PDF (14.8, 'Tagged PDF'), a set of conventions for using the marked content and logical structure facilities to facilitate the extraction and reuse of a document's content for other purposes
- Various ways of increasing the accessibility of a document to users with disabilities (14.9, 'Accessibility Support'), including the identification of the natural language in which it is written (such as English or Spanish) for the benefit of a text-to-speech engine
- The Web Capture extension (14.10, ' Web Capture'), which creates PDF files from Internet-based or locally resident HTML, PDF, GIF, JPEG, and ASCII text files
- Facilities supporting prepress production workflows (14.11, 'Prepress Support'), such as the specification of page boundaries and the generation of printer's marks , colour separations , output intents , traps , and low-resolution proxies for high-resolution images
The PDF operators used in content streams are grouped into categories of related operators called procedure sets (see Table 314). Each procedure set corresponds to a named resource containing the implementations of the operators in that procedure set. The ProcSet entry in a content stream's resource dictionary (see 7.8.3, 'Resource Dictionaries') shall hold an array consisting of the names of the procedure sets used in that content stream. These procedure sets shall be used only when the content stream is printed to a PostScript output device. The names identify PostScript procedure sets that shall be sent to the device to interpret the PDF operators in the content stream. Each element of this array shall be one of the predefined names shown in Table 314.
Table 314 - Predefined procedure set
| Name | Category of operators |
|---|---|
| Painting and graphics state | |
| Text | Text |
| ImageB | Grayscale images or image masks |
Table 314 - Predefined procedure set (continued)
| Name | Category of operators |
|---|---|
| ImageC | Colour images |
| ImageI | Indexed (colour-table) images |
Beginning with PDF 1.4, this feature is considered obsolete. For compatibility with existing conforming readers, conforming writers should continue to specify procedure sets (preferably, all of those listed in Table 314 unless it is known that fewer are needed). However, conforming readers should not depend on the correctness of this information.
A PDF document may include general information, such as the document's title, author, and creation and modification dates. Such global information about the document (as opposed to its content or structure) is called metadata and is intended to assist in cataloguing and searching for documents in external databases. Beginning with PDF 1.4, metadata may also be specified for individual components of a document.
Metadata may be stored in a PDF document in either of the following ways:
- In a metadata stream (PDF 1.4) associated with the document or a component of the document (14.3.2, 'Metadata Streams')
- In a document information dictionary associated with the document (14.3.3, 'Document Information Dictionary')
NOTE Document information dictionaries is the original way that metadata was included in a PDF file. Metadata streams were introduced in PDF 1.4 and is now the preferred method to include metadata.
Metadata, both for an entire document and for components within a document, may be stored in PDF streams called metadata streams (PDF 1.4) .
NOTE 1 Metadata streams have the following advantages over the document information dictionary:
- PDF-based workflows often embed metadata-bearing artwork as components within larger documents. Metadata streams provide a standard way of preserving the metadata of these components for examination downstream. PDF-aware conforming products should be able to derive a list of all metadatabearing document components from the PDF document itself.
- PDF documents are often made available on the Web or in other environments, where many tools routinely examine, catalogue, and classify documents. These tools should be able to understand the self-contained description of the document even if they do not understand PDF.
Besides the usual entries common to all stream dictionaries (see Table 5), the metadata stream dictionary shall contain the additional entries listed in Table 315.
The contents of a metadata stream shall be the metadata represented in Extensible Markup Language (XML).
- NOTE 2 This information is visible as plain text to tools that are not PDF-aware only if the metadata stream is both unfiltered and unencrypted.
Table 315 - Additional entries in a metadata stream dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be Metadata for a metadata stream. |
| Subtype | name | (Required) The type of metadata stream that this dictionary describes; shall be XML . |
- NOTE 3 The format of the XML representing the metadata is defined as part of a framework called the Extensible Metadata Platform (XMP) and described in the Adobe document XMP: Extensible Metadata Platform (see the Bibliography). This framework provides a way to use XML to represent metadata describing documents and their components and is intended to be adopted by a wider class of products than just those that process PDF. It includes a method to embed XML data within non-XML data files in a platform-independent format that can be easily located and accessed by simple scanning rather than requiring the document file to be parsed.
A metadata stream may be attached to a document through the Metadata entry in the document catalogue (see 7.7.2, 'Document Catalog'). The metadata framework provides a date stamp for metadata expressed in the framework. If this date stamp is equal to or later than the document modification date recorded in the document information dictionary, the metadata stream shall be taken as authoritative. If, however, the document modification date recorded in the document information dictionary is later than the metadata stream's date stamp, the document has likely been saved by a writer that is not aware of metadata streams. In this case, information stored in the document information dictionary shall be taken to override any semantically equivalent items in the metadata stream. In addition, PDF document components represented as a stream or dictionary may have a Metadata entry (see Table 316).
Table 316 - Additional entry for components having metadata
| Key | Type | Value |
|---|---|---|
| Metadata | stream | (Optional; PDF 1.4) A metadata stream containing metadata for the component. |
In general, any PDF stream or dictionary may have metadata attached to it as long as the stream or dictionary represents an actual information resource, as opposed to serving as an implementation artifact. Some PDF constructs are considered implementational, and hence may not have associated metadata.
When there is ambiguity about exactly which stream or dictionary may bear the Metadata entry, the metadata shall be attached as close as possible to the object that actually stores the data resource described.
- NOTE 4 Metadata describing a tiling pattern should be attached to the pattern stream's dictionary, but a shading should have metadata attached to the shading dictionary rather than to the shading pattern dictionary that refers to it. Similarly, metadata describing an ICCBased colour space should be attached to the ICC profile stream describing it, and metadata for fonts should be attached to font file streams rather than to font dictionaries.
- NOTE 5 In tables describing document components in this specification, the Metadata entry is listed only for those in which it is most likely to be used. Keep in mind, however, that this entry may appear in other components represented as streams or dictionaries.
- In addition, metadata may also be associated with marked content within a content stream. This association shall be created by including an entry in the property list dictionary whose key shall be Metadata and whose value shall be the metadata stream dictionary. Because this construct refers to an object outside the content stream, the property list is referred to indirectly as a named resource (see 14.6.2, 'Property Lists').
The optional Info entry in the trailer of a PDF file (see 7.5.5, 'File Trailer') shall hold a document information dictionary containing metadata for the document; Table 317 shows its contents. Any entry whose value is not known should be omitted from the dictionary rather than included with an empty string as its value.
Some conforming readers may choose to permit searches on the contents of the document information dictionary. To facilitate browsing and editing, all keys in the dictionary shall be fully spelled out, not abbreviated. New keys should be chosen with care so that they make sense to users.
The value associated with any key not specifically mentioned in Table 317 shall be a text string.
Although conforming readers may store custom metadata in the document information dictionary, they may not store private content or structural information there. Such information shall be stored in the document catalogue instead (see 7.7.2, 'Document Catalog').
Table 317 - Entries in the document information dictionary
| Key | Type | Value |
|---|---|---|
| Title | text string | (Optional; PDF 1.1 ) The document's title. |
| Author | text string | (Optional) The name of the person who created the document. |
| Subject | text string | (Optional; PDF 1.1) The subject of the document. |
| Keywords | text string | (Optional; PDF 1.1) Keywords associated with the document. |
| Creator | text string | (Optional) If the document was converted to PDF from another format, the name of the conforming product that created the original document from which it was converted. |
| Producer | text string | (Optional) If the document was converted to PDF from another format, the name of the conforming product that converted it to PDF. |
| CreationDate | date | (Optional) The date and time the document was created, in human- readable form (see 7.9.4, 'Dates'). |
| ModDate | date | (Required if PieceInfo is present in the document catalogue; otherwise optional; PDF 1.1) The date and time the document was most recently modified, in human-readable form (see 7.9.4, 'Dates'). |
| Trapped | name | (Optional; PDF 1.3 ) A name object indicating whether the document has been modified to include trapping information (see 14.11.6, 'Trapping Support'): True The document has been fully trapped; no further trapping shall be needed. This shall be the name True , not the boolean value true . False The document has not yet been trapped. This shall be the name False , not the boolean value false . Unknown Either it is unknown whether the document has been trapped or it has been partly but not yet fully trapped; some additional trapping may still be needed. Default value: Unknown . NOTE The value of this entry may be set automatically by the software creating the document's trapping information, or it may be known only to a human operator and entered manually. |
EXAMPLE This example shows a typical document information dictionary.
<< /Title ( PostScript Language Reference, Third Edition )
/Author ( Adobe Systems Incorporated )
/Creator ( Adobe FrameMaker 5 . 5 . 3 for Power Macintosh® )
/Producer ( Acrobat Distiller 3 . 01 for Power Macintosh )
/CreationDate ( D : 19970915110347 - 08 ' 00 ' )
/ModDate ( D : 19990209153925 - 08 ' 00 ' )
>>
endobj
PDF files may contain references to other PDF files (see 7.11, 'File Specifications'). Simply storing a file name, however, even in a platform-independent format, does not guarantee that the file can be found. Even if the file still exists and its name has not been changed, different server software applications may identify it in different ways. Servers running on DOS platforms convert all file names to 8 characters and a 3-character extension. Different servers may use different strategies for converting longer file names to this format.
External file references may be made more reliable by including a file identifier (PDF 1.1) in the file and using it in addition to the normal platform-based file designation. Matching the identifier in the file reference with the one in the file confirms whether the correct file was found.
File identifiers shall be defined by the optional ID entry in a PDF file's trailer dictionary (see 7.5.5, 'File Trailer'). The ID entry is optional but should be used. The value of this entry shall be an array of two byte strings. The first byte string shall be a permanent identifier based on the contents of the file at the time it was originally created and shall not change when the file is incrementally updated. The second byte string shall be a changing identifier based on the file's contents at the time it was last updated. When a file is first written, both identifiers shall be set to the same value. If both identifiers match when a file reference is resolved, it is very likely that the correct and unchanged file has been found. If only the first identifier matches, a different version of the correct file has been found.
To help ensure the uniqueness of file identifiers, they should be computed by means of a message digest algorithm such as MD5 (described in Internet RFC 1321, The MD5 Message-Digest Algorithm ; see the Bibliography), using the following information:
- The current time
- A string representation of the file's location, usually a pathname
- The size of the file in bytes
- The values of all entries in the file's document information dictionary (see 14.3.3, 'Document Information Dictionary')
- NOTE The calculation of the file identifier need not be reproducible; all that matters is that the identifier is likely to be unique. For example, two implementations of the preceding algorithm might use different formats for the current time, causing them to produce different file identifiers for the same file created at the same time, but the uniqueness of the identifier is not affected.
A page-piece dictionary (PDF 1.3) may be used to hold private conforming product data. The data may be associated with a page or form XObject by means of the optional PieceInfo entry in the page object (see Table 30) or form dictionary (see Table 95). Beginning with PDF 1.4, private data may also be associated with the PDF document by means of the PieceInfo entry in the document catalogue (see Table 28).
- NOTE 1 Conforming products may use this dictionary as a place to store private data in connection with that document, page, or form. Such private data can convey information meaningful to the conforming product that produces it (such as information on object grouping for a graphics editor or the layer information used by Adobe Photoshop®) but may be ignored by general-purpose conforming readers.
As Table 318 shows, a page-piece dictionary may contain any number of entries, each keyed by the name of a distinct conforming product or of a well-known data type recognized by a family of conforming products. The value associated with each key shall be a data dictionary containing the private data that shall be used by the conforming product. The Private entry may have a value of any data type, but typically it is a dictionary containing all of the private data needed by the conforming product other than the actual content of the document, page, or form.
Table 318 - Entries in a page-piece dictionary
| Key | Type | Value |
|---|---|---|
| any conforming product name or well- known data type | dictionary | A data dictionary (see Table 319). |
Table 319 - Entries in an data dictionary
| Key | Type | Value |
|---|---|---|
| LastModified | date | (Required) The date and time when the contents of the document, page, or form were most recently modified by this conforming product. |
| Private | (any) | (Optional) Any private data appropriate to the conforming product, typically in the form of a dictionary. |
The LastModified entry indicates when this conforming product last altered the content of the page or form. If the page-piece dictionary contains several data dictionaries, their modification dates can be compared with those in the corresponding entry of the page object or form dictionary (see Table 30 and Table 95), or the ModDate entry of the document information dictionary (see Table 317), to ascertain which data dictionary corresponds to the current content of the page or form. Because some platforms may use only an approximate value for the date and time or may not deal correctly with differing time zones, modification dates shall be compared only for equality and not for sequential ordering.
NOTE 2 It is possible for two or more data dictionaries to have the same modification date. Conforming products can use this capability to define multiple or extended versions of the same data format. For example, suppose that earlier versions of a conforming product use an data dictionary named PictureEdit , and later versions of the same conforming product extend the data to include additional items not previously used. The original data could continue to be kept in the PictureEdit dictionary and the additional items placed in a new dictionary named PictureEditExtended . This allows the earlier versions of the conforming product to continue to work as before, and later versions are able to locate and use the extended data items.
Marked-content operators (PDF 1.2) may identify a portion of a PDF content stream as a marked-content element of interest to a particular conforming product. Marked-content elements and the operators that mark them shall fall into two categories:
- The MP and DP operators shall designate a single marked-content point in the content stream.
- The BMC , BDC , and EMC operators shall bracket a marked-content sequence of objects within the content stream.
- NOTE 1 This is a sequence not simply of bytes in the content stream but of complete graphics objects. Each object is fully qualified by the parameters of the graphics state in which it is rendered.
- NOTE 2 A graphics application, for example, might use marked content to identify a set of related objects as a group to be processed as a single unit. A text-processing application might use it to maintain a connection between a footnote marker in the body of a document and the corresponding footnote text at the bottom of the page. The PDF logical structure facilities use marked-content sequences to associate graphical content with structure elements (see 14.7.4, 'Structure Content'). Table 320 summarizes the marked-content operators.
All marked-content operators except EMC shall take a tag operand indicating the role or significance of the marked-content element to the conforming reader. All such tags shall be registered with Adobe Systems (see
Annex E) to avoid conflicts between different applications marking the same content stream. In addition to the tag operand, the DP and BDC operators shall specify a property list containing further information associated with the marked content. Property lists are discussed further in 14.6.2, 'Property Lists.'
Marked-content operators may appear only between graphics objects in the content stream. They may not occur within a graphics object or between a graphics state operator and its operands. Marked-content sequences may be nested one within another, but each sequence shall be entirely contained within a single content stream.
- NOTE 3 A marked-content sequence may not cross page boundaries.
- NOTE 4 The Contents entry of a page object (see 7.7.3.3, 'Page Objects'), which may be either a single stream or an array of streams, is considered a single stream with respect to marked-content sequences.
Table 320 - Marked-content operators
| Operands | Operator | Description |
|---|---|---|
| tag | MP | Designate a marked-content point. tag shall be a name object indicating the role or significance of the point. |
| tag properties | DP | Designate a marked-content point with an associated property list. tag shall be a name object indicating the role or significance of the point. properties shall be either an inline dictionary containing the property list or a name object associated with it in the Properties subdictionary of the current resource dictionary (see 14.6.2, 'Property Lists'). |
| tag | BMC | Begin a marked-content sequence terminated by a balancing EMC operator. tag shall be a name object indicating the role or significance of the sequence. |
| tag properties | BDC | Begin a marked-content sequence with an associated property list, terminated by a balancing EMC operator. tag shall be a name object indicating the role or significance of the sequence. properties shall be either an inline dictionary containing the property list or a name object associated with it in the Properties subdictionary of the current resource dictionary (see 14.6.2, 'Property Lists'). |
| - | EMC | End a marked-content sequence begun by a BMC or BDC operator. |
When the marked-content operators BMC , BDC , and EMC are combined with the text object operators BT and ET (see 9.4, 'Text Objects'), each pair of matching operators ( BMC … EMC , BDC … EMC , or BT … ET ) shall be properly (separately) nested. Therefore, the sequences
| BMC | BT | |
|---|---|---|
| BT | BMC | |
| … | and | … |
| ET | EMC | |
| EMC | ET | |
| are valid, but | ||
| BMC | BT | |
| BT | BMC | |
| … | and | … |
| EMC | ET | |
| BT | EMC |
are not valid.
The marked-content operators DP and BDC associate a property list with a marked-content element within a content stream. The property list is a dictionary containing private information meaningful to the conforming writer creating the marked content. Conforming products should use the dictionary entries in a consistent way; the values associated with a given key should always be of the same type (or small set of types).
If all of the values in a property list dictionary are direct objects, the dictionary may be written inline in the content stream as a direct object. If any of the values are indirect references to objects outside the content stream, the property list dictionary shall be defined as a named resource in the Properties subdictionary of the current resource dictionary (see 7.8.3, 'Resource Dictionaries') and referenced by name as the properties operand of the DP or BDC operator.
Some PDF path and text objects are defined purely for their effect on the current clipping path, without the objects actually being painted on the page. This occurs when a path object is defined using the operator sequence W n or W* n (see 8.5.4, 'Clipping Path Operators') or when a text object is painted in text rendering mode 7 (see 9.3.6, 'Text Rendering Mode'). Such clipped, unpainted path or text objects are called clipping objects . When a clipping object falls within a marked-content sequence, it shall not be considered part of the sequence unless the entire sequence consists only of clipping objects. In Example 1, for instance, the markedcontent sequence tagged Clip includes the text string ( Clip me ) but not the rectangular path that defines the clipping boundary.
% Object to be clipped
EXAMPLE 1 /Clip BMC 100 100 10 10 re W n % Clipping path ( Clip me ) Tj EMC
Only when a marked-content sequence consists entirely of clipping objects shall the clipping objects be considered part of the sequence. In this case, the sequence is known as a marked clipping sequence . Such sequences may be nested. In Example 2, for instance, multiple lines of text are used to clip a subsequent graphics object (in this case, a filled path). Each line of text shall be bracketed within a separate marked clipping sequence, tagged Pgf . The entire series shall be bracketed in turn by an outer marked clipping sequence, tagged Clip .
NOTE The marked-content sequence tagged ClippedText is not a marked clipping sequence, since it contains a filled rectangular path that is not a clipping object. The clipping objects belonging to the Clip and Pgf sequences are therefore not considered part of the ClippedText sequence.
EXAMPLE 2 /ClippedText BMC /Clip << … >> BDC BT 7 Tr % Begin text clip mode /Pgf BMC ( Line 1 ) Tj EMC /Pgf BMC ( Line ) ' ( 2 ) Tj EMC ET % Set current text clip EMC 100 100 10 10 re f % Filled path
EMC
The precise rules governing marked clipping sequences shall be as follows:
-
A clipping object shall be a path object ended by the operator sequence W n or W* n or a text object painted in text rendering mode 7.
-
An invisible graphics object shall be a path object ended by the operator n only (with no preceding W or W* ) or a text object painted in text rendering mode 3.
-
A visible graphics object shall be a path object ended by any operator other than n , a text object painted in any text rendering mode other than 3 or 7, or any XObject invoked by the Do operator.
-
An empty marked-content element shall be a marked-content point or a marked-content sequence that encloses no graphics objects.
-
A marked clipping sequence shall be a marked-content sequence that contains at least one clipping object and no visible graphics objects.
-
Clipping objects and marked clipping sequences shall be considered part of an enclosing marked-content sequence only if it is a marked clipping sequence.
-
Invisible graphics objects and empty marked-content elements shall always be considered part of an enclosing marked-content sequence, regardless of whether it is a marked clipping sequence.
-
The q (save) and Q (restore) operators may not occur within a marked clipping sequence.
Example 3 illustrates the application of these rules. Marked-content sequence S4 is a marked clipping sequence because it contains a clipping object (clipping path 2) and no visible graphics objects. Clipping path 2 is therefore considered part of sequence S4. Marked-content sequences S1, S2, and S3 are not marked clipping sequences, since they each include at least one visible graphics object. Thus, clipping paths 1 and 2 are not part of any of these three sequences.
EXAMPLE 3 /S1 BMC /S2 BMC /S3 BMC 0 0 m 100 100 l 0 100 l W n % Clipping path 1 0 0 m 200 200 l 0 100 l f % Filled path EMC /S4 BMC 0 0 m 300 300 l 0 100 l W n % Clipping path 2 EMC EMC 100 100 10 10 re f % Filled path EMC
In Example 4 marked-content sequence S1 is a marked clipping sequence because the only graphics object it contains is a clipping path. Thus, the empty marked-content sequence S3 and the marked-content point P1 are both part of sequence S2, and S2, S3, and P1 are all part of sequence S1.
EXAMPLE 4 /S1 BMC … Clipping path … /S2 BMC /S3 BMC EMC /P1 DP EMC EMC
In Example 5 marked-content sequences S1 and S4 are marked clipping sequences because the only object they contain is a clipping path. Hence the clipping path is part of sequences S1 and S4; S3 is part of S2; and S2, S3, and S4 are all part of S1.
EXAMPLE 5 /S1 BMC /S2 BMC /S3 BMC EMC EMC /S4 BMC … Clipping path … EMC EMC
PDF's logical structure facilities (PDF 1.3) shall provide a mechanism for incorporating structural information about a document's content into a PDF file. Such information may include the organization of the document into chapters and sections or the identification of special elements such as figures, tables, and footnotes. The logical structure facilities shall be extensible, allowing conforming writers to choose what structural information to include and how to represent it, while enabling conforming readers to navigate a file without knowing the producer's structural conventions.
PDF logical structure shares basic features with standard document markup languages such as HTML, SGML, and XML. A document's logical structure shall be expressed as a hierarchy of structure elements , each represented by a dictionary object. Like their counterparts in other markup languages, PDF structure elements may have content and attributes. In PDF, rendered document content takes over the role occupied by text in HTML, SGML, and XML.
A PDF document's logical structure shall be stored separately from its visible content, with pointers from each to the other. This separation allows the ordering and nesting of logical elements to be entirely independent of the order and location of graphics objects on the document's pages.
The Markings entry in the document catalogue (see 7.7.2, 'Document Catalog') shall specify a mark information dictionary , whose entries are shown in Table 321. It provides additional information relevant to specialized uses of structured PDF documents.
Table 321 - Entries in the mark information dictionary
| Key | Type | Value |
|---|---|---|
| Marked | boolean | (Optional) A flag indicating whether the document conforms to Tagged PDF conventions (see 14.8, 'Tagged PDF'). Default value: false . If Suspects is true , the document may not completely conform to Tagged PDF conventions. |
| UserProperties | boolean | (Optional; PDF 1.6) A flag indicating the presence of structure elements that contain user properties attributes (see 14.7.5.4, 'User Properties'). Default value: false . |
| Suspects | boolean | (Optional; PDF 1.6) A flag indicating the presence of tag suspects (see 14.8.2.3, 'Page Content Order'). Default value: false . |
The logical structure of a document shall be described by a hierarchy of objects called the structure hierarchy or structure tree . At the root of the hierarchy shall be a dictionary object called the structure tree root , located by means of the StructTreeRoot entry in the document catalogue (see 7.7.2, 'Document Catalog'). Table 322 shows the entries in the structure tree root dictionary. The K entry shall specify the immediate children of the structure tree root, which shall be structure elements .
Structure elements shall be represented by a dictionary, whose entries are shown in Table 323. The K entry shall specify the children of the structure element, which may be zero or more items of the following kinds:
- Other structure elements
- References to content items , which are either marked-content sequences (see 14.6, 'Marked Content') or complete PDF objects such as XObjects and annotations. These content items represent the graphical content, if any, associated with a structure element. Content items are discussed in detail in 14.7.4, 'Structure Content.'
Table 322 - Entries in the structure tree root
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be StructTreeRoot for a structure tree root. |
| K | dictionary or array | (Optional) The immediate child or children of the structure tree root in the structure hierarchy. The value may be either a dictionary representing a single structure element or an array of such dictionaries. |
| IDTree | name tree | (Required if any structure elements have element identifiers) A name tree that maps element identifiers (see Table 323) to the structure elements they denote. |
| ParentTree | number tree | (Required if any structure element contains content items) A number tree (see 7.9.7, 'Number Trees') used in finding the structure elements to which content items belong. Each integer key in the number tree shall correspond to a single page of the document or to an individual object (such as an annotation or an XObject) that is a content item in its own right. The integer key shall be the value of the StructParent or StructParents entry in that object (see 14.7.4.4, 'Finding Structure Elements from Content Items'). The form of the associated value shall depend on the nature of the object: For an object that is a content item in its own right, the value shall be an indirect reference to the object's parent element (the structure element that contains it as a content item). For a page object or content stream containing marked-content sequences that are content items, the value shall be an array of references to the parent elements of those marked-content sequences. See 14.7.4.4, 'Finding Structure Elements from Content Items' for further discussion. |
| ParentTreeNext Key | integer | (Optional) An integer greater than any key in the parent tree, shall be used as a key for the next entry added to the tree. |
| RoleMap | dictionary | (Optional) A dictionary that shall map the names of structure types used in the document to their approximate equivalents in the set of standard structure types (see 14.8.4, 'Standard Structure Types'). |
| ClassMap | dictionary | (Optional) A dictionary that shall map name objects designating attribute classes to the corresponding attribute objects or arrays of attribute objects (see 14.7.5.2, 'Attribute Classes'). |
Table 323 - Entries in a structure element dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be StructElem for a structure element. |
| S | name | (Required) The structure type, a name object identifying the nature of the structure element and its role within the document, such as a chapter, paragraph, or footnote (see 14.7.3, 'Structure Types'). Names of structure types shall conform to the guidelines described in Annex E. |
| P | dictionary | (Required; shall be an indirect reference) The structure element that is the immediate parent of this one in the structure hierarchy. |
| ID | byte string | (Optional) The element identifier, a byte string designating this structure element. The string shall be unique among all elements in the document's structure hierarchy. The IDTree entry in the structure tree root (see Table 322) defines the correspondence between element identifiers and the structure elements they denote. |
| Pg | dictionary | (Optional; shall be an indirect reference ) A page object representing a page on which some or all of the content items designated by the K entry shall be rendered. |
| K | (various) | (Optional) The children of this structure element. The value of this entry may be one of the following objects or an array consisting of one or more of the following objects: • A structure element dictionary denoting another structure element • An integer marked-content identifier denoting a marked- content sequence • A marked-content reference dictionary denoting a marked- content sequence • An object reference dictionary denoting a PDF object Each of these objects other than the first (structure element dictionary) shall be considered to be a content item; see 14.7.4, 'Structure Content' for further discussion of each of these forms of representation. If the value of K is a dictionary containing no Type entry, it shall be assumed to be a structure element dictionary. |
| A | (various) | (Optional) A single attribute object or array of attribute objects associated with this structure element. Each attribute object shall be either a dictionary or a stream. If the value of this entry is an array, each attribute object in the array may be followed by an integer representing its revision number (see 14.7.5, 'Structure Attributes,' and 14.7.5.3, 'Attribute Revision Numbers'). |
| C | name or array | (Optional) An attribute class name or array of class names associated with this structure element. If the value of this entry is an array, each class name in the array may be followed by an integer representing its revision number (see 14.7.5.2, 'Attribute Classes,' and 14.7.5.3, 'Attribute Revision Numbers'). If both the A and C entries are present and a given attribute is specified by both, the one specified by the A entry shall take precedence. |
| R | integer | (Optional) The current revision number of this structure element (see 14.7.5.3, 'Attribute Revision Numbers'). The value shall be a non-negative integer. Default value: 0. |
Table 323 - Entries in a structure element dictionary (continued)
| Key | Type | Value |
|---|---|---|
| T | text string | (Optional) The title of the structure element, a text string representing it in human-readable form. The title should characterize the specific structure element, such as Chapter 1, rather than merely a generic element type, such as Chapter. |
| Lang | text string | (Optional; PDF 1.4) A language identifier specifying the natural language for all text in the structure element except where overridden by language specifications for nested structure elements or marked content (see 14.9.2, 'Natural Language Specification'). If this entry is absent, the language (if any) specified in the document catalogue applies. |
| Alt | text string | (Optional) An alternate description of the structure element and its children in human-readable form, which is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, 'Alternate Descriptions'). |
| E | text string | (Optional; PDF 1.5) The expanded form of an abbreviation. |
| ActualText | text string | (Optional; PDF 1.4) Text that is an exact replacement for the structure element and its children. This replacement text (which should apply to as small a piece of content as possible) is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.4, 'Replacement Text'). |
Every structure element shall have a structure type , a name object that identifies the nature of the structure element and its role within the document (such as a chapter, paragraph, or footnote). To facilitate the interchange of content among conforming products, PDF defines a set of standard structure types; see 14.8.4, 'Standard Structure Types.' Conforming products are not required to adopt them, however, and may use any names for their structure types.
Where names other than the standard ones are used, a role map may be provided in the structure tree root, mapping the structure types used in the document to their nearest equivalents in the standard set.
- NOTE 1 A structure type named Section used in the document might be mapped to the standard type Sect. The equivalence need not be exact; the role map merely indicates an approximate analogy between types, allowing conforming products to share nonstandard structure elements in a reasonable way.
- NOTE 2 The same structure type may occur as both a key and a value in the role map, and circular chains of association are explicitly permitted. Therefore, a single role map may define a bidirectional mapping. A conforming reader using the role map should follow the chain of associations until it either finds a structure type it recognizes or returns to one it has already encountered.
- NOTE 3 In PDF versions earlier than 1.5, standard element types were never remapped. Beginning with PDF 1.5, an element name shall always be mapped to its corresponding name in the role map, if there is one, even if the original name is one of the standard types. This shall be done to allow the element, for example, to represent a tag with the same name as a standard role, even though its use differs from the standard role.
Any structure element may have associated graphical content, consisting of one or more content items . Content items shall be graphical objects that exist in the document independently of the structure tree but are associated with structure elements as described in the following sub-clauses. Content items are of two kinds:
- Marked-content sequences within content streams (see 14.7.4.2, 'Marked-Content Sequences as Content Items')
- Complete PDF objects such as annotations and XObjects (see 14.7.4.3, 'PDF Objects as Content Items')
The K entry in a structure element dictionary (see Table 323) shall specify the children of the structure element, which may include any number of content items, as well as child structure elements that may in turn have content items of their own.
Content items shall be leaf nodes of the structure tree; that is, they may not have other content items nested within them for purposes of logical structure. The hierarchical relationship among structure elements shall be represented entirely by the K entries of the structure element dictionaries, not by nesting of the associated content items. Therefore, the following restrictions shall apply:
- A marked-content sequence delimiting a structure content item may not have another marked-content sequence for a content item nested within it though non-structural marked content shall be allowed.
- A structure content item shall not invoke (with the Do operator) an XObject that is itself a structure content item.
A sequence of graphics operators in a content stream may be specified as a content item of a structure element in the following way:
- The operators shall be bracketed as a marked-content sequence between BDC and EMC operators (see 14.6, 'Marked Content'). Although the tag associated with a marked-content sequence is not directly related to the document's logical structure, it should be the same as the structure type of the associated structure element.
- The marked-content sequence shall have a property list (see 14.6.2, 'Property Lists') containing an MCID entry, which i shall be an integer marked-content identifier that uniquely identifies the marked-content sequence within its content stream, as shown in the following example:
EXAMPLE 1 2 0 obj << /Type /Page /Contents 3 0 R … >> endobj 3 0 obj << /Length … >> stream … /P << /MCID 0 >> BDC … … EMC
% Page object % Content stream % Page's content stream % Start of marked-content sequence ( Here is some text ) Tj % End of marked-content sequence …
endstream endobj
NOTE This example and the following examples omit required StructParents entries in the objects used as content items (see 14.7.4.4, 'Finding Structure Elements from Content Items').
Navigation: ← Previous | PDF-Spec-Index | PDF-Spec-14-Page-Piece