Epic: Add form fields and PDF form interoperability

[vitormattos]

LibreSign needs a consistent way to create, persist, fill, import and sign document fields.

This epic is the main roadmap for form-field support across LibreSign and related projects. Implementation details should stay in focused issues in each repository.

LibreSign should have its own field domain model. PDF AcroForm should be treated as an interoperability format, not as LibreSign's internal model.

Note

This epic defines the goal, architecture and scope.
Pull requests should implement focused child issues, not the epic itself.

Important

Funding and community support needed

This is a large feature that affects the PDF editor, LibreSign domain and API, PDF interoperability, signing engines, templates and automated tests.

We are looking for organizations interested in funding this work and for contributors who want to help implement the roadmap.

Companies that need advanced form fields, reusable document templates or AcroForm interoperability are especially welcome to support the development of this feature.

Community contributions are also welcome. Please use the focused issues linked below instead of trying to implement the complete epic in one pull request.

Architecture

The responsibilities should remain separated:

pdf-elements
  browser rendering and field editing
        |
        v
LibreSign domain / API
  fields, recipients, values, validation and audit
        |
        +----------------------+
        |                      |
        v                      v
PDF form backend          signing engines
read / write / fill       signer-php / JSignPdf
AcroForm                  sign / validate

A logical field is not necessarily one visible rectangle. The model must support one field with multiple widgets, including widgets on different pages and radio groups.

Roadmap

1. PDF editor foundation

Work is tracked in LibreSign/pdf-elements:

• Improve library quality gates and package validation pdf-elements#80
• Add browser interaction and accessibility tests with Playwright pdf-elements#82
• Automate README screenshot generation and visual validation pdf-elements#83
• Define a stable form field and widget data model pdf-elements#84
• Add generic form-field editing support pdf-elements#85

Do not create one issue for every field type before the shared model and editing foundation are stable.

2. LibreSign field domain and API

LibreSign needs a domain model independent from the browser editor and PDF library.

It should cover:

• field identity and semantic type;
• widgets and document/page placement;
• values, defaults and validation;
• required and read-only state;
• choice options;
• recipient association;
• source/origin such as manual, AcroForm, template or API;
• API serialization;
• audit-relevant changes.

Vendor-specific PDF objects should not be exposed through the LibreSign domain or API.

3. PDF form backend

LibreSign needs an internal abstraction for PDF form operations instead of using one vendor library throughout the application.

Expected capabilities include:

• inspect existing AcroForm fields;
• read field hierarchy and widgets;
• fill existing fields;
• create or update supported fields;
• preserve forms during incremental updates;
• optionally flatten fields when explicitly required;
• report unsupported PDF features without silently damaging documents.

The selected PHP PDF library must be validated with real-world PDFs, including xref/object streams, multiple widgets, Unicode, incremental updates and signed documents.

A separate LibreSign repository is not required for this adapter unless a concrete reuse case appears later.

4. AcroForm interoperability

Expected flow:

PDF AcroForm
     |
     v
import / transform
     |
     v
LibreSign fields
     |
     v
workflow values and recipients
     |
     v
PDF backend + signing engine

Initial interoperability should consider text fields, checkboxes, radio groups, choice fields, hierarchy, inherited properties, multiple widgets, required/read-only flags and existing signature fields.

XFA should be detected and reported as unsupported unless support is intentionally added later.

5. Signature workflow integration

Fields should become part of the signature-request domain rather than only coordinates rendered over a PDF.

This includes:

• assigning fields to recipients where applicable;
• validating required fields;
• collecting and preserving values;
• writing values to the final PDF;
• exposing field state through the API;
• recording relevant field changes in the audit trail.

6. Preserve PDF signature semantics

Form manipulation and digital signing must remain separate responsibilities.

The PDF backend prepares allowed document changes. Signing engines sign and validate the resulting revision.

The implementation must respect existing incremental signatures and certification permissions:

• DocMDP P=1: no changes;
• P=2: form filling and signatures;
• P=3: form filling, signatures and annotations.

FieldMDP can be added later, but the architecture must not prevent future support.

Existing PDF signature fields should also be supported when the signing backend provides this capability.

7. Templates and reuse

Stable fields should later support reusable document templates where field definitions are preserved independently from the final recipient assignment.

Related issue:

• #5628 — Templates for a quicker workflow

Existing LibreSign issues

These issues describe user needs that should be solved by or aligned with this roadmap.

Visible fields and editor

• Add more visible fields #1863
• Studdy issue: Searching by PDF viewer #1972
• Require at least one signature field before sending document #7710

Field types and dynamic values

• Option to add initials to document #5273
• [FEATURE]: Dynamic fields insertion (signer metadata) directly in PDF #7246
• Choosing a signature option and double signature #3925

Reuse and document workflows

• [FEATURE]: Templates for a quicker workflow #5628
• Allow a new set of signatures on the same original document #4161
• simpler way to sign my own documents #4005

PDF integrity and signing

• [FEATURE]: DocMDP (“No changes allowed”) + UI notice “modified after signing” #5701
• Question: should signed PDF forms be read-only after signing? #617
• Update JSignPdf to 3.x #8068
• PhpNative engine: non-ASCII characters in the signature stamp are rendered as mojibake #8155

These issues should remain focused on their original user need. This epic provides the shared architecture and implementation order.

Related repositories

LibreSign/pdf-elements

Generic Vue editor and visual field/widget model. It must remain usable outside LibreSign and Nextcloud.

LibreSign/signer-php

Signing-specific support may be needed to preserve AcroForm during incremental signing, sign existing signature fields and support safe fill-then-sign workflows.

Generic PDF form editing should not be implemented in the signing library.

JSignPdf/jsignpdf-php

The wrapper should expose stable JSignPdf support for discovering and signing existing PDF signature fields when that feature is available.

PHP PDF library

LibreSign needs a maintained PHP library for AcroForm read/write operations.

Where practical, missing capabilities should be contributed upstream instead of maintaining LibreSign-specific forks.

Testing

Tests should cover the complete interoperability path using representative and externally generated PDF fixtures where possible.

Important cases include:

• different page sizes and rotations;
• text, checkbox, radio and choice fields;
• field hierarchy;
• multiple widgets;
• Unicode;
• existing signature fields;
• incremental updates and already-signed PDFs.

pdf-elements should test browser interaction. LibreSign should test domain/API behavior. The PDF backend should test interoperability. Signing engines should test signing integrity.

Scope control

This epic is a roadmap, not a single implementation task.

Create focused issues when each stage is ready. Avoid speculative issues for every possible field type before the shared infrastructure is available.

Completion

This epic is complete when LibreSign can:

• create and persist form fields;
• edit them using pdf-elements;
• assign relevant fields to recipients;
• collect and validate values;
• import supported AcroForm fields;
• write supported values safely to PDFs;
• sign without losing form or previous-signature integrity;
• reuse field definitions in workflows such as templates;
• validate the supported path with automated tests.