PDF/A conformance in pdfnative

PDF/A-1b, 2b, 2u and 3b via layout: { tagged: … }, validated against the veraPDF reference validator in CI. Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — console.warn by default, a custom onDiagnostic sink, or a thrown error under strict: true.

PDF/A is the ISO archival profile for PDF (ISO 19005). pdfnative supports PDF/A-1b, 2b, 2u, and 3b via the tagged build option. This guide explains what works today, what's still in flight, and how to validate your output against the official reference validator.

TL;DR#

import { buildPDFBytes } from 'pdfnative';

const pdf = buildPDFBytes(params, { tagged: true });        // PDF/A-2b (default)
const pdf1b = buildPDFBytes(params, { tagged: 'pdfa1b' });  // PDF/A-1b
const pdf2u = buildPDFBytes(params, { tagged: 'pdfa2u' });  // PDF/A-2u
const pdf3b = buildPDFBytes(params, { tagged: 'pdfa3b' });  // PDF/A-3b + attachments

tagged alone is not enough: embed a font#

ISO 19005 requires every font in the file to be embedded. tagged writes the XMP conformance declaration, the structure tree and the output intent — but it does not embed a font for you. If your document uses only the viewer's built-in fonts (which is what happens when you pass no fontEntries), pdfnative writes a file that claims PDF/A while referencing non-embedded Helvetica, and veraPDF will reject it.

Pass at least a Latin font whenever you set tagged:

import { buildDocumentPDFBytes, registerFonts, loadFontData } from 'pdfnative';

registerFonts({ latin: () => import('pdfnative/fonts/noto-sans-data.js') });
const fontData = await loadFontData('latin');

// fontRef becomes a PDF resource name, so it needs the leading slash.
// /F1 and /F2 are reserved by the engine — start at /F3.

const pdf = buildDocumentPDFBytes(
  { title: 'Archival', blocks, fontEntries: [{ fontData, fontRef: '/F3', lang: 'latin' }] },
  { tagged: 'pdfa2b' },
);

Since v1.7.0 the builders guard this declaration themselves: requesting any 'pdfa*' level (or tagged: true) with no fontEntries emits the PDFA_NO_FONT_ENTRIES diagnostic — a console.warn by default, or a thrown Error under strict: true, before any output bytes are produced. See Conformance diagnostics below.

The sample generators in scripts/generators/ all do this, which is why the veraPDF CI job passes. If you author through pdfnative-react, its lintDocument() rule L_TAGGED_NO_FONTS still catches the same trap earlier, at the document-model level — a complementary check to the core diagnostic.

Every output written with tagged set ships:

• A full structure tree (/Document → /Table → /TR → /TH|/TD, /H1–H3, /P, /L → /LI, /Figure, /Link).
• /ActualText UTF-16BE on every marked content /Span.
• An XMP metadata stream with pdfaid:part and pdfaid:conformance.
• An sRGB ICC OutputIntent (GTS_PDFA1).
• /MarkInfo << /Marked true >> on the catalog.
• A trailer /ID derived deterministically from the document title and creation timestamp.
• /Info CreationDate byte-equivalent to xmp:CreateDate, both with timezone offsets.

Conformance diagnostics (v1.7.0)#

Configurations that produce a PDF/A claim veraPDF would reject no longer fail silently. Both builders (buildPDFBytes and buildDocumentPDFBytes) surface them through a single diagnostics channel:

By default each diagnostic is a console.warn, deduplicated once per code per build. Two layout options change that:

import { buildPDFBytes, type PdfDiagnostic } from 'pdfnative';

// CI / tests: escalate to a thrown Error, before any bytes are produced.
buildPDFBytes(params, { tagged: 'pdfa2b', strict: true });

// Custom sink — receives every diagnostic (no deduplication).
// Pass () => {} to silence entirely.
const diagnostics: PdfDiagnostic[] = [];
const pdf = buildPDFBytes(params, {
  tagged: 'pdfa2b',
  onDiagnostic: (d) => diagnostics.push(d),
});

Each PdfDiagnostic carries a machine-readable code, a severity ('warning'), and an actionable message that includes the remedy. onDiagnostic is ignored when strict is set — diagnostics throw instead. The code list is a stable, additions-only union (PdfDiagnosticCode), so a sink written today keeps compiling as future codes are added.

