Signatures, encryption and attachments / AcroForm fields
AcroForm fields and HTML form inputs in a PDF
Interactive form fields inside a PDF, and why an HTML input rendered to PDF is a picture of a field rather than a field.
Where this API stands
This API does not produce this standard, and there is no option that would. What follows is what the requirement actually is and where a rendered document stands against it. This API creates no /AcroForm and no form fields, and this is the one case in this cluster where the outcome actively surprises people, so it is worth stating flatly. An `<input>`, `<select>` or `<textarea>` in your markup is laid out and drawn like any other element: you get the box, the border and any value that was already in it, as ink on the page. There is no field to click, nothing to type into, and no name or value that a form processor could read back. A checkbox drawn by a browser becomes a small square, permanently in whatever state it was rendered in.
What the standard requires
The requirements as a checker enforces them, rather than as a procurement document paraphrases them. A file satisfies all of these or it satisfies none of them.
- An /AcroForm dictionary in the catalogue with a /Fields array holding the field dictionaries.
- Each field has a /FT giving its type (/Tx for text, /Btn for buttons and checkboxes, /Ch for choices, /Sig for signatures), a /T name, and a widget annotation placing it on a page.
- /DA and /DR supply the default appearance and the resources it references, which is what the field's text is drawn with when a value is typed.
- /NeedAppearances true tells a reader to generate the appearance streams itself, which is the usual fix for a filled field that renders blank.
- PDF/UA requires every field to have a /TU tooltip, because that is what a screen reader announces in place of a visual label.
Who asks for this
Anyone issuing a form to be filled in rather than printed and written on: an application form, a claim, a consent. It also comes up as a surprise, when somebody renders an HTML form to PDF and expects the result to be fillable.
What it looks like in a file
The concrete form of the thing being described, so you can recognise it in a document you have been handed rather than only in a specification.
<!-- Rendered to PDF, this is ink. The box is drawn, the border is
drawn, the placeholder is not, and nothing is fillable. -->
<input type="text" name="claim_ref" value="">
<!-- If the form is to be completed by hand, say so in the markup and
give people room to write. 9mm is about right for an adult hand. -->
<div class="write-in">
<label>Claim reference</label>
<div class="rule"></div>
</div>
<style>
.write-in .rule {
height: 9mm;
border-bottom: 0.4pt solid #333;
}
.write-in label {
font-size: 8pt;
letter-spacing: 0.06em;
text-transform: uppercase;
}
</style>What to do about it
Decide which kind of document you are making. If it is a form to be filled in on a computer, build the AcroForm downstream with pdf-lib, pyHanko or a commercial tool, using the render only as the visual background. If it is a form to be printed and completed by hand, which is more often what is actually wanted, style the fields as ruled lines and boxes with enough height to write in, and drop the input elements entirely. The worst outcome is the middle: an HTML form rendered as-is, which is too cramped to write in and not fillable either.
How to check a file rather than assume
`mutool show file.pdf trailer/Root/AcroForm` shows the form dictionary if there is one. `pdftk file.pdf dump_data_fields` lists the fields and their types in readable form. Opening the file in a reader and trying to type in it answers the question in two seconds and is the check most people should run first.
The mistake people make here
Sending a print-styled form to someone who needs to complete it on screen. They will fill it in by adding annotations, or print it, complete it by hand, and scan it back, and you receive an image where you expected data. If the completed form has to be machine-read, the fields have to be real, and that decision belongs at the start of the build rather than after the first submission comes back as a photograph.
Frequently asked
Does this API produce AcroForm fields?
Not produced by this API. This API creates no /AcroForm and no form fields, and this is the one case in this cluster where the outcome actively surprises people, so it is worth stating flatly. An `<input>`, `<select>` or `<textarea>` in your markup is laid out and drawn like any other element: you get the box, the border and any value that was already in it, as ink on the page. There is no field to click, nothing to type into, and no name or value that a form processor could read back. A checkbox drawn by a browser becomes a small square, permanently in whatever state it was rendered in.
Can I turn on the pdf_a option and be done?
No. The option writes an XMP packet declaring PDF/A-1b into the document catalogue, and the render response comes back carrying a warning that says in as many words that this is best-effort and that full conformance requires tagged structure and an embedded ICC profile. It is a claim written into the file, not a certificate earned by it, and a validator checks the claim against the bytes. Read the warning array in the response rather than taking the absence of an error as a pass.
Should I convert before rendering or after?
After, always. A conformance converter rewrites colour, embeds profiles, sets boxes and stamps metadata on a finished PDF. Trying to satisfy a conformance target from the source side means guessing at what the converter would have done, and the guesses that go wrong are expensive: flattening transparency you did not need to flatten changes what the page looks like.
Standards this one is confused with
The neighbours that matter are the ones people mistake for this, not the ones that sort next to it.
Adding a digital signature field to a PDF
A form field holding a cryptographic signature over the file, which proves who signed it and that nothing has changed since.
Certification signatures and DocMDP permissions
The first signature on a document, which certifies the whole thing and declares what, if anything, anyone is allowed to change afterwards.
PDF/UA-1 compliance for a generated PDF
ISO 14289-1: the standard that says a PDF is usable by assistive technology, which in practice means it carries a complete and correct structure tree.
PAdES signature levels B-B, B-T, B-LT and B-LTA
The four European profiles for PDF signatures, each adding what the one below it needs to still be verifiable years later.
Password protection and PDF/A conformance
Why a password-protected file can never be PDF/A or PDF/UA, and what the password option here actually gives you.
Every standard, with what this API does about it
The full list, grouped by what the requirement is for, each marked with how far this API gets.
What this API actually does
One page per option and endpoint that exists, with nothing that does not.
Conformance is decided after a file exists. Render the document, then check it, then convert only what the checker actually flags.