1. Widget Extraction

Stage 1 shows all interactive PDF fields: text boxes, checkboxes, radio buttons, select controls, and signature fields. These source fields are called widgets.

Widget table

Drawing a new widget

Press D to enter draw mode, then drag on the PDF canvas to define the widget box. A popup lets you choose the widget type.

2. Widget Linking

Stage 2 labels source widgets and helps identify widgets that still need review. Stage 3 uses these widgets as the allowed source IDs when building Schema V3.

3. Form Builder

Stage 3 edits Schema V3 directly. The left panel shows pages and ordered page items. Select any item to edit it in the inspector. Changes auto-save as a draft; use Update DB when the schema is ready to become the pipeline output.

Schema V3 Structure

A Schema V3 document is a clean form definition. Extraction status, provider, model, usage, and page diagnostics live outside the schema in the extraction envelope.

Page items are flat and ordered. A section is only a marker heading. Groups, tables, and repeat groups are the containers for nested items.

Item Types

What the JSON Looks Like

Envelope

{
  "schema": {
    "schema_version": 3,
    "title": "Employment Form",
    "page_count": 3,
    "pages": [
      { "page": 1, "items": [] }
    ]
  },
  "extraction": {
    "file_id": "64a1f3...",
    "cached": false,
    "version": 0,
    "provider": "openrouter",
    "model": "openai/gpt-4o-mini",
    "usage": {},
    "api_error": false,
    "parse_error": false,
    "processing": false,
    "page_status": []
  }
}

Simple field

{
  "kind": "field",
  "label": "First Name",
  "input_type": "text",
  "widgets": [
    { "widget_id": "page1-widget6" }
  ]
}

Split field

{
  "kind": "field",
  "label": "Date of Birth",
  "input_type": "date",
  "parts": [
    { "label": "Month", "widget_id": "page1-widget1" },
    { "label": "Day", "widget_id": "page1-widget2" },
    { "label": "Year", "widget_id": "page1-widget3" }
  ]
}

Choice field

{
  "kind": "field",
  "label": "Please check all that apply.",
  "input_type": "checkbox",
  "choices": [
    { "label": "Absent Parent", "widget_id": "page1-widget13" },
    { "label": "Child Care", "widget_id": "page1-widget15" },
    {
      "label": "Other",
      "widget_id": "page1-widget35",
      "details": {
        "label": "Other",
        "input_type": "text",
        "widgets": [
          { "widget_id": "page1-widget32" }
        ]
      }
    }
  ]
}

Group and repeat group

{
  "kind": "group",
  "label": "Applicant Name",
  "items": []
}

{
  "kind": "repeat_group",
  "label": "Providers",
  "item_label": "Provider",
  "items": [
    { "label": "Provider 1", "items": [] }
  ]
}

Field Types and Widget Carriers

Every field has an input_type and exactly one widget carrier.

Irregular Tables

Schema V3 tables do not need row spans, column spans, or a regular/irregular setting. Each row owns its own cells. A row may have two cells, the next may have three, and another may include an empty cell.

{
  "kind": "table",
  "label": "Assessment",
  "rows": [
    {
      "cells": [
        { "kind": "text", "text": "Question" },
        { "kind": "text", "text": "Answer" },
        { "kind": "text", "text": "Comments" }
      ]
    },
    {
      "cells": [
        { "kind": "text", "text": "Pain level" },
        {
          "kind": "field",
          "label": "Pain level",
          "input_type": "number",
          "widgets": [{ "widget_id": "page2-widget1" }]
        }
      ]
    },
    {
      "cells": [
        { "kind": "text", "text": "Mobility notes" },
        {
          "kind": "field",
          "label": "Mobility notes",
          "input_type": "text",
          "widgets": [{ "widget_id": "page2-widget2" }]
        },
        { "kind": "empty" }
      ]
    }
  ]
}

Decision Guide

Which item kind?

Which carrier?

PDF Widget Linking

A widget reference connects a Schema V3 field to a physical PDF widget. The reference is always a widget_id inside widgets[], parts[], choices[], or a choice's optional details.

1. Select a field in the Stage 3 tree.
2. Choose the carrier mode in the field inspector.
3. Select the target slot, part, or choice.
4. Click the matching PDF widget in link mode.

Validation and Review

Click Checks or press Ctrl+K to run validation. Update DB blocks when Schema V3 is malformed or PDF widget coverage is incomplete.

Keyboard Shortcuts

Common Errors

"Schema V2 structured JSON is not supported"

The draft or cache uses the old V2 shape. Re-run Stage 3 extraction so the backend produces Schema V3.

"Field must use exactly one widget carrier"

Open the field inspector and choose one mode: widgets, parts, or choices. Remove the other carriers.

"Duplicate widget ID"

The same PDF widget is referenced by more than one field. Keep the first correct owner and unlink the duplicate reference.

"Missing extracted widget"

A source PDF widget is not owned by any field. Link it to the right field, or keep it in the Unresolved fields group until you decide where it belongs.

"Unknown widget ID"

The schema references a widget ID that does not exist in the current PDF widget list. Remove the bad reference or relink the field to a valid widget.