Skip to content

The PDF program ​

datum-pdf-program.js is the program a server runs to make, fill, sign and read PDFs. It is the same program the browser runs, so a request gives the same bytes on every host. Running the programs on your own server says how to run it inside a WebAssembly runtime and what limits to set; this page is the list of what it answers.

Calling it ​

A host calls __datum_pdf with one JSON request as text and reads one JSON reply as text. The call returns a promise: let it settle before the module exits. A host that runs the program in process imports its handlePdfRequest instead and skips the text.

Every request has an abi, the interface version the host speaks, and an op. The program answers a request of its own major version (currently 4) and refuses any other with the abi_mismatch failure. The reply is either { "ok": true, "op": "…" } with the keys of that operation, or a failure.

json
{ "ok": false, "error": { "code": "template", "message": "The template is encrypted with a password; supply an unencrypted copy of the template." } }

The failure codes and the warnings that come back in warnings are listed in the codes reference. A failure is the whole answer; a warning never stops a file being made.

Bytes travel as base64. The program reads no clock and no random source: the host says when it is and what to call the document in env, which is what makes the output repeatable. Two more globals exist: __datum_pdf_abi is the version string, and __datum_pdf_register(module) takes a plugin module's pdfRenditions and functions (a function name must be a plain identifier that no built-in or earlier module took).

The operations ​

OpWhat it does
capabilitiesNames the version and the features
documentChooses a layout from the form and the answers and makes the PDF in one step
buildChooses the layout and builds what would be drawn, without drawing it
renderDraws a document that build returned
layoutMeasures a document: the pages it would run to, with no file
fillFills a PDF with values, and draws into areas
inspectReads a PDF: its pages, fields, encryption and embedded files
signPrepares a signature over a PDF and says what to sign
completeEmbeds the signature value the host made
timestampRequestBuilds the RFC 3161 request for a timestamp authority
verifyReads every signature in a PDF

Anything else is an invalid_request failure.

capabilities ​

Request: { "abi": "4.0.0", "op": "capabilities" }. Reply: abi, features and kernelVersion. Probe the program at start and refuse one that reports another major version, a version below the floor you built against, or lacks a feature you need.

FeatureWhat it means
document, build, render, layout, fill, inspectThe operation of that name
signaturesign, complete, timestampRequest and verify, and signature on document, render and fill
taggedTagged PDFs
acroformFillable fields, in drawn documents and in templates
areas, area-fieldsAreas drawn onto a template's pages, and areas that become fillable fields
bidiRight-to-left and mixed-direction text
unknown-componentsThe unknownComponents policy
pdfaPDF/A conformance
attachments, attachment-dataUploaded files embedded, and inspect returning embedded files' bytes
attachment-typesExecutables, scripts and HTML refused as attachments, and a file whose bytes are larger than its declared size
theme-controlsA PDF theme's geometry: controls, choice marks, fields, headings, tables, boxes, panels, lists, spacing
data-keysA field's dataKey places its answer, in tables, repeats and fillable field names
layout-conditionsA layout's when chooses it from the answers
field-tooltipsinspect lists each field's tooltip
conditional-expressions, formulas, formula-functionsif in expressions, formula strings, and the function library with plugin functions
verify-detailThe full signature report: the signed revision, later updates, timestamps, knownCertificates
template-decryptionTemplates encrypted with an empty user password are read
mapping-valuesA mapping's values map from answers to PDF values
output-safetySafe attachment names, bidi controls stripped from answers, field values clamped to their maximum length, risky patterns refused
render-capsA layout's limits for pages and answer length
default-font-fallbackA family no font covers is drawn in the supplied default sans-serif face

Require at least document. Add fill and inspect for templates, signature to sign, verify-detail before you rely on a verify report, layout-conditions and formulas when layouts have conditions, pdfa for archival files, and output-safety and render-caps when answers come from the public.

document ​

The request carries the form, the answers and the host's time. Keys marked optional can be left out.

