RFC: typed form-field attributes in docling-core (accessible name /TU, field types, states)

[wittjeff]

This is a docling-core schema proposal (that repo has discussions disabled, so posting here). Follow-up to #301 and companion to docling PR #4055, which extracts the AcroForm widget layer and is the concrete producer that wants to write these attributes.

1. Motivation

DoclingDocument's form model (FormItem + GraphData, the field_* labels) represents visible page content: every GraphCell documents its text/orig as "text as seen on document." Interactive PDF forms carry load-bearing information that has no page presence — the AcroForm field dictionary — and the model currently has no typed slot for it. This blocks two things:

1. Faithful extraction from born-digital PDFs. Field names, types, states, and values are machine-readable in the file, but only partially representable in the document. PR docling#4055 works around this by keeping the lossless record on a Python-level FormFieldInfo while serializing only what the schema can hold.
2. PDF/UA as an output target. PDF/UA (ISO 14289) requires every form field to have an accessible name — the /TU tooltip in PDF/UA-1 §7.18.1, or the structure-tree label association in PDF 2.0 / PDF/UA-2. A model that cannot distinguish "visible label" from "accessible name" cannot represent the most common form-accessibility defect (visible label present, /TU missing), the fix (generate /TU from the bound visible label), or the quality check (does /TU match the label semantically?).

The same visible-vs-programmatic split runs through all accessibility tooling: HTML's <label> vs aria-label, a picture's caption vs its alt text. DoclingDocument has crossed the "content with no pixels" bridge before, with ActualText.

2. Current state (verified against docling-core 2.91)

• FormItem: FloatingItem + graph: GraphData. No field-level typed attributes.
• FieldRegionItem: bare DocItem (label + prov only).
• GraphCellLabel: unspecified | key | value | checkbox — no field-type taxonomy, and no state on the cell (state exists only as the DocItemLabels checkbox_selected / checkbox_unselected).
• GraphLinkLabel: to_value | to_key | to_parent | to_child.
• NodeItem.meta / MiscAnnotation(content: dict): untyped escape hatch only.
• Producers today: the HTML backend (<form> structures) and the XBRL backend; docling#4055 adds the PDF widget layer.

3. Proposal

Keep two layers cleanly separated:

Layer 1 — page content (unchanged): visible labels, printed values, and checkbox glyphs stay GraphCells with provenance, linked to field items.

Layer 2 — field dictionary (new, typed): attributes on the field item (FieldRegionItem, or a new FormFieldItem), or a dedicated FormFieldMeta object:

Attribute	PDF source	Purpose
field_name	/T (fully qualified)	identity, radio-group inference
accessible_name	/TU	PDF/UA accessible name; distinct from the visible label by design
mapping_name	/TM	export/interop
field_type	/FT + flags	enum: text | checkbox | radio | combobox | listbox | pushbutton | signature
value / default_value	/V, /DV	filled-form state
state	/AS vs on-state	checkbox/radio on/off
export_value	/Opt, appearance states	what "checked" means
required, readonly	/Ff bits	validation + AT announcement
radio_group	shared parent /T	mutual-exclusivity set
widget_ref	object number / annot index	round-trip hook: lets a writer locate the widget to add or fix /TU, tags, tab order
tab_order	page /Tabs, annot order	PDF/UA requires a logical tab order

Relationship rule: the visible-label ↔ field binding remains a GraphLink (to_key / to_value); accessible_name is never inferred into the graph. A consumer wanting "the best label" gets a documented resolution order: accessible_name → linked visible label → field_hint.

4. Not PDF-specific

The HTML backend maps onto the same attributes cleanly (name= → field_name, aria-label/title → accessible_name, <input type=> → field_type, required → required, checked → state), which keeps the model format-neutral.

5. Serialization

• markdown/HTML/doctags export: lossy renderings to be specified (☐/☑ + label; accessible_name as title= in HTML export).
• Forward pointer: these attributes are what a future tagged-PDF / PDF/UA serialization target would consume.

6. Backward compatibility

All additions optional-with-defaults; existing HTML/XBRL producers unaffected; no changes to GraphData validation.

7. Open questions

1. FormFieldItem as a new item type vs attributes on FieldRegionItem?
2. Should visual-only detections (scanned forms, layout-model output) use the same item with the dictionary attributes simply absent — one taxonomy for born-digital and visual? (Our preference: yes — it lets vision pipelines fill the same slots with lower confidence.)
3. Where does widget_ref provenance belong — a ProvenanceItem extension or a field attribute?
4. Appetite for tab_order now, or only with serializer work?

We're happy to implement whichever shape the maintainers prefer — docling#4055's FormFieldInfo already carries every value in the table, so the write-side lands as a small follow-up once the schema exists.

🤖 Generated with Claude Code

[wittjeff]

Closing this as superseded.

Since it was posted, the maintainers retired the FormItem + GraphData model this RFC was built on, and #4140 materializes AcroForm widgets as FieldRegionItem / FieldItem / FieldValueItem from docling-parse's native widget extraction. The parts of this proposal that survive that change (a typed role and state, required and read-only flags, choice options, an accessible name kept distinct from the visible label, and a widget reference for round-tripping) now live in section 5 of #4143, aligned with Well-Tagged PDF 1.0 and PDF/UA-2 rather than PDF/UA-1. #4144 is the first implementation step, using /TU as FieldKeyItem text on top of #4140.

Discussion continues on #4143.