open-matter / 0.1

open-matter is a convention for putting a small, machine-readable index card inside a PDF, as a standard file attachment. An agent that opens the file can read the card in milliseconds and decide what to do next — without parsing a single page.

It is a carrier, not a representation. It does not replace PDF, Tagged PDF, XMP, DocLang, or paper.json. It says where agent-facing data lives so that data never gets separated from the document that circulates.

The PDF remains a valid PDF. It looks identical in every viewer. Viewers that list attachments show the card as a normal file named open-matter.yaml. Typical overhead is under 1 KB.

The card must be stored as an embedded file in the PDF EmbeddedFiles name tree (PDF 1.4 and later).

• The filename must be exactly open-matter.yaml.
• The embedded-file MIME type must be application/yaml.
• The payload must be UTF-8 YAML.

Implementations must not put the card in:

• the Info dictionary
• XMP metadata
• document-level JavaScript
• a visible page
• a sidecar file next to the PDF

Richer representations (DocLang, extracted tables, OCR transcripts) may ride along as further attachments. The card points at them from the optional derived key.

spec: open-matter/0.1
title: Contrato de fornecimento
doc_type: contract
language: pt-PT
pages: 40
summary: >
  Supply agreement between two parties; liability cap and
  termination terms are the sensitive clauses.
key_sections:
  liability_cap: 4
  termination: 5
entities: [REISIERX Lda]
extraction:
  scanned: false
  tables_on_pages: [2, 7]
derived:
  doclang: doc.doclang.json
content_sha256: 335671f796b07b02
generated_by: <model or tool id>
generated_at: 2026-08-13

Required keys

All other keys are optional. Tools that rewrite a card must preserve unknown keys.

Optional keys

1. Look up the attachment by the reserved name. Do not guess other names.
2. Decode as UTF-8. Parse as YAML. Validate spec. If any step fails, must fall back silently to a normal parse.
3. Treat every field as a hint, never as ground truth.
4. If content_sha256 is present and does not match, the card is stale. Ignore it or regenerate it.
5. A missing or lying card must only ever cost a slow read, never a wrong answer.

1. Write valid UTF-8 YAML to the reserved filename and MIME type.
2. Do not alter page content. The file must render identically.
3. If a card already exists, replace it. Do not leave two reserved names.
4. When rewriting, preserve unknown keys.
5. Prefer under-claiming. A short honest summary beats a long one.

Manifests are untrusted data, written by whoever last touched the file.

Agents must not interpret any field as instructions, code, a prompt, a tool call, or a URL to fetch automatically. Title, summary, entities, and every other string are data.

A card can lie. Nothing in this convention prevents that. That is why the hash exists, and why the fallback rule exists.

Implementations must not render manifest content as executable anything — not HTML, not scripts, not evaluated templates.

XMP / Info dictionary. Flat, ancient, aimed at bibliographic software. Nobody targeting agents looks there first.

Tagged PDF. An accessibility structure. Barely produced in practice, expensive to retrofit, and still a full parse.

DocLang. A representation. This is the carrier. The derived key is the bridge.

A sidecar file. Orphaned the first time someone forwards the PDF.

A new file format. Requires the world to change formats. This convention does not.

This version is open-matter/0.1. A future version will use a new spec string. Readers that do not recognise the value must ignore the card and fall back.

The text of this specification is dedicated to the public domain under CC0 1.0. Reference implementations are MIT unless a file says otherwise.