IIIF Presentation 4 support

Author: stephenwf

README.md

@@ -7,6 +7,7 @@ npm i @iiif/parser
 This is a parser and set of low-level utilities for the following IIIF Specifications:
 
 - [IIIF Presentation 3](https://iiif.io/api/presentation/3.0/) (current)
+- [IIIF Presentation 4](https://preview.iiif.io/api/prezi-4/presentation/4.0/) (preview support via `/presentation-4`)
 - [IIIF Image 3](https://iiif.io/api/image/3.0/) (current)
 - [IIIF Presentation 2](https://iiif.io/api/presentation/2.1/)
 
@@ -16,8 +17,7 @@ These include:
 
 
 > [!NOTE]
-> A new version of the IIIF Presentation API is being developed (v4) which handles 3D content. This parser will
-> support this version soon. You can read about the additions [here](https://github.com/IIIF/3d/blob/main/temp-draft-4.md)
+> Presentation API v4 support is available from `@iiif/parser/presentation-4` and is designed for mixed v2.1/v3.0/v4.0 ingestion with a v4 normalization pipeline.
 
 ### Features
 The features of this library are focussed on encoding the structure of all types of IIIF and providing utilities for extracting data from the IIIF or converting it into another format that is easier to develop with. The aim of the parser is to maximize the IIIF compatibility of other tools built on top of it.
@@ -104,6 +104,35 @@ export type TraversalMap = {
 };
 ```
 
+#### IIIF Presentation 4
+
+- `upgradeToPresentation4()` to ingest v2.1, v3.0 or v4.0 into a v4-compatible shape
+- `Traverse` with v4 container support (`Timeline`, `Canvas`, `Scene`)
+- `normalize()` with deterministic ID minting for missing IDs
+- `validatePresentation4()` with traversal-first diagnostics (`tolerant` or `strict`)
+- `serializeConfigPresentation4` for native v4 output
+- `serializeConfigPresentation3` for strict v4→v3 downgrade (fails on unsupported v4-only constructs)
+- `pnpm run update-cookbook-v4` to refresh local `fixtures/cookbook-v4` from [preview cookbook v4](https://preview.iiif.io/cookbook/v4/)
+
+```ts
+import {
+  upgradeToPresentation4,
+  normalize,
+  validatePresentation4,
+  serialize,
+  serializeConfigPresentation4
+} from '@iiif/parser/presentation-4';
+
+const upgraded = upgradeToPresentation4(loadSomeManifest());
+const report = validatePresentation4(upgraded);
+const normalized = normalize(upgraded);
+const serialized = serialize(
+  { entities: normalized.entities, mapping: normalized.mapping, requests: {} },
+  normalized.resource,
+  serializeConfigPresentation4
+);
+```
+
 #### Image 3
 
 The Image 3 parser is adapted from an Image Server implementation, and supports:

__tests__/presentation-4-parser/cookbook.tests.ts

@@ -0,0 +1,42 @@
+import cookbookIndex from '../../fixtures/cookbook-v4/_index.json';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { cwd } from 'node:process';
+import { describe, expect, test } from 'vitest';
+import { normalize, serialize, serializeConfigPresentation4, validatePresentation4 } from '../../src/presentation-4';
+
+const { readFile } = fs;
+
+describe('Presentation 4 cookbook', function () {
+  const tests = Object.values(cookbookIndex as Record<string, { id: string; url: string }>).map((item) => [
+    item.id,
+    item.url,
+  ]);
+
+  test.each(tests)('Testing normalize %p (%p)', async (id: string, url: string) => {
+    const json = await readFile(join(cwd(), 'fixtures/cookbook-v4', `${id}.json`));
+    const manifest = JSON.parse(json.toString());
+    const original = JSON.parse(json.toString());
+    const normalized = normalize(manifest);
+
+    expect(normalized.resource.type).toBe(manifest.type);
+    expect(normalized.resource.id).toBe(manifest.id);
+
+    const report = validatePresentation4(manifest, { mode: 'tolerant' });
+    const errors = report.issues.filter((issue) => issue.severity === 'error');
+    expect(errors).toEqual([]);
+
+    const reserialized = serialize(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation4
+    ) as any;
+
+    expect(reserialized).toEqual(original);
+    expect(url).toEqual((cookbookIndex as any)[id].url);
+  });
+});

__tests__/presentation-4-parser/normalize.test.ts

@@ -0,0 +1,56 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cwd } from 'node:process';
+import { describe, expect, test } from 'vitest';
+import { normalize } from '../../src/presentation-4';
+
+const fixtureDir = join(cwd(), 'fixtures/presentation-4');
+const fixtureFiles = readdirSync(fixtureDir).filter((file) => file.endsWith('.json'));
+
+describe('presentation-4 normalize', () => {
+  test.each(fixtureFiles)('normalizes fixture %s', (fixtureName) => {
+    const fixture = JSON.parse(readFileSync(join(fixtureDir, fixtureName), 'utf8'));
+    const result = normalize(fixture);
+
+    expect(result.resource.type).toBe('Manifest');
+    expect(result.entities.Manifest[result.resource.id]).toBeTruthy();
+    expect(Object.keys(result.mapping).length).toBeGreaterThan(1);
+  });
+
+  test('mints deterministic ids for missing resources in tolerant mode', () => {
+    const input = {
+      '@context': 'http://iiif.io/api/presentation/4/context.json',
+      type: 'Manifest',
+      label: { en: ['No IDs'] },
+      items: [
+        {
+          type: 'Timeline',
+          duration: 15.5,
+          items: [
+            {
+              type: 'AnnotationPage',
+              items: [
+                {
+                  type: 'Annotation',
+                  motivation: 'painting',
+                  body: {
+                    type: 'Sound',
+                    id: 'https://example.org/audio.mp3',
+                    format: 'audio/mp3',
+                  },
+                  target: 'https://example.org/timeline/1',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = normalize(input as any);
+
+    expect(result.resource.id.startsWith('vault://iiif-parser/v4/Manifest/')).toBe(true);
+    expect(result.diagnostics.some((diagnostic) => diagnostic.code === 'minted-id')).toBe(true);
+    expect(Object.keys(result.entities.Timeline).length).toBe(1);
+  });
+});

__tests__/presentation-4-parser/performance.test.ts

@@ -0,0 +1,127 @@
+import { performance } from 'node:perf_hooks';
+import { describe, expect, test } from 'vitest';
+import { normalize, serialize, serializeConfigPresentation4, validatePresentation4 } from '../../src/presentation-4';
+
+function createLargeCanvasManifest(canvasCount = 200, annotationsPerCanvas = 4) {
+  return {
+    '@context': 'http://iiif.io/api/presentation/4/context.json',
+    id: 'https://example.org/iiif/perf/canvas-manifest',
+    type: 'Manifest',
+    label: { en: ['Large canvas manifest'] },
+    items: Array.from({ length: canvasCount }).map((_, canvasIndex) => ({
+      id: `https://example.org/iiif/perf/canvas/${canvasIndex + 1}`,
+      type: 'Canvas',
+      width: 4000,
+      height: 3000,
+      items: [
+        {
+          id: `https://example.org/iiif/perf/canvas/${canvasIndex + 1}/page/1`,
+          type: 'AnnotationPage',
+          items: Array.from({ length: annotationsPerCanvas }).map((__, annotationIndex) => ({
+            id: `https://example.org/iiif/perf/canvas/${canvasIndex + 1}/annotation/${annotationIndex + 1}`,
+            type: 'Annotation',
+            motivation: ['painting'],
+            body: [
+              {
+                id: `https://example.org/iiif/perf/image/${canvasIndex + 1}-${annotationIndex + 1}.jpg`,
+                type: 'Image',
+                format: 'image/jpeg',
+              },
+            ],
+            target: [
+              {
+                id: `https://example.org/iiif/perf/canvas/${canvasIndex + 1}`,
+                type: 'Canvas',
+              },
+            ],
+          })),
+        },
+      ],
+    })),
+  };
+}
+
+function createLargeSceneManifest(sceneCount = 120, modelsPerScene = 3) {
+  return {
+    '@context': 'http://iiif.io/api/presentation/4/context.json',
+    id: 'https://example.org/iiif/perf/scene-manifest',
+    type: 'Manifest',
+    label: { en: ['Large scene manifest'] },
+    items: Array.from({ length: sceneCount }).map((_, sceneIndex) => ({
+      id: `https://example.org/iiif/perf/scene/${sceneIndex + 1}`,
+      type: 'Scene',
+      items: [
+        {
+          id: `https://example.org/iiif/perf/scene/${sceneIndex + 1}/page/1`,
+          type: 'AnnotationPage',
+          items: Array.from({ length: modelsPerScene }).map((__, modelIndex) => ({
+            id: `https://example.org/iiif/perf/scene/${sceneIndex + 1}/annotation/${modelIndex + 1}`,
+            type: 'Annotation',
+            motivation: ['painting'],
+            body: [
+              {
+                id: `https://example.org/iiif/perf/model/${sceneIndex + 1}-${modelIndex + 1}.glb`,
+                type: 'Model',
+                format: 'model/gltf-binary',
+              },
+            ],
+            target: [
+              {
+                id: `https://example.org/iiif/perf/scene/${sceneIndex + 1}`,
+                type: 'Scene',
+              },
+            ],
+          })),
+        },
+      ],
+    })),
+  };
+}
+
+describe('presentation-4 performance scale tests', () => {
+  test('normalizes and serializes large canvas manifests', () => {
+    const manifest = createLargeCanvasManifest();
+    const started = performance.now();
+    const normalized = normalize(manifest);
+    const serialized = serialize<any>(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation4
+    );
+    const report = validatePresentation4(manifest, { mode: 'tolerant' });
+    const elapsed = performance.now() - started;
+
+    expect(report.valid).toBe(true);
+    expect(normalized.resource.type).toBe('Manifest');
+    expect(serialized.id).toBe(manifest.id);
+    expect(Object.keys(normalized.mapping).length).toBeGreaterThan(1500);
+    expect(elapsed).toBeLessThan(20000);
+  });
+
+  test('normalizes and serializes large scene manifests', () => {
+    const manifest = createLargeSceneManifest();
+    const started = performance.now();
+    const normalized = normalize(manifest);
+    const serialized = serialize<any>(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation4
+    );
+    const report = validatePresentation4(manifest, { mode: 'tolerant' });
+    const elapsed = performance.now() - started;
+
+    expect(report.valid).toBe(true);
+    expect(normalized.resource.type).toBe('Manifest');
+    expect(serialized.id).toBe(manifest.id);
+    expect(Object.keys(normalized.entities.Scene).length).toBe(120);
+    expect(elapsed).toBeLessThan(20000);
+  });
+});