pdfform
Derive a JSON Schema from a PDF form, then fill the form from JSON. Usable as a command line tool or as a library.
There is no single library that reads an AcroForm, describes it as a schema, and writes values back correctly. pypdf and pikepdf give you the raw dictionaries, pdf-lib gives you a typed field API in JavaScript, and the mapping to JSON Schema is left to you, along with the handful of details that decide whether a filled form actually shows anything in a viewer. pdfform is that missing layer.
Features
- Schema extraction. One JSON Schema property per fillable field, with types, enums,
maxLength, defaults and descriptions. - Filling from a JSON file, from
--set NAME=VALUE, or from a Python dict. - Correct button handling. Check box on-states are read per widget, not assumed to be
Yes, and both/Vand/ASare written. - Flattening that bakes the appearance streams into the page content using the placement algorithm from the PDF spec, rather than only translating them.
- XFA awareness. Static and dynamic XFA are told apart, static XFA layers can be dropped (the
pdftk drop_xfaequivalent), and dynamic XFA fails loudly instead of producing an empty schema. - Label inference. Optional best-effort guessing of what a field called
Text12actually means, from the text printed next to it.
Installation
Requires Python >= 3.12.
pip install pdfform
From a checkout, uv sync --all-groups sets everything up; see CONTRIBUTING.md.
Command line
# What is in this form?
pdfform fields form.pdf
# Derive a JSON Schema
pdfform schema form.pdf -o schema.json
# Dump the current values as a starting point, edit, then write them back
pdfform values form.pdf --include-empty -o data.json
pdfform fill form.pdf -d data.json -o filled.pdf
# Or set a few fields directly
pdfform fill form.pdf --set Name=Doe --set Agreed=true --set Colour=Blue -o filled.pdf
# Produce a non-editable document
pdfform fill form.pdf -d data.json -o filled.pdf --flatten
pdfform fields prints one line per field with its kind, page, options, current value and description:
FIELD KIND PG DETAIL
Haushaltsjahr text 1 max 4 “Haushaltsjahr”
Grund_Probandenentgelt checkbox 1 on=Ja [Ja] “Probandenentgelt”
Mitarbeiter_des_Klinikums radio 1 [Nein, Ja] “Ist der Zahlungsempfänger Mitarbeiter des Klinikums?”
Antragsteller_Unterschrift signature 2 “Unterschrift des Antragstellers”
Data can be checked against the derived schema before anything is written:
pdfform validate form.pdf -d data.json
pdfform fill form.pdf -d data.json -o filled.pdf --validate # refuses to write on a mismatch
Other commands: pdfform strip-xfa removes an XFA layer, pdfform xfa lists or dumps the XFA packets. pdfform --help covers the rest.
Library
from pdfform import extract_form, build_schema, fill_form
info = extract_form("form.pdf")
schema = build_schema(info) # a JSON Schema document
fill_form("form.pdf", {"Name": "Doe", "Agreed": True}, "filled.pdf")
fill_form returns the resulting bytes, so the output argument is optional and fills can be chained. Values may be nested ({"Address": {"Street": ...}}) or flat with dot-separated keys ({"Address.Street": ...}).
Working with the field inventory directly:
for field in info.fillable:
print(field.name, field.kind, field.on_states, field.describe())
extract_form never raises on a document that simply has no form; it returns an empty FormInfo. Errors that do get raised (DynamicXfaError, UnknownFieldError, FieldValueError) all derive from PdfFormError.
How fields map to JSON Schema
| Field kind | JSON Schema |
|---|---|
| text | {"type": "string"}, plus maxLength when /MaxLen is set |
| check box | {"type": "boolean"} |
| radio group | {"type": "string", "enum": [...on states...]} |
| dropdown | {"type": "string", "enum": [...]}, or a free string for an editable combo box |
| list box | as dropdown, or an array of them when multi-select is set |
| push button | omitted, it holds no value |
| signature | omitted by default, pdfform cannot sign |
Read-only fields are omitted unless --include-read-only is given. Everything needed to write a value back is preserved under the x-pdf keyword, which validators ignore:
"Grund_Probandenentgelt": {
"type": "boolean",
"description": "Probandenentgelt",
"x-pdf": {"field": "Grund_Probandenentgelt", "kind": "checkbox", "pages": [0], "onState": "Ja", "offState": "Off"}
}
Filling accepts more than the schema strictly describes: a check box takes true/false as well as its on-state name, a radio group or dropdown takes an option's display label as well as its export value, and null clears a field. Unknown names and out-of-range values are errors by default and warnings under --no-strict. Use validate when the data is meant to be schema-clean, since it holds it to the stricter standard.
Compared to other tools
PyPDFForm also emits a JSON Schema, but it is lossy where it matters: a radio group becomes {"type": "integer"} addressed by option index, so the actual export values are unrecoverable, and a check box becomes a bare boolean that discards the on-state. pdfform puts the real on-state names in the enum and keeps them in x-pdf, so a schema plus a filled JSON document is enough to reconstruct exactly what was written. pdfcpu form export produces the closest thing on the CLI side but is not JSON Schema, and its checkbox handling only recognises /Yes as checked.
Things that bite when filling PDF forms
These are the reasons this tool exists rather than a forty-line script.
Check box on-states are not /Yes. The checked value is whichever key appears in the widget's /AP /N dictionary, and it may be /On, /1, /Ja, /x or anything else. pdfform reads it per field.
/V alone is not enough. /V is the logical value; /AS selects which appearance stream gets drawn. Set only /V and the file is correct while the box looks empty in every viewer. For a radio group the rule applies per widget: /V goes on the group, every kid gets /AS, and only the kid whose own on-state matches is switched on.
A button value is a name, not a string. Written as a text string it is silently ignored.
Appearance streams. Without regenerating appearances, Acrobat may show a value that Preview, Chrome's viewer or a printer does not. pdfform both generates appearance streams for text and choice fields and sets /NeedAppearances, since neither is reliable alone.
/AP /N is not always a state dictionary. For text fields it is a single stream, whose dictionary keys are /BBox, /Resources and friends. Reading those as appearance states is the usual way to invent on-states that do not exist.
Field names are hierarchical. The real name is the /T of every ancestor joined with ., and only the leaf is stored on the field itself. --nested splits them back into nested objects. A partial name may itself contain a literal dot, so the flat name stays available under x-pdf.field.
Widgets are usually not the field. A field with one widget is normally merged into a single dictionary, but a field with several has them as /Kids, and the /AP sits on the kid. Looking only at the objects returned by a get_fields() style call finds no on-state for fields that visibly have check boxes.
XFA. Many government and banking forms store the real definition in an XML /XFA packet. If AcroForm fields exist alongside it the form is static XFA: fillable, but Acrobat may re-read the XFA data on open and discard the values, so pdfform fill drops the XFA layer by default. If /Fields is empty the form is dynamic XFA: script-generated, with no fixed field list, and pdfform says so instead of emitting an empty schema. The template packet is a much richer schema source than the AcroForm; pdfform xfa --packet template dumps it.
Field names are often meaningless. Text12 and Kontrollkästchen3 produce a schema that is structurally correct and semantically useless. The document's own /TU tooltip is used as the description when present. Failing that, --infer-labels guesses from the text printed next to each widget, including per-option labels for radio groups. It is a geometric heuristic, right most of the time and wrong some of the time, which is why it is opt-in.
Flattening
--flatten draws each widget's current appearance into the page content stream and removes the form. The appearance is placed by transforming the /BBox by the form's /Matrix, taking the bounding box of the result, and mapping that onto the annotation /Rect, per PDF 32000-1 section 12.5.5. Translating to the rectangle corner instead, which is the common shortcut, misplaces any appearance whose /BBox is not at the origin.
Widgets that are hidden, or that have no appearance stream at all, are removed without being painted. That matches what a viewer shows for them.
Development
See CONTRIBUTING.md.
License
MIT
Metadata
Release files for pdfform 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pdfform-0.2.0.tar.gz | 95.2 kB | With provenance | Details for pdfform-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdfform-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for pdfform-0.2.0-py3-none-any.whl |
Total release size: 130.6 kB
Release files / pdfform-0.2.0.tar.gz
| Download URL | pdfform-0.2.0.tar.gz |
|---|---|
| Size | 95.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a1cd2d9ff5dbb1540a6118a568da8220bd44a28584543bc041c57706b0af28f
|
|
BLAKE2b-256 checksum How to use checksums |
ee262bd21df872b8e4166db9c35ca3c484b95c7233da3a6917b14c61aa482bdc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / pdfform-0.2.0-py3-none-any.whl
| Download URL | pdfform-0.2.0-py3-none-any.whl |
|---|---|
| Size | 35.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dfa7090f4d5e234748c455c6668eb4fd986116d97b3c8da0176cee5ba6230701
|
|
BLAKE2b-256 checksum How to use checksums |
807b93c0989b627b7b7ed7d3a8027808b63ff0e3f1e783f5af2a727b93e7c811
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logSecurity for pdfform 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pdfform-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.