Conformance

Every PDF is archival by default: it is written to PDF/A, the ISO standard for long-term archiving, without asking. A document can claim another PDF/A part, add an accessibility claim (PDF/UA), or name the Office Open XML class its DOCX conforms to.

A claim is written into the file only when the file meets it. When it cannot be met, the claim is left out and the render says why: a document is never labelled with a standard it does not satisfy.

Declaring a claim

Claims live in metadata.conformance, one list per output format:

{
  "document": {
    "metadata": {
      "title": "Annual Report 2026",
      "lang": "en-CA",
      "conformance": { "pdf": ["a-2u", "ua-1"], "docx": ["strict"] }
    },
    "content": [
      { "h1": "Annual Report 2026" },
      { "p": "Report content goes here." }
    ]
  }
}

The list is a set of overrides, not a complete list. A family it does not mention keeps its default, so ["ua-2"] still produces an archival file. Order does not matter, and each standard can be claimed at one level only: two PDF/A parts, or two PDF/UA parts, are refused as a contradiction.

PDF/A: archival

Value	Standard	Use it for
a-2b	PDF/A-2b	The default. The page looks the same in any reader, years from now
a-2u	PDF/A-2u	2b, plus every character copies and searches as the one drawn. Costs nothing extra here
a-2a	PDF/A-2a	2u, plus the document is tagged with its logical structure
a-3b, a-3u, a-3a	PDF/A-3	The same three levels, for a document that embeds files (e-invoices with their XML, for example)
a-4	PDF/A-4	Archival over PDF 2.0
a-none	none	Waives the archival default

Without a PDF/A value, a document is claimed as a-2b. Three cases move the default on their own:

• a document with attachments is claimed as PDF/A-3b, since part 2 does not allow embedded files and part 3 exists for them;
• a document written as PDF 2.0 (by pdfVersion, or by a claim defined over 2.0 such as ua-2) is claimed as PDF/A-4;
• an encrypted document is not archival.

Encrypted PDFs are not archival

PDF/A forbids encryption, and the encryption is what you asked for, so the default gives way to it. An encrypted PDF is delivered without its PDF/A claim, and the render notes it. A definition that claims a PDF/A part and also sets encryption is refused: choose one. To keep a document both archival and confidential, leave the PDF unencrypted and protect it where it is stored and sent.

a-none turns archival off explicitly, for any other document that must not be archival:

"metadata": { "conformance": { "pdf": ["a-none"] } }

An empty list, like an absent conformance block, changes nothing.

What PDF/A asks of you

Almost everything PDF/A requires is the renderer's job: embedded and subset fonts, colour profiles, metadata, and none of the features the standard bans. Three things depend on the document:

The document must	Because
not be encrypted, when it claims PDF/A	PDF/A forbids encryption: an encrypted document is simply not archival
use fonts whose licence allows embedding, when it supplies its own	PDF/A embeds every font used
only contain characters some available font can draw	an empty box in place of a character is not archival content

PDF/UA: accessibility

Value	Standard	Written as
ua-1	PDF/UA-1 (ISO 14289-1)	PDF 1.7, beside a-2* or a-3*
ua-2	PDF/UA-2 (ISO 14289-2)	PDF 2.0, beside a-4
wtpdf-accessibility, wtpdf-reuse	Well-Tagged PDF 1.0	PDF 2.0. Each implies ua-2, and both can be claimed together

An accessibility claim tags the document for screen readers and other assistive technology. Tagging is built only when a document claims it, since a structure tree is a large share of a tagged file's size.

Most of the structure comes from what you already wrote: headings become heading tags, tables become table tags with their header scopes, lists become list tags, a table of contents becomes navigable, and running headers, footers and watermarks are marked as page furniture a reader skips. Links, form fields, formulas and barcodes get their descriptions from their own content.

What PDF/UA asks of you

Some facts only the author holds. Under an accessibility claim, the schema requires them, so an editor flags a missing one while you write, and the API refuses a definition that lacks one:

Key	Why
metadata.title	a reader announces the title, not the file name
metadata.lang, a tag such as "en" or "fr-CA"	a screen reader pronounces the text in this language
alt on every image, or on its definition in document.images	a listener is told what the picture shows
title or desc on every svg	the same, for drawings

And some the schema cannot check:

• under ua-1, headings start at h1 and never skip a level on the way down;
• header cells are th, so a reader can say which column or row a value belongs to;
• content order is reading order: write the document in the order it should be read;
• meaning is never carried by colour or position alone, and alt text and link text say something ("figure 1" describes nothing).

A form field with no label is announced by its name: write a label for words a person would say.

Claims and PDF versions

PDF/A parts 2 and 3 and PDF/UA-1 are defined over PDF 1.7. PDF/A-4, PDF/UA-2 and Well-Tagged PDF are defined over PDF 2.0. Claims from the two sides cannot be combined:

Claim	Output	Can stand beside
default, a-2*, a-3*	PDF 1.7	ua-1
a-4	PDF 2.0	ua-2, wtpdf-*
ua-1	PDF 1.7	a-2*, a-3*
ua-2, wtpdf-*	PDF 2.0	a-4 (also what the default becomes)

metadata.pdfVersion pins the output to "1.7" or "2.0". Without it, the version follows the claims. A pin is never overridden: a claim it contradicts, such as ua-1 with "2.0", is refused before anything is rendered.

DOCX: Office Open XML class

Value	Class
strict	ISO/IEC 29500 Strict
transitional	ISO/IEC 29500 Transitional

A package conforms to one class, so the two cannot be claimed together. A claimed class is produced as claimed: what Strict cannot carry is left out and reported, never written in the other class.

When a claim cannot be made

• Refused before rendering. A contradiction the definition shows on its own (two parts of one standard, a-2b beside ua-2, a claim against the pdfVersion pin), or a key an accessibility claim requires, is a validation error: nothing is rendered or billed, and the message names the key.
• Withheld at render. When the finished file would not meet a claim, whether you asked for it or it is the archival default, the document is still delivered and counted, without that claim. The response's errorCodes carries CONFORMANCE_WITHHELD, so check it before handing the document on. The reason and the clause are in the render's diagnostics: turn on diagnostics while authoring to see them in the document's appendix.
• Not a withhold. An encrypted document that claims no PDF/A part is not archival by design: nothing you asked for is lost, so there is no code, only a note in the diagnostics.

Check errorCodes before handing a document on

A document whose claim was withheld is still delivered. If your users rely on PDF/A or PDF/UA, treat CONFORMANCE_WITHHELD in the response's errorCodes as a failure in your integration.