Repository navigation
PDF Spec 07 Objects
Part of: PDF-Spec-07-Syntax
Navigation: PDF-Spec-07-Lexical | PDF-Spec-Index | PDF-Spec-07-Filters
PDF includes eight basic types of objects: Boolean values, Integer and 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."
Boolean objects represent the logical values of true and false. They appear in PDF files using the keywords true and false .
PDF provides two types of 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 conforming reader is running; Annex C 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 Integer objects
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.
EXAMPLE 2 Real objects
- NOTE 1 A conforming writer shall not use the PostScript syntax for numbers with non-decimal radices (such as 16#FFFE) or in exponential format (such as 6.02E23).
- NOTE 2 Throughout this standard, the term number refers to an object whose type may be either integer or real. 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.
A string object shall consist of a series of zero or more bytes. String objects are not integer objects, but are stored in a more compact format. The length of a string may be subject to implementation limits; see Annex C.
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 sub-clause 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.
7.9.2, "String Object Types," describes the encoding schemes used for the contents of string objects.
A literal string shall be written as an arbitrary number of characters enclosed in parentheses. Any characters may appear in a string except unbalanced parentheses (LEFT PARENHESIS (28h) and RIGHT PARENTHESIS (29h)) and the backslash (REVERSE SOLIDUS (5Ch)), which shall be treated specially as described in this sub-clause. Balanced pairs of parentheses within a string require no special treatment.
EXAMPLE 1 The following are valid literal strings: ( This is a string ) ( Strings may contain newlines and such . ) ( Strings may 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. If the character following the REVERSE SOLIDUS is not one of those shown in Table 3, the REVERSE SOLIDUS shall be ignored.
Table 3 - Escape sequences in literal strings
| Sequence | Meaning |
|---|---|
| \n | LINE FEED (0Ah) (LF) |
| \r | CARRIAGE RETURN (0Dh) (CR) |
| \t | HORIZONTAL TAB (09h) (HT) |
| \b | BACKSPACE (08h) (BS) |
| \f | FORM FEED (FF) |
| ( | LEFT PARENTHESIS (28h) |
| ) | RIGHT PARENTHESIS (29h) |
| \ | REVERSE SOLIDUS (5Ch) (Backslash) |
| \ ddd | Character code ddd (octal) |
A conforming 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 conforming reader 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.
( This string has an end-of-line at the end of it .
EXAMPLE 3 ) ( 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 denotes a string containing two characters, \005 (Control-E) followed by the digit 3, whereas both the literal ( \0053 ) ( \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 conforming 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.
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 either A-F or a-f) encoded as ASCII characters and enclosed within angle brackets (using LESS-THAN SIGN (3Ch) and GREATERTHAN SIGN (3Eh)).
EXAMPLE 1 < 4E6F762073686D6F7A206B6120706F702E >
Each pair of hexadecimal digits defines one byte of the string. White-space characters (such as SPACE (20h), HORIZONTAL TAB (09h), CARRIAGE RETURN (0Dh), LINE FEED (0Ah), and FORM FEED (0Ch)) shall be ignored.
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.
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 made up of the same sequence of characters denote the same object. 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 name.
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 may be coded in either of two ways.
White space used as part of a name shall always be coded using the 2-digit hexadecimal notation and no white space may intervene between the SOLIDUS and the encoded name.
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 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-Various***Characters? | A;Name_With-Various***Characters? |
| /1.2 | 1.2 |
| /$$ | $$ |
| /@pattern | @pattern |
| /.notdef | .notdef |
| /lime#20Green | Lime Green |
| /paired#28#29parentheses | paired()parentheses |
| /The_Key_of_F#23_Minor | The_Key_of_F#_Minor |
| /A#42 | AB |
In PDF, literal names shall always be introduced by the SOLIDUS character (/), unlike keywords such as true , false , and obj .
- NOTE 3 This standard 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 standard) as /Type and /FullScreen.
The length of a name shall be subject to an implementation limit; see Annex C. 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 conforming reader. 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 111), a colorant 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 (after expansion of NUMBER SIGN sequences, if any) 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 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 may represent the same logical text. Name objects defined by different sequences of bytes constitute distinct name objects in PDF, even though the UTF-8 sequences may have identical external interpretations.
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 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 ]
PDF directly supports only one-dimensional arrays. Arrays of higher dimension can be constructed by using arrays as elements of arrays, nested to any depth.
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 PostScript, which may be objects of any type). The value may be any kind of object, including another dictionary. 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 PostScript, where null behaves like any other object as the value of a dictionary entry.) The number of entries in a dictionary shall be subject to an implementation limit; see Annex C. A dictionary may have zero entries.
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 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 document. 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 specialized 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 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 standard or a registered name; see Annex E for details.
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 sub-clause 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 represent.
A stream shall consist of a dictionary followed by zero or more bytes bracketed between the keywords stream (followed by newline) and endstream :
EXAMPLE
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-of-line 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.
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 conforming reader.
- NOTE 2 Without the restriction against following the keyword stream by a CARRIAGE RETURN alone, it would be impossible to differentiate 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 endof-line.
Table 5 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."
Every stream dictionary shall have a Length entry that indicates how many bytes of the PDF file are 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 shall 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.
It is also an error if the stream contains 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 of a filter that shall be applied in processing the stream data found between the keywords stream and endstream , or an array of zero, one or several names. Multiple filters shall be specified in the order in which they are to be applied. |
| DecodeParms | dictionary or array | (Optional) A parameter dictionary or an array of such dictionaries, used by the filters specified by Filter . 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: 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. |
| F | file specification | (Optional; PDF 1.2) The file containing the stream data. If this entry is 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 | (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 . |
| FDecodeParms | dictionary or array | (Optional; PDF 1.2) A parameter dictionary, or an array of such dictionaries, used by the filters specified by FFilter . The same rules apply as for DecodeParms . |
Table 5 - Entries common to all stream dictionaries (continued)
| Key | Type | Value |
|---|---|---|
| DL | integer | (Optional; PDF 1.5) A non-negative integer representing the number of bytes in the decoded (defiltered) stream. It can be used to determine, for example, whether enough disk space is available to write a stream to a file. This value shall be considered a hint only; for some stream filters, it may not be possible to determine this value precisely. |
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.
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. Nonzero generation numbers may be introduced when the file is later updated; see subclauses 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 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 white space separating each part):
12 0 R
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 conforming reader; 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 were 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 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 >> % An indirect reference to object 8 stream BT /F1 12 Tf 72 712 Td ( A stream with an indirect length ) Tj ET endstream endobj 8 0 obj 77 % The length of the preceding stream endobj
Navigation: PDF-Spec-07-Lexical | PDF-Spec-Index | PDF-Spec-07-Filters