Add form fields and PDF form interoperability #8264

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 must stay in focused child issues.

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

Goal

LibreSign should support document fields through one consistent model that can be used across:

• the browser editor;
• the LibreSign API and workflow;
• PDF form interoperability;
• signing;
• templates and reusable workflows.

The implementation must avoid creating separate incompatible field models for each layer.

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       sign / validate
AcroForm

A logical field is not necessarily one visible rectangle.

The LibreSign field model should support the concepts required by both:

• fields created inside LibreSign;
• compatible fields imported from PDFs.

Vendor-specific PDF objects and signing-engine-specific concepts must not become part of the LibreSign domain model.

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

The editor should provide the generic field and widget editing foundation required by LibreSign and other consumers.

2. LibreSign field domain and API

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

The model should cover the concepts needed for:

• field identity and type;
• field placement and widgets;
• values and validation;
• recipient association;
• field origin;
• API representation;
• audit-relevant changes.

Detailed schema and API behavior should be defined in focused implementation issues.

3. PDF form backend

LibreSign needs a PDF form backend that can handle supported AcroForm operations without exposing one PDF library throughout the application.

This area includes:

• reading supported AcroForm fields;
• writing and filling supported fields;
• preserving PDF integrity;
• reporting unsupported form features safely.

Library selection, supported field types and detailed behavior belong in focused issues.

4. AcroForm interoperability

LibreSign should be able to map supported AcroForm fields to and from its own field domain.

The intended direction is:

PDF AcroForm
     |
     v
LibreSign fields
     |
     v
LibreSign workflow
     |
     v
PDF output

Initial work should include common AcroForm field concepts and existing PDF signature fields.

XFA and other unsupported PDF form technologies should be handled explicitly instead of silently modified.

5. Signature workflow integration

Fields should become part of the signature-request domain rather than existing only as visual coordinates.

This includes support for assigning relevant fields to recipients and using field state during the signing workflow.

Visible signature fields must remain separate from the digital signature itself.

Related work:

• Clarify PDF signatures without visible signature fields #8321

6. Existing PDF signature fields

LibreSign should support compatible signature fields that already exist in a PDF.

They should be represented through the same LibreSign field model and be usable in the normal recipient and signing workflow.

Signing-engine-specific support must be tracked in focused child issues.

The epic must not depend on one particular signing engine or implementation.

7. PDF signature integrity

PDF form operations and digital signing must preserve the expected PDF signature semantics.

The architecture must support incremental signing, existing signatures and PDF certification restrictions.

Detailed rules and engine-specific behavior should be defined in focused issues.

8. Templates and reuse

The shared field model should support future reusable workflows, including templates where field definitions can be preserved independently from the final recipient assignment.

Related issue:

• Templates for a quicker workflow #5628

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
• Clarify PDF signatures without visible signature fields #8321

Field types and dynamic values

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

Reuse and document workflows

• 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
• PhpNative engine: non-ASCII characters in the signature stamp are rendered as mojibake #8155

These issues should remain focused on their original user needs.

This epic provides the shared architecture and roadmap.

Related repositories

LibreSign/pdf-elements

Generic Vue editor and field/widget model.

It should remain usable outside LibreSign and Nextcloud.

LibreSign/signer-php

Signing-specific PDF support may be required by some child issues.

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

JSignPdf/jsignpdf-php

Signing-engine capabilities needed by LibreSign should be exposed through focused integration work.

Engine-specific behavior should not become part of this epic.

PHP PDF library

LibreSign needs a maintained PDF library capable of supporting the required AcroForm operations.

The library choice and exact supported capabilities should be validated in focused issues.

Testing

Each implementation area must include automated tests at the correct layer.

Testing responsibilities should remain separated:

• pdf-elements tests editor behavior;
• LibreSign tests domain, API and workflow behavior;
• the PDF backend tests AcroForm interoperability;
• signing integrations test signature integrity.

Cross-layer interoperability should be covered with representative PDF fixtures where appropriate.

Detailed test cases belong in child issues.

Scope control

This epic is a roadmap, not an implementation task.

Create focused child issues for:

• field model and API work;
• PDF backend work;
• AcroForm import/export;
• individual field types;
• existing PDF signature fields;
• signing-engine integrations;
• template integration;
• other concrete implementation work.

Do not implement the complete epic in one pull request.

Completion

This epic is complete when LibreSign has a consistent field architecture that supports:

• creating and persisting supported fields;
• editing them through pdf-elements;
• assigning relevant fields to recipients;
• importing and exporting supported AcroForm fields;
• using fields in signing workflows;
• supporting compatible existing PDF signature fields;
• preserving PDF and signature integrity;
• reusing field definitions in workflows such as templates;
• automated interoperability coverage across the supported path.

Downstream handoff

#9051 depends on the field/domain contracts established by this epic.

Before closing this epic, review #9051 against the final LibreSign field model, recipient association, validation, placement/widget and API contracts produced here. Update #9051 where needed before creating its implementation backlog.

Do not let AI-specific planning create a parallel field model or freeze assumptions that this epic has not yet established.