What the Document Says about Itself
Give the file its title, its author, its subject, its date, and if needed entries from a vocabulary of your own.
See It in a Real PDF
Two identical pages that draw the structure of an invoice with lines and rectangles, without a word of text: the file is about a dozen kilobytes and embeds no font.
Open the PDF The Whole Example
Also shown in: A Document That Reads Freely and Asks Not to Be Copied · A Document That Asks for a Password Before It Opens · Every Linear Barcode on One Page
Summary
On the spine of a binder, you write what is inside: the title, who prepared it, what it is about, when it dates from. A digital document does the same, except the software is what reads the label — and it also says which program the document came out of: an accounting package, a spreadsheet, a drawing program. It is there to find the file again later, to put it away, to know what you hold without opening it.
Technically
Written at the top level of a request, under
"metadata"
metadata writes the document's /Info dictionary and its XMP /Metadata packet, and keeps the two in step: every field is written into both, the two an archiving standard holds to each other. Only the entries of metadata.info reach the entries alone, no property of the packet standing for them. A vocabulary of the customer's own is added through schemas, with its properties and their descriptions, the latter being what lets a checker accept names the standard never heard of. The root key information_dictionary set to false drops the /Info dictionary and keeps the packet alone, under whatever version the request declares.
Request Schema
-
metadata— object, optional, absent by default. -
metadata.title— string, optional. The document's title. -
metadata.author— string, optional. Who wrote it. -
metadata.subject— string, optional. What it is. -
metadata.keywords— string, optional. The words the document is to be found by. -
metadata.creator— string, optional. The program the original document was written in. -
metadata.producer— string, optional. What created it. -
metadata.created— string, optional. The date, in ISO 8601, for instance2026-08-08T10:00:00+02:00. -
metadata.modified— string, optional. The date the document was last changed, in the same shapes. A document stating none was last changed when it was created. -
metadata.trapped— string, optional. Three values:yes,no,unknown. Says whether the document has been prepared for the ink spreading at the press. Saying nothing carries a different meaning from sayingno. -
metadata.schemas— array, optional, empty by default. The customer's own vocabularies. -
schemas[].name,schemas[].namespace,schemas[].prefix— strings, all required. Prefixes the library reserves for itself are refused. -
schemas[].properties— array, required, an empty one being refused. -
properties[].name,properties[].description— strings, both required; an empty description is refused. -
properties[].value— required. A string, or a list or a structure as an object:{"seq": […]}for a list in order,{"bag": […]}for one in no order,{"alt": […]}for alternatives,{"structure": [{"field": name, "value": …}, …]}for named fields, nested as deep as the type says. One text in several languages is{"lang_alt": [{"language": tag, "text": …}, …]}, the version a reader takes when none is asked for first, under the tagx-default. -
properties[].value_type— string or object, optional,textby default. Nine words:boolean,date,integer,mime_type,proper_name,real,text,uri,url. A list is{"seq": item},{"bag": item}or{"alt": item}, its items a word or a structure; a structure is{"structure": …}. The wordlang_altreads the value as one text in several languages: a text with no version, a version naming no language or one language given twice, case aside, is refused. -
A structure states
name,namespace,prefix,descriptionandfields, each field aname, avalue_typeand adescription. It is described in the packet beside its schema, so that an archival validator checks its fields too. A value whose shape is not its type's is refused. -
properties[].category— string, optional,internalby default. Two values:internal,external. -
metadata.declarations— array, optional. The specifications the document declares it conforms to, each{"conforms_to": address, "claims": […]}, a claim statingby, who makes it,date,credentials, what qualifies them, andreport, the address of the report it rests on. A declaration proves nothing: nothing checks the file against the specification it names.
The properties are written into the packet whatever else the request says; their description is written beside them when the document claims a standard that asks to be able to look them up.
Archiving: a document claiming pdfa3b writes what it says about itself in both places, while a document claiming pdfa4 writes the packet alone — that standard carries no entries at all. A request naming an entry through metadata.info under pdfa4 is refused, the entry having nowhere else to go.
A Whole Request That Creates a PDF
{
"metadata": {
"schemas": [
{
"name": "Board papers",
"namespace": "https://example.test/ns/board/",
"prefix": "board",
"properties": [
{
"name": "Sitting",
"value": "2026-08-08",
"description": "The day the board sat",
"value_type": "date",
"category": "external"
},
{
"name": "Present",
"value": { "bag": ["Claire Vasseur", "Jan de Vries"] },
"description": "Who sat",
"value_type": { "bag": "proper_name" }
},
{
"name": "Resolutions",
"value": {
"seq": [
{
"structure": [
{ "field": "Number", "value": "1" },
{ "field": "Carried", "value": "True" }
]
}
]
},
"description": "What the board resolved, in order",
"value_type": {
"seq": {
"name": "Resolution",
"namespace": "https://example.test/ns/resolution/",
"prefix": "res",
"description": "One resolution put to the vote",
"fields": [
{
"name": "Number",
"value_type": "integer",
"description": "Its number in the minutes"
},
{
"name": "Carried",
"value_type": "boolean",
"description": "Whether it was carried"
}
]
}
}
}
]
}
],
"title": "Minutes of the board meeting",
"author": "Claire Vasseur",
"subject": "Board meeting of 8 August 2026",
"creator": "The board secretariat system",
"created": "2026-08-08T10:00:00+02:00"
},
"standard_fonts": [{ "name": "sans", "face": "helvetica" }],
"items": [
{
"type": "text",
"rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 768 },
"content": ["Minutes of the board meeting"],
"font": "sans",
"font_size": 18
}
]
}
The document as a whole
The Numbers Reading Software Shows A Hundred Letters in a Single File 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 Files the Document Names without Carrying 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