A cross-reference stream is a regular PDF stream object whose stream dictionary includes cross-reference-specific entries in addition to the standard stream dictionary entries:

<strong>/Type /XRef</strong> — Marks the object as a cross-reference stream. Required.

<strong>/Size</strong> — The total number of objects in the PDF (same semantics as in the traditional xref table trailer dictionary). Required.

<strong>/W</strong> — A three-element array specifying the byte widths of each field in each cross-reference entry. The three fields are: type (0, 1, or 2), field 2 (meaning depends on type), and field 3 (meaning depends on type). Example: <code>/W [1 3 1]</code> means the type field is 1 byte, field 2 is 3 bytes, and field 3 is 1 byte.

<strong>/Index</strong> — An array specifying which object numbers the entries in this stream cover, in the format <code>[first_obj_num count first_obj_num count ...]</code>. Optional; if absent, the stream covers objects 0 to /Size-1.

<strong>/Prev</strong> — The byte offset of the previous cross-reference stream in the file (for incremental updates). Same role as /Prev in the traditional xref trailer.

The cross-reference stream also incorporates the trailer dictionary entries directly (eliminating the need for a separate <code>trailer</code> keyword block): /Root (the document catalogue), /Info (document information dictionary), /Encrypt, and /ID.

Each entry in a cross-reference stream describes one object. The entry type (field 1) determines how the remaining fields are interpreted:

<strong>Type 0 — Free objects</strong>: The object is free (deleted or not yet used). Field 2 is the object number of the next free object in the free list. Field 3 is the generation number to be used when the object is next allocated. This is the compressed equivalent of the <code>f</code> (free) entry type in a traditional xref table.

<strong>Type 1 — In-use objects (uncompressed)</strong>: The object is an uncompressed, directly accessible object. Field 2 is the byte offset of the object from the beginning of the file. Field 3 is the object's generation number. This is the compressed equivalent of the <code>n</code> (in-use) entry type in a traditional xref table.

<strong>Type 2 — In-use objects (compressed, in an object stream)</strong>: The object is compressed within an <a href="https://pdftheguide.com/glossary/pdf-object-stream" target="_blank" rel="noopener">object stream</a>. Field 2 is the object number of the containing object stream. Field 3 is the index of this object within the object stream (zero-based). There is no generation number for type 2 entries — compressed objects always have generation 0.

The binary encoding means that reading a cross-reference stream requires decompressing the stream, then parsing fixed-width binary records according to the /W field widths. PDF parsers that only support traditional xref tables cannot read cross-reference stream files correctly.

Cross-reference streams and object streams were introduced together in PDF 1.5 as a package of compression improvements. They work together:

<strong>Object streams</strong> (<code>/Type /ObjStm</code>) group multiple indirect objects together into a single compressed stream. Each compressed object within the stream is assigned a sequential index (0, 1, 2, ...). The objects themselves have normal object numbers, but instead of residing at byte offsets in the file, they exist only within the object stream.

<strong>Cross-reference streams track object stream members</strong> using Type 2 entries. When a PDF viewer needs to read object 42 (which is compressed in object stream 100, at index 3), the xref stream entry for object 42 is: type=2, field2=100 (object stream number), field3=3 (index within stream). The viewer reads object stream 100, decompresses it, and locates the third object within it.

<strong>File size reduction</strong>: The combination of cross-reference streams and object streams typically reduces PDF file size by 10–30% for text-heavy documents. The reduction is more significant for files with many small objects (typical in documents with extensive metadata, bookmarks, or complex structure trees).

<strong>Linearisation interaction</strong>: Linearised PDFs (optimised for fast web display) can use cross-reference streams. The linearisation dictionary and hints tables interact with cross-reference streams in a specific way defined in the PDF specification.

<strong>Compatibility</strong>: PDF viewers that do not support PDF 1.5+ (increasingly rare, but still encountered in some legacy embedded systems) cannot read cross-reference streams. For maximum compatibility, some PDF creation tools offer a "save as PDF 1.4" option that expands object streams and writes traditional xref tables.