BASALT · JOURNAL
How to tell if a PDF is fillable, and which kind of form it is
To tell if a PDF is fillable, open it in Preview and click a blank box on the page. If a text cursor appears and you can type, the file almost certainly has real form fields. If nothing happens, it's either a flat page that only looks like a form, or an XFA form that Preview can't use. One Terminal command, below, settles which.
Those are three different files, and they need three different approaches. A fillable PDF is almost always an AcroForm, the standard kind. XFA is a separate XML-based kind, added in PDF 1.5 and deprecated in PDF 2.0, and in its dynamic form Preview shows only a placeholder page. A flat page has no fields at all, only drawings of boxes, so there's nothing to fill until you add text on top.
Case one: an AcroForm with real fields
An AcroForm is the usual fillable PDF. The catalog has an /AcroForm entry listing the form's fields, and each field appears on the page as a widget annotation, a rectangle laid over the box you see, where the reader draws the field. Each field has a type: text, checkbox, radio button, choice list, push button or signature.
Where the answers live matters. A value you type is stored in the field's /V entry, and the widget usually gets its own small drawing of it, called an appearance stream. Neither is part of the page's content, which still describes the blank form.
Apple's Preview guide puts filling in simply: "Click a field in the form, then type your text." That's the test, and it works without any tools.
Case two: an XFA form
An XFA form is a different design. The form is described by XML stored in an /XFA entry of the AcroForm dictionary, and in the dynamic variety the pages aren't in the file at all. The catalog says /NeedsRendering true, which means the reader must build the pages from the XML when it opens the file.
A reader that doesn't support XFA has nothing to draw, so it shows a placeholder page. The text starts "Please wait... If this message is not eventually replaced by the proper contents of the document, your PDF viewer may not be able to display this type of document." Preview shows the placeholder page, so a form that looks empty except for that message is almost certainly XFA. The "Please wait" message explains it in full, including what your options are.
Some XFA files are the static kind: the pages exist, and the XFA data rides along with them. Those can open like ordinary forms in a reader that ignores the XFA part. A static XFA form can hold two copies of an answer, one in the XML and one in the page's field, and a reader that only sees one of them can show you something the other doesn't.
Case three: a flat page that only looks like a form
Plenty of PDFs are forms in appearance only. The boxes and lines are part of the page drawing, or the page is a scan. There's no field under the box, so clicking it gives you nothing to type into.
Apple's guide covers it: "If a PDF won't allow you to type directly into the form, you can add a text box instead." In Preview, turn on the form filling toolbar with Show Form Filling Toolbar, then use the Text Box tool to place text where it belongs. That text is markup laid on the page, not a form field. Filling in PDF forms on a Mac walks through it.
How to check without clicking
The clicking test shows what Preview does, not what the file is. For a definite answer, qpdf (brew install qpdf) reads the structure without changing the file:
qpdf --json --json-key=acroform document.pdfRead the end of the output first. "hasacroform": true means the file has an AcroForm dictionary, and false with an empty "fields" list means it has none, so it's flat. Each field lists its "fieldtype" (/Tx is text, and /Btn covers checkboxes, radio buttons and push buttons, with "ischeckbox" and "isradiobutton" saying which), its "fullname" and its "value". qpdf prints text strings with a u: prefix.
That output is also how you see what a form is holding. This trimmed version lists only names and values:
qpdf --json --json-key=acroform document.pdf | grep -E '"(fullname|value)"'Be careful here: hasacroform is true for XFA files as well, because an XFA form still sits inside an AcroForm dictionary. To separate the two, make an expanded copy and look for the XFA keys:
qpdf --qdf --object-streams=disable document.pdf expanded.pdf
grep -a -E '/XFA|/NeedsRendering' expanded.pdfNo output means no XFA. If /XFA and /NeedsRendering true both appear, you have a dynamic XFA form. On a sample XFA file the grep found both, and on a plain AcroForm file it found neither.
Values live apart from the page
This is the privacy point. Filled-in answers are stored in the fields, not baked into the page, so they can remain in the file even when the page looks blank or when you only meant to share how the form looked. On macOS 15, a form with a name typed into a text field and saved through PDFKit showed the name in the qpdf output, and PDFKit had drawn it into the field's appearance. Spotlight's extracted text (mdimport -t -d3 document.pdf) still held only the page's own words. A check that reads only page text won't show you the answers.
Before sending a filled form, read the values with the grep above, and decide whether you want them to travel with it. Making the answers part of the page is what flattening a PDF on a Mac does, and how flattening differs from redaction matters if the point is to hide something. A form that won't save is a related, common headache.
Frequently asked questions
How do I know if a PDF is fillable?
Open it in Preview and click a box. If a cursor appears and you can type, it's fillable. If not, run qpdf --json --json-key=acroform on it and look at hasacroform and the list of fields. A true value with fields means a real AcroForm. A false value means the page is flat.
How do I check if a PDF form is fillable on a Mac?
Click a field in Preview and type. For a firm answer, Terminal with qpdf is better: its acroform report lists each field's type, name and value. Remember that XFA files also report an AcroForm, so look for /XFA as well before deciding the form will work in Preview.
What is an AcroForm?
An AcroForm is the standard PDF form: a dictionary in the catalog that lists fields, each tied to a widget annotation drawn over a box on the page. The field's value is stored in its own entry, not in the page content. Most fillable PDFs you'll meet are AcroForms.
What's the difference between AcroForm and XFA?
AcroForm keeps fields in the PDF's own structure. XFA keeps the form in an XML description, and dynamic XFA files build their pages from it when opened. PDF 2.0 deprecates XFA. A reader without XFA support shows a placeholder page instead of a dynamic XFA form.
Why can't I type in my PDF?
Either it has no fields, so it's flat and you can add text boxes, or it's an XFA form that your reader doesn't support, or its fields are marked read-only. The acroform report shows no fields for a flat file, and the /XFA grep on an expanded copy picks out an XFA form.
Can I make a flat PDF fillable?
Not by typing over it. Apple's suggested workaround in Preview is to place text boxes over the blanks, which lets you fill it in but doesn't create real fields. Adding true fields takes a form editor, so the quicker route is often to ask the sender for the fillable version.
Are my answers stored in a fillable PDF?
Yes. Each answer is saved in its field's value, separate from the page's drawing. That's why a form can look blank while still holding data, and why you should read the values before sharing the file.
Doing it in Basalt
Basalt helps with the first two cases. Its Inspect tool tells you whether a PDF has form fields, and says so plainly when the file is an XFA form. The Forms tool fills in fields laid over the page, and its Lock answers option, on by default, draws the answers into the page; turn it off to save a copy you can keep filling in. For an XFA form, XFA to PDF draws the answers into the page and removes the XFA data, or for a dynamic one runs the form's own scripts in a sealed engine and draws the result as an ordinary PDF. That result is a rendition, so a digital signature isn't carried over. Basalt can't fill in an XFA form itself. Every tool writes a new file, and the original is untouched. It's $29 once for up to three Macs, free for 24 hours.
Redaction that proves itself
Basalt destroys the content you mark, then re-opens the file it wrote and proves the content is gone before it saves anything. Your documents never leave your Mac.
