Epic: Add form fields and PDF form interoperability

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.

[!NOTE]

This epic defines the goal, architecture and implementation areas.
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 work on focused implementation issues instead of trying to complete the whole epic in one pull request.

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:

• https://github.com/LibreSign/pdf-elements/issues/80
• https://github.com/LibreSign/pdf-elements/issues/82
• https://github.com/LibreSign/pdf-elements/issues/83
• https://github.com/LibreSign/pdf-elements/issues/84
• https://github.com/LibreSign/pdf-elements/issues/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:

• https://github.com/LibreSign/libresign/issues/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:

• https://github.com/LibreSign/libresign/issues/5628

Existing LibreSign issues

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

Visible fields and editor

• https://github.com/LibreSign/libresign/issues/1863
• https://github.com/LibreSign/libresign/issues/1972
• https://github.com/LibreSign/libresign/issues/8321

Field types and dynamic values

• https://github.com/LibreSign/libresign/issues/5273
• https://github.com/LibreSign/libresign/issues/7246
• https://github.com/LibreSign/libresign/issues/3925

Reuse and document workflows

• https://github.com/LibreSign/libresign/issues/5628
• https://github.com/LibreSign/libresign/issues/4161
• https://github.com/LibreSign/libresign/issues/4005

PDF integrity and signing

• https://github.com/LibreSign/libresign/issues/5701
• https://github.com/LibreSign/libresign/issues/617
• https://github.com/LibreSign/libresign/issues/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.

This is a roadmap epic rather than an implementation task; start by reviewing the linked child issues in LibreSign/pdf-elements and the related LibreSign issues for a focused work area. Choose one concrete area, define its scope and layer-specific tests in a child issue, and treat the epic as complete only when the listed field, interoperability, signing, template, and integrity capabilities are covered.