Convert between Instant JSON and XFDF

XFDF is Adobe’s XML-based format for sharing PDF form data and annotations. Many legacy review workflows ship XFDF files alongside PDFs, and teams that migrate to Instant JSON often need a bridge between the two formats. Nutrient .NET SDK can import and export both formats, so an XFDF payload from an older system can become an Instant JSON file for Web SDK, Document Engine, or another GdPicture-based service.

This guide shows how to move data between the two formats.

• Apply an Instant JSON file to a PDF and export the result as XFDF
• Reimport the XFDF file and export it back as Instant JSON
• Control whether form fields, annotations, or both are included in each direction

Prepare the project

Start by registering the SDK license before you process documents. For setup details, refer to the getting started with .NET SDK guide.

using GdPicture14;

LicenseManager licence = new LicenseManager();
licence.RegisterKEY(""); // Set your license key

Import Instant JSON and export XFDF

Start with a PDF that already contains form fields. The first step is to import an Instant JSON file with form field values, then export the resulting state as XFDF. The XFDF export uses two Boolean values to control which object families it includes — set both to true to capture the full annotation and form field surface:

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.LoadFromFile(@"test_form_fields.pdf");

    GdPictureStatus importStatus = pdf.ImportInstantJSONDataFromFile(@"test_form_fields_instant.json");
    if (importStatus != GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Instant JSON import failed: {importStatus}");
        Environment.Exit(1);
    }

    GdPictureStatus exportStatus = pdf.ExportXFDFDataToFile(@"output.xfdf", ExportFormFields: true, ExportAnnotations: true);
    if (exportStatus != GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"XFDF export failed: {exportStatus}");
        Environment.Exit(1);
    }
}

The XFDF payload is human-readable XML, so you can inspect it in a text editor before you send it to a downstream consumer.

Import XFDF back into a PDF

Next, open the same source PDF in a new GdPicturePDF instance and import the XFDF you just produced. ImportXFDFDataFromFile mirrors the export call, and two Boolean values enable you to scope the import to form fields, annotations, or both:

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.LoadFromFile(@"test_form_fields.pdf");

    GdPictureStatus importStatus = pdf.ImportXFDFDataFromFile(@"output.xfdf", ImportFormFields: true, ImportAnnotations: true);
    if (importStatus != GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"XFDF import failed: {importStatus}");
        Environment.Exit(1);
    }

Export the imported XFDF as Instant JSON

After you import the XFDF, export the document state as Instant JSON. Pass fullState: true so the export captures every annotation and form field, not just the diff since load:

    using FileStream stream = new FileStream(@"output.json", FileMode.Create, FileAccess.Write);
    GdPictureStatus exportStatus = pdf.ExportInstantJSONDataToStream(stream, fullState: true);
    if (exportStatus != GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Instant JSON export failed: {exportStatus}");
        Environment.Exit(1);
    }
}

Scope the conversion

Use the ImportFormFields / ExportFormFields and ImportAnnotations / ExportAnnotations flags when only one object family should round-trip. For example, export only form values back to a server that doesn’t need review markup, or import annotations from a markup tool without overwriting form data filled in by an end user.

Error handling

XFDF and Instant JSON imports validate input before they apply changes. Common failure cases include:

• GdPictureStatus.PdfDocumentMustBeUnencrypted — both formats refuse to operate on encrypted PDFs
• GdPictureStatus.FileNotFound — the path is wrong, or the source file is missing
• GdPictureStatus.GenericError — malformed XFDF or Instant JSON

For status-handling patterns, refer to the handling errors with .NET SDK guide.

Conclusion

This guide bridges Instant JSON and XFDF in both directions. It gives you a migration path from legacy XFDF-based workflows to Instant JSON while still supporting downstream consumers that expect XFDF.