KeyMeaning
formThe form's root component
valuesThe answers, keyed by value path as a submission carries them. They are what prints and what a layout's when reads. Send the sandbox's validated values
localeThe language to draw in
pdfOptional. The definition's pdf block: layouts and defaultLayoutId
layoutIdOptional. The layout to draw. Wins over every when
layoutOptional. A layout to draw whole instead of any in pdf
fontsThe font resources: id, family, weight, style, data (base64) and coverage (script tags)
envcreatedAt (ISO 8601), documentId (hashed into the file's trailer id), and optional producer and creator
optionsOptional. compact, tagged and pdfa as the render options of PDFs
templateOptional. { "data": "…" }: the bytes of a template layout whose PDF is not inline in the definition
signatureOptional. Prepares a signature over the result: the settings of Signing over the layout's own, and certificates, base64 DER, the signer's first
translationsOptional. The host's translation catalogue. An entry here wins over the definition's
formTranslationsOptional. The definition's own translations map
kindsOptional. The definition's kinds map, so a plugin's or a design system's component type is drawn as its base type
optionSnapshotOptional. Options of data-source-backed components, per component id, already resolved. The program never fetches
effectiveStatesOptional. Visibility per component id. Left out, rules run inside the program
themeOptional. A PDF theme object. The program knows only datum-pdf and datum-plain by id
titleOptional. The document title, overriding the form's
hostContextOptional. An object read as host.<key>
unknownComponentsOptional. ignore, warn (the default) or fail
attachmentsOptional. { budgetBytes, onExceeded }. Default 4 MiB and skip
todayOptional. YYYY-MM-DD. Left out, a rule that reads the clock never holds. A server sends its own day
formulaErrorsOptional. fail (the default) or warn
riskyPatternsOptional. refuse (the default) or allow

The reply has bytes (base64), pageCount, pages (empty for a filled template), warnings, and the layout it printed: layoutId, layoutKind (generated, template or derived) and layoutChoice (given, asked, condition, default, fallback or derived). It also has fields and areas for a template, pdfa when the file declares a level, attachments (the embedded names) and, when the request asked for a signature, signing.

A template layout needs its bytes. If the layout's source is inline, the program has them. Otherwise send template. Because the answers can choose the layout, the program refuses template bytes sent without a layoutId when a condition chose a template other than the one printed when no condition holds, so it never fills the wrong PDF. Call build first to learn which layout the answers choose, resolve its bytes, then send document with that layoutId.

json
{
  "abi": "4.0.0",
  "op": "document",
  "form": { "…": "the form's root component" },
  "values": { "fullName": "Ada Lovelace", "age": 36 },
  "locale": "en",
  "pdf": { "layouts": [ { "…": "…" } ] },
  "fonts": [ { "id": "sans", "family": "sans-serif", "weight": 400, "data": "…base64…", "coverage": ["Latn"] } ],
  "env": { "createdAt": "2026-11-14T12:00:00.000Z", "documentId": "intake-1042" },
  "options": { "pdfa": "2b" }
}

build and render ​

build takes the same inputs as document (keys from form to riskyPatterns, but not fonts, env, options, template or signature). It replies with layoutId, layoutKind, layoutChoice, warnings and either document, the model of a generated layout, or fill, the plan of a template (the values and areas already worked out). Use it to learn which layout the answers choose, to cache a document, or to inspect one.

render takes the document from a build, plus fonts, env, and optional options and signature. The reply is the same as document's without the layout keys.

layout ​

Takes document, fonts. Replies with pages (each page's index, width, height and the blockIds that landed on it) and warnings, and no file. It is a cheap way to count pages.

fill ​

Fills a PDF with values you resolved yourself.

KeyMeaning
template{ "data": "…" }, the PDF in base64
valuesAcroForm field name to value: text, true or false, a list of option values, or null to clear
areasOptional. Areas with their values already resolved
fonts, envAs for document
optionsThe three fill options of Template layouts: flatten, readOnly and appearances. Send all three
conformanceOptional. The archival level to keep through the fill
attachmentsOptional. Uploaded files to embed
signatureOptional. Prepares a signature over the filled PDF
typography, colorsOptional. What a content area draws with when its own draw says nothing

Reply: bytes, pageCount, fields (one per value: pdfField, status of filled, cleared, missing or unsupported, kind, message), areas, warnings, and pdfa, attachments and signing when they apply.

inspect ​

Request: template ({ "data": "…" }) and optionally attachments: none (the default), digest or data, which lists the embedded files with their SHA-256 and, for data, their bytes. Reply: info.

info keyMeaning
pageCount, pagesThe page count, and each page's index, width and height
fieldsEach field's name, kind (text, checkbox, radio, dropdown, listbox, signature, button or unknown), page, rect, options, exportValues (what means on, for a checkbox or radio), maxLength, multiline, readOnly, required, value, signed (for a signature field) and tooltip
hasXfaThe PDF carries XFA, which a fill removes
encrypted, permissionsWhether it was encrypted. The owner's permissions: print, printHighQuality, modify, copy, annotate, fillForms, assemble
pdfaThe PDF/A level it declares
signaturesHow many signature fields are signed
attachments, warningsThe embedded files when asked for, and what could not be read

A listing is capped at 500 pages and 5,000 fields, with template.truncated. A template that needs a password to open is refused as a template failure.

sign, complete and timestampRequest ​

Signing takes two calls so that a private key never enters the program. Signing describes the flow.

sign takes pdf ({ "data": "…" }), signature (the settings and certificates), env (createdAt at least) and optionally fonts. It replies with bytes, the prepared file, signing and warnings. signing is what the host must sign.

signing keyMeaning
fieldThe signature field the signature will land in
byteRangeThe four numbers that frame the signed bytes
digestSHA-256 over the byte range, base64
toBeSignedThe signed attributes, base64: sign these bytes
toBeSignedDigestSHA-256 of toBeSigned, for a key service that takes a digest
signatureAlgorithmRSASSA-PKCS1-v1_5-SHA256, ECDSA-P256-SHA256 or ECDSA-P384-SHA256, from the signer's certificate
subFilterETSI.CAdES.detached or adbe.pkcs7.detached

timestampRequest takes signature, the signature value in base64, and replies with request, the base64 request to post to a timestamp authority with content type application/timestamp-query.

complete takes the prepared pdf and signing: the same certificates and settings that sign had, plus value (the raw signature over toBeSigned, base64; ECDSA as DER or as r followed by s), toBeSignedDigest (echoed so a changed input is caught) and optionally timestamp: { "token": "…" }, the authority's answer in base64. It replies with bytes, the signed file, field, cms (the signature container) and timestamped.

verify ​

Request: pdf, and optionally knownCertificates, a list of at most 64 base64 certificates of at most 16 KiB each, such as your timestamp authority's. More is an invalid_request. Reply: signatures, attachments (each embedded file's name, sha256, relationship and size), warnings, and documentId, the file's trailer id, which nothing authenticates by itself.

Each entry of signatures reports one signature.

KeyMeaning
field, subFilter, byteRangeWhere the signature is and how it was made
coversDocumentThe signed range reaches the end of the file: nothing was added after it
digestMatchesThe signed range hashes to the digest in the signature
certificateMatchesThe signature names the certificate that signed it
signer, signerSourceThe signing certificate (certificate, publicKey, subject, issuer, serialNumber, notBefore, notAfter) and where it was found: signature, known or none
certificatesEvery certificate the signature carries
toBeVerified, signature, signatureP1363, signatureAlgorithmWhat the host checks the signature value over, with the signer's key
signingTime, reason, location, name, contactInfoWhat the signature says about itself
certification{ permissions } of noChanges, formFilling or annotations, or null for an approval signature
commitmentThe commitment type and statement signed with the attributes
timestampA timestamp token in the signature: time, tsa, coversSignature, the imprint, and the token's own signature, signer and checks
details, signedRevision, changedAfter, signedDocumentIdWhat the signature dictionary said in the revision that was signed, and how the file's latest definition differs
laterRevisionsWhat updates after this signature added, changed or freed (revisions, changes), whether the certification permits all of it (permitted), and the later signatures that decision relied on (reliedOnSignatures)

The program checks structure, digests and certificate binding. It does not check the signature value and does not decide trust; that is the host's. Signing says what to check.

Fonts ​

document, render, layout and fill draw with the fonts in the request. A font is { id, family, weight, style, data, coverage }, where data is a TrueType or OpenType file in base64. Send what the document needs: the host works that out from the document, or sends the whole pack. With no resource for a family, the program uses a resource whose family is sans-serif in its place; with none at all it falls back to the standard PDF fonts, which have a Western repertoire only. See Fonts.

MIT licence. Your forms, your data, your keys.