What is a PDF form? AcroForm vs XFA and why some forms won't open

Every PDF has a catalogue, and an interactive form adds one entry to it: /AcroForm. That dictionary holds a /Fields array listing the form's fields, a /DR resource dictionary with the fonts the fields may use, a /DA default appearance string, and a handful of flags. A field is itself a dictionary with a partial name (/T), a type (/FT), a value (/V) and a default value (/DV). Fields can be nested, and the full name of a field is its ancestors' names joined with dots — which is why you meet names like applicant.address.city rather than plain "city".

Where a field is drawn is a separate question, answered by widget annotations. A widget is an annotation of subtype /Widget attached to a page, with a /Rect giving its rectangle in PDF user space. Usually a field owns exactly one widget, but a radio group owns one per option, and a field that repeats on every page — an initials box, for example — owns one per page. Page coordinates start at the bottom-left corner and are measured in points (1/72 inch), which is why a field near the top of an A4 page has a y value close to 842.

This split explains a common surprise: a field can exist in the form without being visible anywhere. If its rectangle is empty, or its hidden flag is set, no reader will show it, yet its value is still stored in the file and still travels with it. FormFlatten counts such fields and tells you how many it skipped rather than pretending the form is smaller than it is.

There are only four field types in the specification. /Tx is a text field; its behaviour is controlled by bit flags — multiline, password, comb (one character per cell, which requires a maximum length), file select, do-not-spell-check, do-not-scroll and rich text. /Btn covers three different controls at once: push buttons, checkboxes and radio groups, separated by the pushbutton and radio flags. /Ch is a choice field, either a dropdown (combo flag set) or a scrolling list, with the options in /Opt and a multi-select flag. /Sig is a signature field, which is normally empty until something signs it.

Checkboxes and radio buttons store their state as a name, not as true or false. Each widget declares an "on" name in its appearance dictionary — often /Yes, but it can be anything, including the option's label — and the field's value is either that name or /Off. This is why a checkbox that looks identical to another can need a completely different value, and why exporting form data gives you strings like "Choice2" instead of the words printed next to the box. A radio group's /Opt array, when present, gives readable export values in widget order.

A field can also be marked read-only or required. Read-only means the issuer filled it in and does not want it changed — a reference number, a pre-printed date, a calculated total. Required is only a hint: nothing in the PDF format stops you from saving an incomplete form, it merely makes Acrobat complain when you submit. FormFlatten shows both: read-only fields are greyed out and kept exactly as they were, required-but-empty fields get a red outline and a count in the action bar.

A field's value is data; the picture of that value is a separate object called an appearance stream, stored under /AP /N on the widget. It is a small content stream — the same drawing language as the page — that paints the text, the border and the background inside the widget's rectangle. When a reader shows you "Marta Kask" in a name field, it is usually showing you that stream, not the /V string.

The two can fall out of step. A tool that writes a value without regenerating the appearance produces a file whose data is right and whose display is blank. To cope with that, the AcroForm dictionary has a /NeedAppearances flag: when it is true, a reader is asked to build appearances itself from the value and the /DA string. Acrobat and most desktop readers honour it; some mobile viewers and printing pipelines do not, which is the classic reason a form that looked filled on your laptop prints empty at the other end.

The /DA string is worth reading when a form misbehaves. It looks like "/Helv 0 Tf 0 g": a font name that must exist in the form's /DR resources, a size and the text colour. A size of 0 means auto — the reader shrinks the text to fit the box. Because /Helv is Helvetica with WinAnsi encoding, a field with that default appearance physically cannot display Cyrillic, Greek or most accented Eastern European characters until someone embeds a font that has them.

In the early 2000s Adobe introduced XFA (XML Forms Architecture) with LiveCycle Designer. An XFA form keeps its real definition — layout, fields, validation rules, scripts — in an XML payload referenced from /AcroForm /XFA. Two flavours exist: static XFA, which also ships a normal AcroForm rendering as a fallback, and dynamic XFA, which does not and whose pages are generated at open time, so the file can grow rows as you type.

Dynamic XFA is what produces the grey or purple page saying "Please wait… if this message is not eventually replaced, please upgrade to the latest version of Adobe Reader." Browsers, macOS Preview, mobile readers and every open-source library show that page because none of them implement XFA. The format was never adopted outside Adobe's ecosystem: ISO 32000-2 (PDF 2.0, published 2017) deprecated it, and Adobe itself has been steering issuers towards plain AcroForms for years.

If you receive one, the practical options are: open it in Adobe Acrobat Reader on a desktop, ask the issuer for an AcroForm or a paper version, or print it and fill it by hand. FormFlatten detects the /XFA entry and says so; when the file is static XFA it will still show and fill the AcroForm layer, which is often enough to get a usable printed result.

Some forms carry "usage rights" added by Adobe LiveCycle Reader Extensions — a signature over the document that used to let free Reader save filled copies. Modern Reader can save any form, so the rights mostly cause a warning that saving will invalidate them. Other forms contain document-level JavaScript for calculations, date formatting or field validation. That code only runs in Acrobat; in any other tool the fields simply hold whatever you type, so double-check totals a form would normally compute for you.

Three more things stop a form from opening anywhere. Password protection (an encrypted file) needs the password before any structure can be read. A certified signature locks the document against changes, so filling it in a third-party tool would break the certificate. And a damaged cross-reference table — usually from an interrupted download or an email gateway that rewrote the file — makes the whole PDF unparseable; re-downloading from the original source fixes it far more often than any repair tool.