Files the Document Names without Carrying
Point the document at a file stored beside it or served from an address, listed with its attachments without travelling inside it.
See It in a Real PDF
Three lots, each attached to the document as a separate file, described by the columns the document defines itself — lot, day sent, amount — and sorted newest first. The cover page repeats the same columns in plain view, for reading software that does not show attached files.
Summary
Some files are too heavy to put inside a document: the raw readings of a survey, a film of a showroom. The document can still point at them. It lists them among its attachments, with a sentence saying what each is, and reading software opens the file from the folder beside the document, or fetches it from its address. Nothing of the file travels with the document.
Technically
Written at the top level of a request, under
"referenced_files"
Each entry is written as a file specification whose content is a path or an address rather than a stream: a path from the document to a file beside it, its components separated by a slash and resolved from the folder holding the document, or an address beginning with its scheme and spelled in 7-bit ASCII. The file is claimed by its name as an attachment is — by a page in page_files, a picture in images, a part in document_parts — and listed among the document's files, where reading software opens the path or fetches the address. The server fetches nothing. A name an attachment already took is taken over, the attachment staying tied to the document as a whole.
Request Schema
-
referenced_files— array, optional, empty by default. -
referenced_files[].name— string, required. The name the rest of the request claims the file by. -
referenced_files[].payload— object, required, holding one key of two:beside, a path from the document to the file, resolved from the folder holding the document, a path from the root, a drive, an address or a backslash being refused;at, the address the file is served from, beginning with its scheme and spelled in 7-bit ASCII. -
referenced_files[].description— string, required. What the file is, in words, for a person reading the list of files the document names. -
referenced_files[].relationship— string, required. What the file is to the document: one ofsource,alternative,data,supplement,unspecified.
A document naming a file this way states "version": "2.0", or the render comes back 400; a document claiming any part of PDF/A names none. The file itself is never read: a path that leads nowhere is written all the same.
A Whole Request That Creates a PDF
{
"version": "2.0",
"referenced_files": [
{
"name": "readings",
"payload": { "beside": "survey/readings.csv" },
"description": "Every reading of the 2026 survey",
"relationship": "data"
}
],
"standard_fonts": [{ "name": "sans", "face": "helvetica" }],
"items": [
{
"type": "text",
"rect": { "llx": 72, "lly": 700, "urx": 523, "ury": 740 },
"content": ["The survey, and the file of its readings beside it"],
"font": "sans",
"font_size": 12
}
]
}The document as a whole
The Numbers Reading Software Shows A Hundred Letters in a Single File What the Document Says about Itself What the Document Says about Itself, Said Once Text Nobody Can Copy The Notes a Program Leaves in the File for Itself The Notes a Program Leaves on One Page The Data a Program Hangs on a Run of Ink A File Still Readable Decades from Now The Print Standard the Document Claims The Variable Print Standard the Document Claims The Password That Opens It, and What May Be Done with It An Invoice a Person and a Machine Both Read The Address Relative Links Are Read Against The PDF Version the File Declares The Extensions to PDF the File Says It Uses What a Picture Says about Itself, and How It Is Read The Attachments the Document Carries Beside Its Pages The Attachments Shown as a Portfolio Which Attachments a Page Claims Which Attachments a Font Claims The Identity Card a Single Font Carries Which Attachments the Document's Card Claims A Document Card Written Elsewhere The Areas of a Page a Reader Measures In The Identity Card a Single Page Carries The Accessibility Standard the Document Claims The Standards the Finished Document Is Measured Against
Where to Go Next
Every JSON key of a request, in one page The other forty-one settings of a request