PDF20 Spec 07 Objects

7.3 Objects

Part of: PDF20-Spec-07-Syntax

Navigation: PDF20-Spec-07-Lexical | PDF20-Spec-Index | PDF20-Spec-07-Filters

7.3

Objects

7.3.1 General PDF syntax includes nine basic types of objects: boolean values, integers, real numbers, strings, names, arrays, dictionaries, streams, and the null object. Objects may be labelled so that they can be referred to by other objects. A labelled object is called an indirect object (see 7.3.10, "Indirect objects"). Each object type, their method of creation and their proper referencing as indirect objects is described in 7.3.2, "Boolean objects" through 7.3.10, "Indirect objects".

7.3.2 Boolean objects Boolean objects represent the logical values of true and false. They appear in PDF files using the keywords true and false. See 4, "Notation", for more information regarding the notation of these keywords throughout this document.

7.3.3 Numeric objects PDF syntax provides two types of basic numeric objects: integer and real. Integer objects represent mathematical integers. Real objects represent mathematical real numbers. The range and precision of numbers may be limited by the internal representations used in the computer on which the PDF processor is running; Annex C, "Advice on maximising portability", gives these limits for typical implementations. An integer shall be written as one or more decimal digits optionally preceded by a sign. The value shall be interpreted as a signed decimal integer and shall be converted to an integer object. EXAMPLE 1 123

Integer objects 43445 +17

-98

0

A real value shall be written as one or more decimal digits with an optional sign and a leading, trailing, or embedded PERIOD (2Eh) (decimal point). The value shall be interpreted as a real number and shall be converted to a real object. A real number shall not be present when an integer is expected. Wherever a real number is expected, an integer may be used instead. For example, it is not necessary to write the number 1.0 in real format; the integer 1 is sufficient. EXAMPLE 2

Real objects

34.5

-3.62 +123.6

-.002 0

A PDF writer shall not use the PostScript language syntax for numbers with non-decimal radices (such as 16#FFFE) or in exponential format (such as 6.02E23). Throughout this document, the term number refers to an object whose type can be either integer or real.

24

ISO 32000-2:2020(E)

7.3.4 String objects 7.3.4.1

General

A string object shall consist of a series of zero or more bytes. The maximum length of a string used in the computer on which the PDF processor is running may be subject to implementation limits; see Annex C, "Advice on maximising portability". String objects shall be written in one of the following two ways: •

As a sequence of literal characters enclosed in parentheses () (using LEFT PARENTHESIS (28h) and RIGHT PARENTHESIS (29h)); see 7.3.4.2, "Literal strings"

•

As hexadecimal data enclosed in angle brackets <> (using LESS-THAN SIGN (3Ch) and GREATERTHAN SIGN (3Eh)); see 7.3.4.3, "Hexadecimal strings"

NOTE

In many contexts, conventions exist for the interpretation of the contents of a string value. This subclause defines only the basic syntax for writing a string as a sequence of bytes; conventions or rules governing the contents of strings in particular contexts are described with the definition of those particular contexts.

Subclause 7.9.2, "String object types" describes the encoding schemes used for the contents of string objects.

7.3.4.2

Literal strings

A literal string shall be written as an arbitrary number of characters enclosed in parentheses (LEFT PARENHESIS (28h) and RIGHT PARENTHESIS (29h)). Any characters may appear in a string except unbalanced parentheses and the backslash (REVERSE SOLIDUS (5Ch)), which shall be treated specially as described in this subclause. Balanced pairs of parentheses within a string require no special treatment. EXAMPLE 1

The following are valid literal strings:

(This is a string) (Strings can contain newlines and such.) (Strings can contain balanced parentheses () and special characters ( * ! & } ^ %and so on) .) (The following is an empty string .) () (It has zero (0) length.)

Within a literal string, the REVERSE SOLIDUS is used as an escape character. The character immediately following the REVERSE SOLIDUS determines its precise interpretation as shown in "Table 3 — Escape sequences in literal strings". If the character following the REVERSE SOLIDUS is not one of those shown in "Table 3 — Escape sequences in literal strings", the REVERSE SOLIDUS shall be ignored. Table 3 — Escape sequences in literal strings Sequence