On the MCP surface (pdfnative-mcp 1.6.0), the same honesty is exposed as three opt-in inputs on every document tool: embedFonts: true embeds Noto Sans Latin so a PDF/A claim on base-14 text is actually accepted by veraPDF, strict: true fails instead of producing a non-conformant file, and includeDiagnostics: true echoes the engine's diagnostics (PDFA_NO_FONT_ENTRIES, PDFA_UNEMBEDDED_FORM_FONT, PDFA_DEVICE_CMYK_IMAGE) in the tool result. Known engine limitation: add_form (or a formField block) under a PDF/A claim still fails veraPDF even with embedFonts — the AcroForm /DR /Helv font is an unembedded Type1 (ISO 19005-2 §6.2.11.4.1).

v1.1.0 status — fully validated#

v1.1.0 ships full PDF/A-1b / 2b / 2u / 3b conformance against the official veraPDF reference validator. The validator runs as a blocking check on every PR (see .github/workflows/verapdf.yml).

To produce a strictly veraPDF-compliant PDF/A document, register the Latin font module and resolve it. Registering alone is not enough: the builders are synchronous and cannot await a loader, so the font never reaches the document and you get an unembedded Helvetica reference — verified: 0 embedded fonts.

import { registerFonts, loadFontData, buildPDFBytes } from 'pdfnative';

registerFonts({ latin: () => import('pdfnative/fonts/noto-sans-data.js') });
const fontData = await loadFontData('latin');

const pdf = buildPDFBytes(
  { ...params, fontEntries: [{ fontData, fontRef: '/F3', lang: 'latin' }] },
  { tagged: true },
);

Without the 'latin' font registered, pdfnative falls back to the unembedded Helvetica standard-14 references for byte-stable v1.0.x output — convenient for non-archival rendering but invalid under PDF/A.

Validating your output#

pdfnative ships a thin wrapper around the official veraPDF CLI:

# 1. Generate the sample suite (writes test-output/)
npm run test:generate

# 2. Run veraPDF against every PDF/A-claiming sample
npm run validate:pdfa

The script auto-detects veraPDF on $PATH or via the VERAPDF_HOME env var. If veraPDF is not installed it exits 0 with install instructions — local development never blocks. CI installs veraPDF deterministically (pinned to 1.30.2) and runs the same script on every engine PR — see .github/workflows/verapdf.yml — and again as a blocking gate before every npm publish.

Detection is automatic and guarded: every sample declaring pdfaid:part — currently the 18 PDF/A-claiming samples — is validated without any registration, and a coverage canary fails the run if the detected count drifts from declared.pdfaSamples in docs/assets/ecosystem.json (bump it when adding or removing a claiming sample; a mismatch with no sample change means detection or generation regressed).

Which samples are subject to PDF/A validation? Only files that declare a conformance level in their XMP (pdfaid:part) — the ones built with tagged: 'pdfa…', e.g. the pdfa/ and pdfa-latin/ sample categories. The script skips everything else. Most showcase samples (bidi/, alphabet/, charts/, …) intentionally make no PDF/A claim: they have no XMP packet at all, so force-validating one against a PDF/A profile in the veraPDF GUI fails by construction (missing /Metadata, uncalibrated DeviceRGB, …) — that is expected and not a defect.

veraPDF is invoked as an external Java tool. pdfnative remains a zero-runtime-dependency library; veraPDF is never bundled, linked, or required by consumers of the npm package.

Installing veraPDF locally#

veraPDF is a Java application. Pick whichever path matches your OS. After install, either expose verapdf on $PATH or set the VERAPDF_HOME environment variable to the install directory.

macOS — Homebrew cask:

brew install --cask verapdf
verapdf --version

Linux — official installer (headless):

curl -fsSL -o verapdf-installer.zip https://software.verapdf.org/rel/verapdf-installer.zip
unzip verapdf-installer.zip
java -jar verapdf-izpack-installer-*.jar -console
# follow the prompts; defaults are sane
export VERAPDF_HOME="$HOME/verapdf"
export PATH="$VERAPDF_HOME:$PATH"

Windows — official GUI installer from https://docs.verapdf.org/install/, or the same headless install CI uses (download the pinned zip, run java -jar verapdf-izpack-installer-*.jar auto-install.xml — the descriptor is shown in CONTRIBUTING). After install, either add the install directory to PATH or:

