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. - Signature images.
stampdraws a PDF, PNG, JPEG or SVG signature into a signature field, or into a new one at a place on the page. - Cryptographic signing.
signsigns the document with a certificate, as a separate step. - 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
The signature commands bring their own dependencies, so the base install stays small:
pip install 'pdfform[stamp]' # PNG, JPEG and SVG signatures (Pillow, svglib). PDF signatures need nothing extra
pip install 'pdfform[sign]' # cryptographic signatures (pyHanko)
From a checkout, uv sync --all-groups --all-extras 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 stamp and pdfform sign, described below, 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, it takes no value. See stamp and 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.
Signing
A signature field cannot be filled with a value, and "signing" means two different things. They are two commands, and they compose.
stamp draws a signature image. It makes the field look signed, nothing more. The image becomes the field's appearance, so fill --flatten bakes it into the page like any other widget.
pdfform stamp form.pdf --field Antragsteller_Unterschrift --image signature.png -o stamped.pdf
The source can be a PDF (first page), PNG, JPEG or SVG. The image keeps its aspect ratio and is centred in the field (--fit contain), or fills it and distorts (--fit stretch). Transparent PNGs keep their transparency. A PDF or SVG stays vector, and a JPEG is embedded as is. On a turned page, or a widget turned by /MK /R, the image turns with the field, so it reads upright.
sign adds a cryptographic signature. It needs a certificate and a private key, as a PKCS#12 file or as PEM files. The signature is a PAdES signature (ETSI.CAdES.detached), written as an incremental update, so earlier signatures stay valid.
pdfform sign stamped.pdf --p12 me.p12 --field Antragsteller_Unterschrift -o signed.pdf
pdfform sign stamped.pdf --key key.pem --cert cert.pem --ask-passphrase -o signed.pdf
The passphrase is never a command line argument, so it stays out of the shell history. Use --ask-passphrase, --passphrase-file, or the PDFFORM_PASSPHRASE environment variable. A key without a passphrase loads even when one is set. A form with a single unsigned signature field signs that field. A document without one gets a new invisible field, Signature1 or the next free number. Several unsigned fields need --field. An image placed by stamp stays visible, and any other field gets pyHanko's text appearance. Fields that were not signed yet remain signable, so two people can sign two fields one after the other.
Order: fill, then stamp, then sign. Anything that rewrites the file afterwards, fill and stamp included, invalidates the signature. So with two signers, stamp both fields before the first signature. stamp refuses a signed document. fill still fills one, because certified blank templates are signed too, but it warns that the signature breaks. Whether a recipient trusts the signature depends on the certificate: a self-signed one gives a signature that is intact but not trusted. There is no timestamp, since that would need a request to a timestamp authority.
fill does all three at once. --stamp FIELD=IMAGE (repeatable, with --stamp-fit) stamps after the values are set. --sign signs last, and --sign-field picks the field. fill takes the same key and passphrase options as sign, so the order is always right:
pdfform fill form.pdf -d data.json --stamp Antragsteller_Unterschrift=signature.png \
--sign --sign-field Antragsteller_Unterschrift --p12 me.p12 -o signed.pdf
With --flatten the stamped image is baked into the page before signing. The signature then goes into a new invisible Signature1, because flattening removes the form, so --sign-field is refused. With --sign, fill does not set /NeedAppearances, because a viewer that regenerates appearances would change the signed file. The appearances fill generates itself stay.
Signing where there is no field. --page and --rect put a new signature field on a page, for a plain document or a form whose field is in the wrong place. --rect takes two opposite corners. Plain numbers are PDF points (1/72 inch) from the bottom left, the same numbers a /Rect holds. With mm, the corners are millimetres from the top left of the page as shown, which is what a ruler on a printout gives. Pages count from 1.
# draw the image into a new field, then sign it: it is the only unsigned one
pdfform stamp letter.pdf --field Unterschrift --page 2 --rect 18mm,230mm,88mm,250mm --image signature.png -o stamped.pdf
pdfform sign stamped.pdf --p12 me.p12 -o signed.pdf
# or sign into a new visible field directly, with pyHanko's text appearance
pdfform sign letter.pdf --p12 me.p12 --page 2 --rect 18mm,230mm,88mm,250mm -o signed.pdf
sign adds the new field in the same incremental update as the signature, so this also works for a second signer on a document that is signed already. stamp refuses a signed document, as above.
In Python:
from pdfform import fill_form, stamp_signature, sign_pdf
stamped = stamp_signature("form.pdf", "Antragsteller_Unterschrift", "signature.png")
sign_pdf(stamped, "signed.pdf", pkcs12="me.p12", passphrase="...", field="Antragsteller_Unterschrift")
# or fill and stamp in one pass, then sign
filled = fill_form("form.pdf", data, stamp={"Antragsteller_Unterschrift": "signature.png"})
sign_pdf(filled, "signed.pdf", pkcs12="me.p12", passphrase="...", field="Antragsteller_Unterschrift")
# a new field at a place: page is an index from 0 here, as in FormField.pages
stamped = stamp_signature("letter.pdf", "Unterschrift", "signature.png", page=1, rect=(18, 230, 88, 250), units="mm")
Development
See CONTRIBUTING.md.
License
MIT
Metadata
Release files for pdfform 0.3.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.3.0.tar.gz | 215.4 kB | With provenance | Details for pdfform-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdfform-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for pdfform-0.3.0-py3-none-any.whl |
Total release size: 267.7 kB
Release files / pdfform-0.3.0.tar.gz
| Download URL | pdfform-0.3.0.tar.gz |
|---|---|
| Size | 215.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cafd46dc05609b6107f0639cc28648d364b6af1bdaac3e827894012ef3ac23b7
|
|
BLAKE2b-256 checksum How to use checksums |
9fd641c9503c3afa70be873c8f3d650a1574a40bf635ea927c1cd5a959959785
|
| 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 Oct 1, 2026.
Transparency logRelease files / pdfform-0.3.0-py3-none-any.whl
| Download URL | pdfform-0.3.0-py3-none-any.whl |
|---|---|
| Size | 52.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a7af87596adcf49942a9efbcd61f328e4f7b4f8868af6593fe6e23946ce968af
|
|
BLAKE2b-256 checksum How to use checksums |
0c26fb9e8e226064786bb3b56ff16d9334103de32e65bf8f1bfd5a920f5d37f7
|
| 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 Oct 1, 2026.
Transparency logSecurity for pdfform 0.3.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.3.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 Oct 1, 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.