Meaning

\n

LINE FEED (0Ah) (LF)

25

ISO 32000-2:2020(E)

Sequence

Meaning

\r

CARRIAGE RETURN (0Dh) (CR)

\t

HORIZONTAL TAB (09h) (HT)

\b

BACKSPACE (08h) (BS)

\f

FORM FEED (0Ch) (FF)

(

LEFT PARENTHESIS (28h)

)

RIGHT PARENTHESIS (29h)

\

REVERSE SOLIDUS (5Ch) (Backslash)

\ddd

Character code ddd (octal)

A PDF writer may split a literal string across multiple lines. The REVERSE SOLIDUS (5Ch) (backslash character) at the end of a line shall be used to indicate that the string continues on the following line. A PDF processor shall disregard the REVERSE SOLIDUS and the end-of-line marker following it when reading the string; the resulting string value shall be identical to that which would be read if the string were not split. EXAMPLE 2 (These
two strings
are the same.) (These two strings are the same.)

An end-of-line marker appearing within a literal string without a preceding REVERSE SOLIDUS shall be treated as a byte value of (0Ah), irrespective of whether the end-of-line marker was a CARRIAGE RETURN (0Dh), a LINE FEED (0Ah), or both. EXAMPLE 3 (This string has an end-of-line at the end of it. ) (So does this one.\n)

The \ddd escape sequence provides a way to represent characters outside the printable ASCII character set. EXAMPLE 4 (This string contains \245two octal characters\307.)

The number ddd may consist of one, two, or three octal digits; high-order overflow shall be ignored. Three octal digits shall be used, with leading zeros as needed, if the next character of the string is also a digit. EXAMPLE 5 the literal

26

ISO 32000-2:2020(E)

(\0053)

denotes a string containing two characters, \005 (Control-E) followed by the digit 3, whereas both (\053)

and (\53)

denote strings containing the single character \053, a plus sign (+).

Since any 8-bit value may appear in a string (with proper escaping for REVERSE SOLIDUS (backslash) and unbalanced PARENTHESES) this \ddd notation provides a way to specify characters outside the ASCII character set by using ASCII characters only. However, any 8-bit value may appear in a string, represented either as itself or with the \ddd notation described. When a document is encrypted (see 7.6, "Encryption"), all of its strings are encrypted; the encrypted string values contain arbitrary 8-bit values. When writing encrypted strings using the literal string form, the PDF writer shall follow the rules described. That is, the REVERSE SOLIDUS character shall be used as an escape to specify unbalanced PARENTHESES or the REVERSE SOLIDUS character itself. The REVERSE SOLIDUS may, but is not required, to be used to specify other, arbitrary 8-bit values.

7.3.4.3

Hexadecimal strings

Strings may also be written in hexadecimal form, which is useful for including arbitrary binary data in a PDF file. A hexadecimal string shall be written as a sequence of hexadecimal digits (0–9 and A–F or a– f) encoded as ASCII characters and enclosed within angle brackets (using LESS-THAN SIGN (3Ch) and GREATER-THAN SIGN (3Eh)). EXAMPLE 1 <4E6F762073686D6F7A206B6120706F702E>

Each pair of hexadecimal digits defines one byte of the string. White-space characters (see “Table 1 — White-space characters”) shall be ignored. The empty string can be represented in a hexadecimal string by a LESS-THAN SIGN (3Ch) immediately followed by a GREATER-THAN SIGN (3Eh). If the final digit of a hexadecimal string is missing — that is, if there is an odd number of digits — the final digit shall be assumed to be 0. EXAMPLE 2 <901FA3>

is a 3-byte string consisting of the characters whose hexadecimal codes are 90, 1F, and A3, but <901FA>

is a 3-byte string containing the characters whose hexadecimal codes are 90, 1F, and A0.

