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.

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 drops the /Info dictionary and keeps the packet alone, which ISO 32000-2 allows and nothing below PDF 2.0 does.

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 instance 2026-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 made.
  • 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 saying no.
  • 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[].value, properties[].description — strings, all required; an empty description is refused.
  • properties[].value_type — string, optional, text by default. Nine values: boolean, date, integer, mime_type, proper_name, real, text, uri, url.
  • properties[].category — string, optional, internal by default. Two values: internal, external.

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"
          }
        ]
      }
    ],
    "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 line that sends it, in three languages

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 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 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 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 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

See the prices See the examples