$env:VERAPDF_HOME = "C:\Program Files\verapdf"
$env:Path += ";$env:VERAPDF_HOME"
verapdf.bat --version

The .bat launcher is fully supported by npm run validate:pdfa since v1.7.0 (it is spawned through a shell, as recent Node versions require for batch files).

No install at all? Drop the file into the official online demo at https://demo.verapdf.org. It validates against the same engine, which is convenient for ad-hoc checks but does not scale to a CI suite.

Troubleshooting#

"My PDF fails veraPDF for missing XMP / DeviceRGB / unembedded font, but I never asked for PDF/A."

If the file was generated without tagged: true, it is a plain ISO 32000-1 document and should not be validated against any PDF/A profile. The veraPDF online demo lets you pick a profile manually, which will then surface failures by design — every PDF/A rule about metadata, output intents, font embedding, transparency, and color spaces will fire because the file never claimed any of those things.

The npm run validate:pdfa wrapper avoids this trap: it scans each PDF for a pdfaid:part declaration in the XMP packet and skips files that don't claim PDF/A. The summary line reports how many were skipped:

Scanned 242 PDF(s); 18 claim PDF/A, 224 skipped (not PDF/A).

If you want a file to be validated, generate it with tagged: true (or any 'pdfa*' value).

"My tagged file still fails rule 6.3.4 (font embedding)."

Register the Latin font module and pass the resolved data as fontEntries (see the TL;DR above). Registration on its own does nothing for the synchronous builders. Without it, pdfnative emits Helvetica as an unembedded standard-14 reference for byte-stable v1.0.x output. With it, every glyph used in the document is embedded as CIDFontType2 / FontFile2 — see the v1.1.0 status table above. Since v1.7.0 this configuration also emits the PDFA_NO_FONT_ENTRIES diagnostic at build time (a thrown error under strict: true), so the failure surfaces before veraPDF ever runs.

Output bytes change in v1.0.4#

v1.0.4 has no public API break, but PDF outputs differ byte-for-byte from v1.0.3:

• Trailer /ID array is now always present.
• /Info CreationDate and xmp:CreateDate carry timezone offsets.
• dc:creator is emitted only when an author is provided.

If your test fixtures snapshot full PDF bytes, regenerate them.

PDF/A vs encryption#

ISO 19005-1 §6.3.2 forbids combining PDF/A with PDF encryption. pdfnative validates this at the build boundary — passing both tagged: … and encryption: … in the same call throws.

Choosing a flavour#

All four flavours share the same XMP / OutputIntent / structure-tree infrastructure — pdfnative only varies the PDF version, the pdfaid:part, and the pdfaid:conformance value.

Canonical list for tooling#

The four legal tagged strings are also exposed as a typed constant for tooling that needs to populate a JSON-schema enum: (pdfnative-mcp does this for its MCP tool descriptions so Gemini-CLI and other agents can autocomplete the right value):

import { PDF_A_CONFORMANCE_TARGETS, type PdfAConformanceTarget } from 'pdfnative';

PDF_A_CONFORMANCE_TARGETS;
// → readonly ['pdfa1b', 'pdfa2b', 'pdfa2u', 'pdfa3b']

function isValidTarget(s: string): s is PdfAConformanceTarget {
  return (PDF_A_CONFORMANCE_TARGETS as readonly string[]).includes(s);
}

The constant is the single source of truth — adding a new target in a future minor release will surface automatically in every downstream consumer that imports it.

Hard invariants for contributors#

These rules are documented in the contributor instruction file .github/instructions/pdfa-conformance.instructions.md:

• /Info CreationDate and xmp:CreateDate come from the same buildPdfMetadata() call. Never inline new Date() in the builders.
• The unencrypted trailer /ID is derived deterministically from MD5(title + creationDate + objectCount). Never randomize — it breaks buildPDFBytes(params) byte-equality tests.
• dc:creator is emitted only when an author is provided and is XML-escaped.
• XMP metadata streams are never compressed.
• Compression always happens before encryption (ISO 32000-1 §7.3.8).

See also#

• CHANGELOG.md — full v1.0.4 release notes.
• veraPDF — the official reference validator.
• ISO 19005-1 / ISO 19005-2 / ISO 19005-3.