AcroForms,
forged clean.

Take a broken-named PDF form and make it programmatically fillable in three commands. Heuristic discovery, human-reviewable mapping, deterministic rename.

Get started Read the manual GitHub ↗

Small, focused commands. Each one reviewable.

Each command does one job and produces an artifact you can inspect before the next step touches the PDF. Pick the ones you need.

prepareResolves PDF-internal name conflicts — multiple fields sharing one literal name — using the heuristic's proposals, so later stages never trip on ambiguity. Skips itself when there's nothing to resolve.optional

bootstrapInfers a starter schema and proposes a per-field mapping in one compile pass. The output is two YAML files you review and edit — nothing has touched the PDF yet.→ schema.yml · mapping.yml

annotateRenders a copy of the PDF with every field labeled inline, colour-coded against your mapping — green for confident, amber for review-needed. Open it next to your editor while you work.→ annotated.pdf

relabel applyValidates your edited mapping in full, then permanently rewrites the AcroForm field names. Collisions auto-disambiguate, and the PDF comes out programmatically fillable.→ form.pdf, fixed

What you stop writing.

Same PDF. Two starting points. One is a three-hour spelunk through page0_fieldN in a PDF viewer.

What the vendor shipped

page0_field6

page0_field7

untitled3

Text-4

page1_field2

After AcroForge

first_name

surname

date_of_birth

guardian_phone ?

home_address

● confident ● review-needed — the same colour-coding annotate draws on the PDF itself

What the engine does well.

Discovery, review, rename, fill — plus the details that make those steps reliable on real-world PDFs.

Spatial label discovery

For each cryptic field, the engine scans surrounding text with mode-aware weighted scoring across Grid-Lock, Inline Paragraph, and Standard Label layouts. The label finds you.

Human-readable artifacts

Every stage produces a YAML you can open in an editor. The mapping documents what was guessed, what was confident, and what you decided. Re-running propose preserves your edits.

Visual review

annotate renders a copy of the PDF with each field labeled inline, colour-coded against your mapping — green for confident proposals, amber for review-needed, gray for missing. Open it next to your editor.

Duplicate-name resolution

Some PDFs ship with three fields all literally named date. prepare spots them and rewrites each to a unique heuristic-proposed name before the mapping is generated, so the YAML stays clean.

Unicode-clean labels

Ligatures (ﬁ ﬂ ﬀ), curly quotes, en/em dashes, zero-width chars: NFKC plus a small substitution table normalize every extracted label so grep, search, and your mapping reviews all work on plain ASCII.

Schema-driven, deterministic

Declare canonical fields once — the engine canonicalises vendor variations into one key set and the validator enforces type contracts. The whole mapping validates before anything touches the PDF, so it never half-renames.

Shell or Ruby. Same engine.

The CLI is a thin shell over the public Ruby API. Choose the surface that fits your workflow.

Shell

bash

# Resolve duplicate AcroForm field names, if any
acroforge prepare form.pdf

# Infer schema + propose mapping in one compile pass
acroforge bootstrap form.pdf

# Visual review: open annotated.pdf alongside mapping.yml
acroforge annotate form.pdf --mapping mapping.yml

# Apply your edited mapping to the PDF in place
acroforge relabel apply form.pdf mapping.yml

CLI reference →

Ruby

ruby

require "acroforge"

# Infer schema + propose mapping in one pass
schema = AcroForge::Schema.infer("form.pdf")
AcroForge::Schema.dump(schema, "schema.yml")

# Visual review file colour-coded against the mapping
AcroForge::Annotator.annotate("form.pdf",
  mapping: "mapping.yml", out: "annotated.pdf")

# Apply mapping in place after review
AcroForge::Relabeler.apply!("form.pdf", "mapping.yml")

Library API →

Stop hand-mapping page0_field6.

Add AcroForge to your Gemfile, then walk through the quick start. Five minutes to a fillable PDF.

Quick start GitHub

Add the gem

gem "acroforge"

Bootstrap

acroforge bootstrap form.pdf

Review the mapping

$EDITOR mapping.yml

Apply

acroforge relabel apply → fillable PDF

AcroForms,forged clean.