✨ Support XMP fragments in document definition

XMP metadata is used in PDFs for various purposes, including declaring
conformance to standards like PDF/A. Adding custom XMP metadata is
already supported by `pdf-core` but was not yet exposed in this library.

This commit adds first-class support for XMP fragments in the document
definition. Consumers can now provide an `xmpFragments` array of objects
with `namespaceUri`, `prefix`, and `unsafeInnerXML` properties to
`DocumentDefinition`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ralfstx

CHANGELOG.md

@@ -8,6 +8,9 @@
   output intents (e.g. for PDF/A or PDF/X conformance). Accepts raw ICC
   profile data as `Uint8Array`, removing the need for consumers to
   depend on `@ralfstx/pdf-core`.
+- `xmpFragments` property on `DocumentDefinition` for merging custom
+  XMP metadata into the document's auto-generated XMP. This is needed
+  e.g. for declaring PDF/A conformance level alongside output intents.
 
 ## [0.6.1] - 2026-03-08
 

src/api/document.ts

@@ -89,6 +89,13 @@ export type DocumentDefinition = {
    */
   outputIntents?: OutputIntent[];
 
+  /**
+   * Custom XMP metadata fragments to merge into the document's
+   * auto-generated XMP metadata. Each fragment declares a namespace
+   * and provides raw XML content for that namespace.
+   */
+  xmpFragments?: XmpFragment[];
+
   dev?: {
     /**
      * When set to true, additional guides are drawn to help analyzing
@@ -273,3 +280,25 @@ export type OutputIntent = {
    */
   info?: string;
 };
+
+/**
+ * A fragment of XMP metadata scoped to a single namespace, to be
+ * merged into the document's auto-generated XMP.
+ */
+export type XmpFragment = {
+  /**
+   * The namespace URI (e.g. `'http://www.aiim.org/pdfa/ns/id/'`).
+   */
+  namespaceUri: string;
+
+  /**
+   * The namespace prefix used in the XML content (e.g. `'pdfaid'`).
+   */
+  prefix: string;
+
+  /**
+   * Raw XML content to place inside the `rdf:Description` element.
+   * The caller is responsible for ensuring the XML is well-formed.
+   */
+  unsafeInnerXML: string;
+};

src/read/read-document.test.ts

@@ -286,6 +286,58 @@ describe('readDocumentDefinition', () => {
       );
     });
   });
+
+  describe('xmpFragments', () => {
+    it('accepts valid xmpFragments', () => {
+      const xmpFragments = [
+        {
+          namespaceUri: 'http://www.aiim.org/pdfa/ns/id/',
+          prefix: 'pdfaid',
+          unsafeInnerXML: '<pdfaid:part>3</pdfaid:part>',
+        },
+      ];
+
+      const def = readDocumentDefinition({ ...input, xmpFragments });
+
+      expect(def.xmpFragments).toEqual(xmpFragments);
+    });
+
+    it('checks namespaceUri is required', () => {
+      const xmpFragments = [{ prefix: 'pdfaid', unsafeInnerXML: '<pdfaid:part>3</pdfaid:part>' }];
+
+      expect(() => readDocumentDefinition({ ...input, xmpFragments })).toThrow(
+        /Missing value for "namespaceUri"/,
+      );
+    });
+
+    it('checks prefix is required', () => {
+      const xmpFragments = [
+        { namespaceUri: 'http://example.com/', unsafeInnerXML: '<x:y>1</x:y>' },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, xmpFragments })).toThrow(
+        /Missing value for "prefix"/,
+      );
+    });
+
+    it('checks unsafeInnerXML is required', () => {
+      const xmpFragments = [{ namespaceUri: 'http://example.com/', prefix: 'x' }];
+
+      expect(() => readDocumentDefinition({ ...input, xmpFragments })).toThrow(
+        /Missing value for "unsafeInnerXML"/,
+      );
+    });
+
+    it('rejects non-string values', () => {
+      const xmpFragments = [
+        { namespaceUri: 123, prefix: 'pdfaid', unsafeInnerXML: '<pdfaid:part>3</pdfaid:part>' },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, xmpFragments })).toThrow(
+        /Invalid value for "xmpFragments\/0\/namespaceUri"/,
+      );
+    });
+  });
 });
 
 function mkIccProfile(colorSpace = 'RGB '): Uint8Array {

src/read/read-document.ts

@@ -46,6 +46,11 @@ export type DocumentDefinition = {
     registryName?: string;
     info?: string;
   }[];
+  xmpFragments?: {
+    namespaceUri: string;
+    prefix: string;
+    unsafeInnerXML: string;
+  }[];
   onRenderDocument?: (pdfDoc: PDFDocument) => void | Promise<void>;
 };
 
@@ -77,6 +82,7 @@ export function readDocumentDefinition(input: unknown): DocumentDefinition {
     customData: optional(readCustomData),
     embeddedFiles: optional(types.array(readEmbeddedFiles)),
     outputIntents: optional(types.array(readOutputIntent)),
+    xmpFragments: optional(types.array(readXmpFragment)),
     onRenderDocument: optional(),
   });
   if (def1.language && !def1.defaultStyle?.language) {
@@ -199,3 +205,11 @@ function readIccProfile(input: unknown): Uint8Array {
   }
   return input;
 }
+
+function readXmpFragment(input: unknown) {
+  return readObject(input, {
+    namespaceUri: required(types.string()),
+    prefix: required(types.string()),
+    unsafeInnerXML: required(types.string()),
+  });
+}

src/render/render-document.test.ts

@@ -158,4 +158,25 @@ describe('renderDocument', () => {
     expect(dataString).toMatch(/\/Info <FEFF/);
     expect(dataString).toMatch(/\/DestOutputProfile/);
   });
+
+  it('renders XMP fragments', async () => {
+    const def = {
+      content: [],
+      xmpFragments: [
+        {
+          namespaceUri: 'http://www.aiim.org/pdfa/ns/id/',
+          prefix: 'pdfaid',
+          unsafeInnerXML:
+            '<pdfaid:part>3</pdfaid:part>\n<pdfaid:conformance>B</pdfaid:conformance>',
+        },
+      ],
+    };
+
+    const pdfData = await renderDocument(def, [], noObjectStreams);
+    const dataString = new TextDecoder().decode(pdfData);
+
+    expect(dataString).toContain('pdfaid:part');
+    expect(dataString).toContain('pdfaid:conformance');
+    expect(dataString).toContain('http://www.aiim.org/pdfa/ns/id/');
+  });
 });

src/render/render-document.ts

@@ -43,6 +43,10 @@ export async function renderDocument(
     });
   }
 
+  for (const fragment of def.xmpFragments ?? []) {
+    pdfDoc.addXMPFragment(fragment);
+  }
+
   await def.onRenderDocument?.(pdfDoc);
 
   return pdfDoc.write(writeOptions);