---
title: "Convert between Instant JSON and XMP | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/annotations/convert-between-instant-json-and-xmp/"
md_url: "https://www.nutrient.io/guides/dotnet/annotations/convert-between-instant-json-and-xmp.md"
last_updated: "2026-06-26T00:00:00.000Z"
description: "Convert annotation data between Instant JSON and XMP using Nutrient .NET SDK."
---

# Convert between Instant JSON and XMP

Nutrient supports two portable annotation formats: Instant JSON and XMP. Instant JSON is a JSON-based schema used across Nutrient products, including iOS, Web, Android, and Document Engine. XMP is GdPicture's XML-based annotation format. Teams often need to move annotation data between them. For example, you may export annotations created in a GdPicture workflow as Instant JSON for another Nutrient SDK, or you may import Instant JSON and store it as XMP beside the PDF.

This guide shows how to:

- Import an Instant JSON file into a blank PDF and export the result as XMP

- Reimport the XMP file and export it back to Instant JSON

- Choose between the flat, single-page XMP layout and the wrapped, multi-page layout

## Prepare the project

Start by registering the SDK license before you process documents. For setup details, refer to the [getting started with.NET SDK](https://www.nutrient.io/sdk/dotnet/getting-started.md) guide.

```csharp

using GdPicture14;

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

```

## Import Instant JSON and export XMP

Start with a fresh PDF, import a sample Instant JSON file, then export the resulting annotations as XMP. [`ExportXMPDataToFile`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPicturePDF~ExportXMPDataToFile.html) produces the flat, single-page XMP shape used by GdPicture's per-page XMP metadata stream:

```csharp

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.NewPDF();
    pdf.NewPage(612, 792);
    pdf.SelectPage(1);

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

    GdPictureStatus exportFlatStatus = pdf.ExportXMPDataToFile(@"output_flat.xmp");
    if (exportFlatStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Flat XMP export failed: {exportFlatStatus}");
        Environment.Exit(1);
    }

```

## Export the wrapped multi-page XMP shape

For documents with annotations across multiple pages, use [`ExportXMPDataToFileEx`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPicturePDF~ExportXMPDataToFileEx.html). The wrapped shape carries one `<PageAnnots>` entry per page, and each entry contains a base64-encoded flat XMP payload:

```csharp

    GdPictureStatus exportWrappedStatus = pdf.ExportXMPDataToFileEx(@"output_wrapped.xmp");
    if (exportWrappedStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Wrapped XMP export failed: {exportWrappedStatus}");
        Environment.Exit(1);
    }
}

```

Choose the shape that matches the consumer:

- **Flat XMP** — Use this per-page format for GdPicture's internal XMP metadata stream. Choose it when you target a single page or work with the `AnnotationManager` API.

- **Wrapped XMP** — Use this multi-page bundle when you need one artifact that carries every page's annotations.

## Import the XMP file back

[`ImportXMPDataFromFile`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPicturePDF~ImportXMPDataFromFile.html) auto-detects both layouts, so you don't need an `Ex` variant on the import side. Load the wrapped XMP into a fresh PDF and verify the round-trip:

```csharp

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.NewPDF();
    pdf.NewPage(612, 792);
    pdf.SelectPage(1);

    GdPictureStatus importStatus = pdf.ImportXMPDataFromFile(@"output_wrapped.xmp");
    if (importStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"XMP import failed: {importStatus}");
        Environment.Exit(1);
    }

```

## Export the imported annotations as Instant JSON

After you import XMP, export the document state as Instant JSON. Pass `fullState: true` to capture every annotation as a complete snapshot. The diff export path uses the change tracker, and the XMP import bridge doesn't currently feed it:

```csharp

    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);
    }
}

```

## Error handling

XMP and Instant JSON imports validate the payload 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 XMP or Instant JSON

For status-handling patterns, refer to the [handling errors with.NET SDK](https://www.nutrient.io/guides/dotnet/best-practices.md#error-handling) guide.

## Conclusion

This guide bridges Instant JSON and XMP in both directions. It gives you a path to move annotation data between Nutrient products, and it uses the wrapped XMP shape for multi-page documents while [`ImportXMPDataFromFile`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPicturePDF~ImportXMPDataFromFile.html) handles either input layout automatically.
---

## Related pages

- [Configure Instant JSON appearance and tracking](/guides/dotnet/annotations/configure-instant-json-appearance-and-tracking.md)
- [Attach a file to an annotation in C#](/guides/dotnet/annotations/attach-a-file.md)
- [Annotate on images in C# .NET](/guides/dotnet/annotations/annotate-on-images.md)
- [Attach an image to an annotation in C#](/guides/dotnet/annotations/attach-an-image.md)
- [Convert between Instant JSON and XFDF](/guides/dotnet/annotations/convert-between-instant-json-and-xfdf.md)
- [Create an annotation in a PDF using C#](/guides/dotnet/annotations/create.md)
- [Custom annotations](/guides/dotnet/annotations/custom-annotations.md)
- [Edit PDF annotations in C#](/guides/dotnet/annotations/edit.md)
- [Export Instant JSON from a PDF](/guides/dotnet/annotations/export-instant-json-from-pdf.md)
- [Export annotation data from PDFs in C# .NET](/guides/dotnet/annotations/export-pdf.md)
- [Get PDF annotation properties in C# .NET](/guides/dotnet/annotations/get-properties.md)
- [Export XMP annotation data in C# .NET](/guides/dotnet/annotations/export-xmp.md)
- [Import Instant JSON into a PDF](/guides/dotnet/annotations/import-instant-json-into-pdf.md)
- [Flatten PDF annotations in C# .NET](/guides/dotnet/annotations/flatten.md)
- [Import XFDF annotation data to PDFs in C# .NET](/guides/dotnet/annotations/import-xfdf.md)
- [Import XMP annotation data to PDF or image in C#](/guides/dotnet/annotations/import-xmp.md)
- [Instant JSON appearance theme comparison](/guides/dotnet/annotations/instant-json-appearance-theme-comparison.md)
- [PDF annotations in C#.NET](/guides/dotnet/annotations.md)
- [Remove PDF annotations in C# .NET](/guides/dotnet/annotations/remove.md)
- [Add PDF actions using C# in form fields](/guides/dotnet/annotations/pdf-actions-support.md)
- [Stamp a PDF document in C# .NET](/guides/dotnet/annotations/stamp-a-document.md)
- [XMP annotations in C# .NET](/guides/dotnet/annotations/xmp-annotations.md)