Select a conformance mode over Connect

Select a conformance mode over Connect

Boundary. Setting a conformance mode wires the catalog and metadata required by the corresponding standard. It makes the engine produce output intended to conform to that standard. It does not make the document “conformant”. A validator, such as veraPDF, decides conformance. Read every “conformance” statement on this page as “intended to conform; the validator determines the outcome”.

At a glance

A document carries exactly one conformance discriminator: plain, a tagged/PDF-UA mode, or a PDF/A mode. That discriminator tells the writer which catalog, structure, and metadata wiring to emit. Use this recipe to set the discriminator over the Connect transports. The tagged-mode setter is core. The PDF/A-4 mode setter is permanently Premium-tier (ADR-011) and registers only when nextpdf/premium is installed alongside the server.

If you call both setters, both feature stacks are layered. The single-valued discriminator still collapses to last-wins, and the engine emits a clobber warning so tooling can observe the overwrite.

Install

composer require nextpdf/server

Confirm that the PDF/A mode setter is present with a tools/list call. See /connect/tool-catalog/.

Conceptual overview

The conformance marker declares intended conformance. A validator determines actual conformance (PDF/A-4 §6.7.3). Conformance is determined against the standard’s requirements, not asserted by the producing software (PDF/A-4 §6.7.3). The tagged mode wires the structure tree and mark-info catalog entries (ISO 32000-2 §14.7).

A mode flip is a wiring operation. It prepares the document for a check against the standard. It is not itself a conformance result.

API surface

Tool names are verified against the running registry via tools/list. The catalog of record is /connect/tool-catalog/. This recipe does not repeat a tool count. Select the discriminator before the first content call. The writer freezes the mode at first page emission.

Code sample — Quick start

Create a document, then flip it to the tagged/PDF-UA mode:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

The response reports the active mode predicates (tagged / accessibility / archival) that the writer checks at every emission site. It also reports the catalog wiring it added. The predicates show what the writer will emit; they do not assert that the result conforms.

Code sample — Production

Flip to PDF/A-4 (Premium-tier), then run the check. Treat a non-success status as a normal result to inspect:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "enable_pdf_a",
    "arguments": { "document_id": "<id>", "version": "PdfA4" }
  }
}

If you call both setters, the discriminator collapses last-wins and the engine emits a clobber warning. Run the standards check for each flavour whose feature stack remains wired, because the wiring is additive even though the single discriminator is not.

Edge cases & gotchas

• Mode set after first page is rejected with a frozen-mode error. Set the mode immediately after creating the document.
• PDF/A setter without Premium fails — it is permanently Premium-tier (ADR-011). A plain PDF 2.0 document needs no PDF/A mode.
• Unknown enum case is rejected. The supported archival case is PDF/A-4 (legacy PDF/A profiles were retired).
• Operation forbidden by archival mode (for example embedded JavaScript) is rejected while the archival predicate is active.
• Flavour/mode mismatch on the check returns a non-conformant marker finding. Pass the flavour matching the active mode, or both when both stacks are wired.

Performance

The frontmatter budget is a documentation cap. Mode wiring adds no measurable separate phase.

Security notes

Not applicable beyond the general Connect transport guidance.

Conformance

Claim	Clause	reference_id
The conformance marker declares intended conformance; a validator decides	PDF/A-4 §6.7.3
Conformance determined against requirements, not asserted by the producer	PDF/A-4 §6.7.3
Tagged mode wires the structure tree and mark-info entries	ISO 32000-2 §14.7

Selecting a conformance mode makes the engine produce output intended to conform. It is not a conformance certification. A validator determines the outcome.

Commercial context

The PDF/A-4 mode setter is permanently Premium-tier (ADR-011) and registers only when nextpdf/premium is installed alongside the server. The tagged-mode setter is a core capability.

Connect specifics

Transport availability (MCP / REST / gRPC)

The mode setters and the check are invoked identically over MCP tools/call, the REST tool endpoint, and the gRPC service through the shared tool executor.

HITL risk tier

Mode setters are caution-level. The check is read-only. None is approval_required by default. An operator override may only raise risk. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

These tools do not trigger the gate unless an operator override raises one to approval_required. The envelope and single-use token contract is in /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/compliance-check/ — validate against the active standard.
• /cookbook/connect/tagged-pdf-tutorial/ — end-to-end tagged-PDF walkthrough.
• /connect/tool-catalog/ — per-tier tool set computation.
• /connect/hitl-risk-tiers/ — the risk model and the gate.