7.3.5 Name objects Beginning with PDF 1.2 a name object is an atomic symbol uniquely defined by a sequence of any characters (8-bit values) except null (character code 0). Uniquely defined means that any two name objects that, after all escaping is expanded (see below), and the resulting sequences of bytes are not an exact binary match denote different objects. Atomic means that a name has no internal structure; although it is defined by a sequence of characters, those characters are not considered elements of the © ISO 2020 – All rights reserved

27

ISO 32000-2:2020(E)

name. Even though a name may contain any characters except null, in order to express a name following the general rules for parsing PDF files, when written into a PDF file names should be encoded as described in the succeeding paragraphs. When writing a name in a PDF file, a SOLIDUS (2Fh) (/) shall be used to introduce a name. The SOLIDUS is not part of the name but is a prefix indicating that what follows is a sequence of characters representing the name in the PDF file and shall follow these rules: a) A NUMBER SIGN (23h) (#) in a name shall be written by using its 2-digit hexadecimal code (23), preceded by the NUMBER SIGN. b) Any character in a name that is a regular character (other than NUMBER SIGN) shall be written as itself or by using its 2-digit hexadecimal code, preceded by the NUMBER SIGN. c) Any character that is not a regular character shall be written using its 2-digit hexadecimal code, preceded by the NUMBER SIGN only. NOTE 1

There is not a unique encoding of names into the PDF file because regular characters can be coded in either of two ways.

No token delimiter (such as white-space) occurs between the SOLIDUS and the encoded name. Whitespace used as part of a name shall always be coded using the 2-digit hexadecimal notation. Regular characters that are outside the range EXCLAMATION MARK(21h) (!) to TILDE (7Eh) (~) should be written using the hexadecimal notation. The token SOLIDUS (a slash followed by no regular characters) introduces a unique valid name defined by the empty sequence of characters. NOTE 2

The examples shown in "Table 4 — Examples of literal names" and containing # are not valid literal names in PDF 1.0 or 1.1.

Table 4 — Examples of literal names Syntax for Literal name

Resulting Name

/Name1

Name1

/ASomewhatLongerName

ASomewhatLongerName

/A;Name_With-VariousCharacters? A;Name_With-VariousCharacters?

28

/1.2

1.2

/$$

$$

/@pattern

@pattern

/.notdef

.notdef

/Lime#20Green

Lime Green

/paired#28#29parentheses

paired()parentheses

/The_Key_of_F#23_Minor

ISO 32000-2:2020(E)

Syntax for Literal name

Resulting Name

/A#42

AB

In PDF syntax, literal names shall always be introduced by the SOLIDUS character (/), unlike keywords such as stream, endstream, and obj. NOTE 3

This document follows a typographic convention of writing names without the leading SOLIDUS when they appear in running text and tables. For example, Type and FullScreen denote names that would actually be written in a PDF file (and in code examples in this document) as /Type and /FullScreen.

The maximum length of a name used in the computer on which the PDF processor is running may be subject to an implementation limit; see Annex C, "Advice on maximising portability". The limit applies to the number of characters in the name’s internal representation. For example, the name /A#20B has three characters (A, SPACE, B), not six. As stated above, name objects shall be treated as atomic within a PDF file. Ordinarily, the bytes making up the name are never treated as text to be presented to a human user or to an application external to a PDF processor. However, occasionally the need arises to treat a name object as text, such as one that represents a font name (see the BaseFont entry in "Table 109 — Entries in a Type 1 font dictionary"), a colourant name in a Separation or DeviceN colour space, or a structure type (see 14.7.3, "Structure types"). In such situations, the sequence of bytes making up the name object should be interpreted according to UTF-8, a variable-length byte-encoded representation of Unicode in which the printable ASCII characters have the same representations as in ASCII. This enables a name object to represent text virtually in any natural language, subject to the implementation limit on the length of a name. NOTE 4

PDF syntax does not prescribe what UTF-8 sequence to choose for representing any given piece of externally specified text as a name object. In some cases, multiple UTF-8 sequences can represent the same logical text. PDF name objects are considered distinct objects if, after all escaping is expanded, the resulting sequences of bytes are not an exact binary match.

7.3.6 Array objects An array object is a one-dimensional collection of objects arranged sequentially. Unlike arrays in many other computer languages, PDF arrays may be heterogeneous; that is, an array’s elements may be any combination of numbers, strings, dictionaries, or any other objects, including other arrays. An indirect reference (see 7.3.10, "Indirect objects") shall be used to refer to a stream object, and may also be used to refer to any other kind of object. An array may have zero elements. An array shall be written as a sequence of objects enclosed in SQUARE BRACKETS (using LEFT SQUARE BRACKET (5Bh) and RIGHT SQUARE BRACKET (5Dh)). EXAMPLE [549 3.14 false (Ralph) /SomeName]

29

ISO 32000-2:2020(E)

7.3.7 Dictionary objects A dictionary object is an associative table containing pairs of objects, known as the dictionary’s entries. The first element of each entry is the key and the second element is the value. The key shall be a name (unlike dictionary keys in the PostScript language, which may be objects of any type). All keys shall be direct objects. The value may be any kind of object, including another dictionary. An indirect reference (see 7.3.10, "Indirect objects") shall be used as the value to refer to a stream object, and may also be used to refer to any other kind of object. A dictionary entry whose value is null (see 7.3.9, "Null object") shall be treated the same as if the entry does not exist. (This differs from the PostScript language, where null behaves like any other object as the value of a dictionary entry.) The maximum number of entries in a dictionary used in the computer on which the PDF processor is running may be subject to implementation limits; see Annex C, "Advice on maximising portability". A dictionary may have zero entries. NOTE 1

The statement requiring dictionary keys to always be direct objects was added in this document (2020).

The entries in a dictionary represent an associative table and as such shall be unordered even though an arbitrary order may be imposed upon them when written in a file. That ordering shall be ignored. Multiple entries in the same dictionary shall not have the same key. A dictionary shall be written as a sequence of key-value pairs enclosed in double angle brackets (<<…>>) (using LESS-THAN SIGNs (3Ch) and GREATER-THAN SIGNs (3Eh)). EXAMPLE <</Type /Example /Subtype /DictionaryExample /Version 0.01 /IntegerItem 12 /StringItem (a string) /Subdictionary << /Item1 0.4 /Item2 true /LastItem (not !) /VeryLastItem (OK)

NOTE 2

Do not confuse the double angle brackets with single angle brackets (< and >) (using LESS-THAN SIGN (3Ch) and GREATER-THAN SIGN (3Eh)), which delimit a hexadecimal string (see 7.3.4.3, "Hexadecimal strings").

Dictionary objects are the main building blocks of a PDF file. They are commonly used to collect and tie together the attributes of a complex object, such as a font or a page of the document, with each entry in the dictionary specifying the name and value of an attribute. By convention, the Type entry of such a dictionary, if present, identifies the type of object the dictionary describes. In some cases, a Subtype entry (sometimes abbreviated S) may be used to further identify a specialised subcategory of the general type. The value of the Type or Subtype entry shall always be a name. For example, in a font dictionary, the value of the Type entry shall always be Font, whereas that of the Subtype entry may be Type1, TrueType, or one of several other values. The value of the Type entry can almost always be inferred from context. The value of an entry in a page's font resource dictionary, for example, shall be a font object; therefore, the Type entry in a font 30

ISO 32000-2:2020(E)

dictionary serves primarily as documentation and as information for error checking. The Type entry shall not be required unless so stated in its description; however, if the entry is present, it shall have the correct value. In addition, the value of the Type entry in any dictionary, even in private data, shall be either a name defined in this document or a registered name; see Annex E, "Extending PDF", for details.

7.3.8 Stream objects 7.3.8.1

General

A stream object, like a string object, is a sequence of bytes. Furthermore, a stream may be of unlimited length, whereas a string shall be subject to an implementation limit. For this reason, objects with potentially large amounts of data, such as images and page descriptions, shall be represented as streams. NOTE 1

This subclause describes only the syntax for writing a stream as a sequence of bytes. The context in which a stream is referenced determines what the sequence of bytes represents.

A stream shall consist of a dictionary followed by zero or more bytes bracketed between the keywords stream (followed by newline) and endstream: dictionary stream …Zero or more bytes… endstream

All streams shall be indirect objects (see 7.3.10, "Indirect objects") and the stream dictionary shall be a direct object. The keyword stream that follows the stream dictionary shall be followed by an end-ofline marker consisting of either a CARRIAGE RETURN and a LINE FEED or just a LINE FEED, and not by a CARRIAGE RETURN alone. The sequence of bytes that make up a stream lie between the end-of-line marker following the stream keyword and the endstream keyword; the stream dictionary specifies the exact number of bytes. There should be an end-of-line marker after the data and before endstream; this marker shall not be included in the stream length. There shall not be any extra bytes, other than white-space, between endstream and endobj. NOTE 2

Without the restriction against following the keyword stream by a CARRIAGE RETURN alone, differentiating a stream that uses CARRIAGE RETURN as its end-of-line marker and has a LINE FEED as its first byte of data from one that uses a CARRIAGE RETURN–LINE FEED sequence to denote end-of-line is not possible.

Alternatively, beginning with PDF 1.2, the bytes may be contained in an external file, in which case the stream dictionary specifies the file, and any bytes between stream and endstream shall be ignored by a PDF processor. "Table 5 — Entries common to all stream dictionaries" lists the entries common to all stream dictionaries; certain types of streams may have additional dictionary entries, as indicated where those streams are described. The optional entries regarding filters for the stream indicate whether and how the data in the stream shall be transformed (decoded) before it is used. Filters are described further in 7.4, "Filters".

7.3.8.2

Stream extent

31

ISO 32000-2:2020(E)

used for the stream’s data. (If the stream has a filter, Length shall be the number of bytes of encoded data.) In addition, most filters are defined so that the data shall be self-limiting; that is, they use an encoding scheme in which an explicit end-of-data (EOD) marker delimits the extent of the data. Finally, streams are used to represent many objects from whose attributes a length can be inferred. All of these constraints shall be consistent. EXAMPLE

An image with 10 rows and 20 columns, using a single colour component and 8 bits per component, requires exactly 200 bytes of image data. If the stream uses a filter, there needs to be enough bytes of encoded data in the PDF file to produce those 200 bytes. An error occurs if Length is too small, if an explicit EOD marker occurs too soon, or if the decoded data does not contain 200 bytes.

Streams shall also not contain too much data, with the exception that there may be an extra end-of-line marker in the PDF file before the keyword endstream. Table 5 — Entries common to all stream dictionaries Key

Type

Value

Length

integer

(Required) The number of bytes from the beginning of the line following the keyword stream to the last byte just before the keyword endstream. (There may be an additional EOL marker, preceding endstream, that is not included in the count and is not logically part of the stream data.) See 7.3.8.2, "Stream extent", for further discussion.

Filter

name or array

(Optional) The name, or an array of zero, one or several names, of filter(s) that shall be applied in processing the stream data found between the keywords stream and endstream. Multiple filters shall be specified in the order in which they are to be applied. NOTE

It is not recommended to include the same filter more than once in a Filter array.

DecodeParms

dictionary or array

F

file (Optional; PDF 1.2) The file containing the stream data. If this entry is specification present, the bytes between stream and endstream shall be ignored. However, the Length entry should still specify the number of those bytes (usually, there are no bytes and Length is 0). The filters that are applied to the file data shall be specified by FFilter and the filter parameters shall be specified by FDecodeParms.

FFilter

name or array

32

(Optional) A parameter dictionary or an array of such dictionaries, used by the filters specified by Filter, respectively. If there is only one filter and that filter has parameters, DecodeParms shall be set to the filter’s parameter dictionary unless all the filter’s parameters have their default values, in which case the DecodeParms entry may be omitted. If there are multiple filters and any of the filters has parameters set to nondefault values, DecodeParms shall be an array with one entry for each filter in the same order as the Filter array: either the parameter dictionary for that filter, or the null object if that filter has no parameters (or if all of its parameters have their default values). If none of the filters have parameters, or if all their parameters have default values, the DecodeParms entry may be omitted.

(Optional; PDF 1.2) The name of a filter to be applied in processing the data found in the stream’s external file, or an array of zero, one or several such names. The same rules apply as for Filter.

ISO 32000-2:2020(E)

Key

Type

Value

FDecodeParms dictionary or array

(Optional; PDF 1.2) A parameter dictionary, or an array of such dictionaries, used by the filters specified by FFilter, respectively. The same rules apply as for DecodeParms.

DL

(Optional; PDF 1.5) A non-negative integer representing the number of bytes in the decoded (defiltered) stream. This value is only a hint; for some stream filters, it may not be possible to determine this value precisely.

integer

7.3.9 Null object The null object has a type and value that are unequal to those of any other object. There shall be only one object of type null, denoted by the keyword null. An indirect object reference (see 7.3.10, "Indirect objects") to a nonexistent object shall be treated the same as a null object. Specifying the null object as the value of a dictionary entry (7.3.7, "Dictionary objects") shall be equivalent to omitting the entry entirely.

7.3.10

Indirect objects

Any object in a PDF file may be labelled as an indirect object. This gives the object a unique object identifier by which other objects can refer to it (for example, as an element of an array or as the value of a dictionary entry). The object identifier shall consist of two parts: •

A positive integer object number. Indirect objects may be numbered sequentially within a PDF file, but this is not required; object numbers may be assigned in any arbitrary order.

•

A non-negative integer generation number. In a newly created file, all indirect objects shall have generation numbers of 0. Non-zero generation numbers may be introduced when the file is later updated; see 7.5.4, "Cross-reference table" and 7.5.6, "Incremental updates"

Together, the combination of an object number and a generation number shall uniquely identify an indirect object. The definition of an indirect object in a PDF file shall consist of its object number and generation number (separated by white-space), followed by the value of the object bracketed between the keywords obj and endobj. EXAMPLE 1

Indirect object definition

12 0 obj (Brillig) endobj

Defines an indirect string object with an object number of 12, a generation number of 0, and the string value Brillig.

The object may be referred to from elsewhere in the file by an indirect reference. Such indirect references shall consist of the object number, the generation number, and the keyword R (with whitespace separating each part): 12 0 R

33

ISO 32000-2:2020(E)

NOTE

(2020) Any object outside of an object stream (see 7.5.7, "Object streams") can consist solely of an object reference. PDF syntax thus permits chains of such objects.

Beginning with PDF 1.5, indirect objects may reside in object streams (see 7.5.7, "Object streams"). They are referred to in the same way; however, their definition shall not include the keywords obj and endobj, and their generation number shall be zero. An indirect reference to an undefined object shall not be considered an error by a PDF processor; it shall be treated as a reference to the null object. EXAMPLE 2

If a file contains the indirect reference 17 0 R but does not contain the corresponding definition then the indirect reference is considered to refer to the null object.

Except where documented to the contrary, any object value may be a direct or an indirect reference; the semantics are equivalent. EXAMPLE 3

The following shows the use of an indirect object to specify the length of a stream. The value of the stream’s Length entry is an integer object that follows the stream in the file. This allows applications that generate PDF files in a single pass to defer specifying the stream’s length until after its contents have been generated.

7 0 obj <</Length 8 0 R>> stream BT /F1 12 Tf 72 712 Td (A stream with an indirect length) Tj ET endstream endobj 8 0 obj 77 endobj

Navigation: PDF20-Spec-07-Lexical | PDF20-Spec-Index | PDF20-Spec-07-Filters

PDF20 Spec 07 Objects

7.3 Objects

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!