Matterhorn 30-001 · PDF/UA-1 UA1:7.20-1

Reference XObjects: PDF content imported from another file

Reference XObjects import content from an external file, which may not be available. PDF/UA-1 forbids them.

What a screen reader actually does

The imported content may be missing entirely.

What is in the file

A reference XObject is a form XObject with one extra entry, /Ref, that points at a page in another PDF:

41 0 obj
<< /Type /XObject /Subtype /Form
   /BBox [ 0 0 1 1 ]
   /Ref << /F << /Type /Filespec /F (charts.pdf) /UF (charts.pdf) >>
           /Page 0                       % the first page of charts.pdf
        >>
   /Length …
>>
stream
0.8 g 0 0 1 1 re f                      % the proxy: a grey box
endstream
endobj

The page paints it with Do like any other XObject. What appears depends on the viewer. If it can find charts.pdf and is willing to import from it, it draws page 1 of that file in the XObject’s place. If not, it draws the XObject’s own content stream — the proxy — which is whatever the producer put there as a stand-in: a low-resolution preview, a grey box, or nothing.

PDF/UA-1 clause 7.20 forbids reference XObjects outright.

Why they cannot be made accessible

Everything that makes a PDF readable lives inside the file: the structure tree, the marked content it points at, the Unicode mappings for the fonts. An imported page brings none of that across. Its text, if it has any, is not in this document’s structure tree and cannot be put there, because there is no marked content in this file for a structure element to own.

So there are three readers and three documents:

• A sighted reader whose viewer finds the external file sees the chart.
• A sighted reader whose viewer does not sees the proxy.
• A screen reader user gets whatever the structure tree says about the proxy, in both cases — an alternate text somebody wrote for it, if anyone did, and otherwise nothing.

Acrobat makes the uncertainty a setting. Adobe documents a Reference XObjects View Mode section in the Page Display preferences, with Show Reference XObject Targets to choose the kind of documents in which targets are shown and an optional Location Of Referenced Files (Adobe: Viewing PDFs and viewing preferences). Two people with different preferences are looking at different documents.

Where they come from

Mostly from print production. The PDF/X-5 standards allow prepress files to reference external graphical content, so that large images or shared elements can be kept out of the file and swapped in at output. A document that came through such a workflow and was then published as is — an annual report, a catalogue, a magazine — can carry references into files that only ever existed on the printer’s server.

Outside that kind of workflow they are rare.

How to check it free

veraPDF reports it against clause 7.20: “The document contains a reference XObject (Ref key in the form XObject dictionary)”.

pikepdf will list every form XObject with a /Ref entry, wherever it is in the file:

import pikepdf

with pikepdf.open("report.pdf") as pdf:
    for obj in pdf.objects:
        if isinstance(obj, pikepdf.Stream) and obj.get("/Subtype") == "/Form" and "/Ref" in obj:
            ref = obj.Ref
            print(obj.objgen, "file:", ref.get("/F"), "page:", ref.get("/Page"))

That walks every object in the file rather than every page’s resources, which matters for the limit described at the end of this page.

How to fix it free

Adobe documents no Acrobat command that resolves or removes a reference XObject; the preferences above change what is displayed, not what is in the file. The repairs are upstream or at object level.

If the source document exists, place the content and re-export. Whatever was referenced — a chart, a logo, a page of another report — goes into the source as real content, gets tagged with the rest, and the export no longer needs a reference. This is nearly always the right answer.

If the referenced file exists but the source does not, the referenced page has to be brought into this file as ordinary content and the reference removed. That needs a tool that can import a page as a form XObject, and the result needs tagging like any other new content — a Figure with alternate text for a chart, real structure for text.

If neither exists, the proxy is all there is. Delete the /Ref entry so the file stops promising content it cannot deliver, and make sure the proxy is tagged and described — or marked as an artifact, if it is decoration:

for obj in pdf.objects:
    if isinstance(obj, pikepdf.Stream) and obj.get("/Subtype") == "/Form" and "/Ref" in obj:
        del obj["/Ref"]
pdf.save("report-no-refs.pdf")

Look at the proxy first. If it is a grey box, the document has lost whatever was there, and the honest fix is to say so in the text.

What Taggart does

Taggart reads the XObjects named in each page’s resources and reports every one that carries a /Ref:

Form XObject /Fm0 on page 1 contains a /Ref entry, making it a reference XObject. PDF/UA-1 forbids these because the referenced content may not be available.

There is no repair. Resolving a reference needs a file Taggart has not been given, and choosing between the referenced content, the proxy and nothing is a decision about what the document says.

One limit: Taggart looks only at the XObjects a page lists in its own resources. A reference XObject painted from inside another form XObject — or from an annotation’s appearance — is not found. The script above will find those.

How Taggart handles it

Taggart checks for this condition automatically and reports it as a blocker, with where in the file it found it.

Where this sits in the standards

Related conditions

• 30-002 Form XObject contains MCIDs and is referenced more than onceAn MCID is only unique within one content stream. Re-using an XObject that contains MCIDs makes the structure-to-content mapping ambiguous.
• 01-005 Content is neither marked as Artifact nor tagged as real contentEvery text-showing, image-painting and path-painting operator on a page must sit either inside a marked-content sequence that maps to the structure tree, or inside an artifact sequence. Content that is in neither is orphaned.
• 13-004 Figure tag alternative or replacement text missingA Figure element has neither /Alt nor /ActualText. Every Figure must have one or the other; if the image is decorative it should be an artifact instead of a Figure.
• 21-001 File specification dictionary for an embedded file does not contain F and UF entriesEmbedded attachments must carry both the byte-string filename (F) and the Unicode filename (UF).

Other conditions in checkpoint 30

Checkpoint 30 covers xobjects. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.

• 30-002 Form XObject contains MCIDs and is referenced more than onceAn MCID is only unique within one content stream. Re-using an XObject that contains MCIDs makes the structure-to-content mapping ambiguous.

Checked with Taggart on a generated file that fails this condition on 2026-10-02. The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated 2026-10-02.