@lde/iiif-validator 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # IIIF Validator
 
-Validates that a URL dereferences to a valid [IIIF Presentation](https://iiif.io/api/presentation/) Manifest. A small, dependency-light building block for Linked Data tooling that needs to tell a _declared_ IIIF manifest apart from one that actually resolves and parses.
+Validates that a URL dereferences to a valid [IIIF Presentation](https://iiif.io/api/presentation/) Manifest. A small building block for Linked Data tooling that needs to tell a _declared_ IIIF manifest apart from one that actually resolves, parses, and loads in a real viewer.
 
 ```ts
 import { validateManifest } from '@lde/iiif-validator';
@@ -22,15 +22,18 @@ interface ManifestValidation {
     | 'network-error'
     | 'http-error'
     | 'invalid-json'
-    | 'not-a-manifest';
+    | 'binary-content'
+    | 'not-a-manifest'
+    | 'does-not-load';
 }
 ```
 
 ## Behaviour
 
-- **Dereference over HTTP** with `Accept: application/ld+json, application/json`, following redirects, using the global `fetch` with an `AbortSignal` timeout (default 10 000 ms). Both are injectable via the options argument (`fetch`, `timeoutMs`).
-- **Lightweight, version-aware structural check.** A document is valid when the response is HTTP 2xx, the body parses as JSON, its `@context` references an IIIF Presentation context, and its `type`/`@type` indicates a manifest – accepting both v3 (`Manifest`) and v2 (`sc:Manifest`). The `@context` value may be a string, an array, or an object; all forms are handled. The version segment of the context is accepted version-agnostically.
-- **Strict failure semantics, no retries.** A timeout, network error, non-2xx status, unparseable body, missing IIIF `@context`, or wrong `type` all yield `valid: false` with the corresponding coarse `reason`. There is no deep JSON Schema validation and no dependency on the hosted IIIF Presentation Validator service.
+- **Dereference over HTTP** with `Accept: */*`, following redirects, using the global `fetch` with an `AbortSignal` timeout (default 10 000 ms). The wildcard mirrors what real IIIF viewers send (the browser `fetch` default); a JSON-specific `Accept` would be more correct but trips up hosts that do backwards content negotiation – serving the manifest to `*/*` while returning 404 for a JSON-specific request. Both `fetch` and `timeoutMs` are injectable via the options argument.
+- **Version-aware structural check.** A document is manifest-shaped when the response is HTTP 2xx, the body parses as JSON, its `@context` references an IIIF Presentation context, and its `type`/`@type` indicates a manifest – accepting both v3 (`Manifest`) and v2 (`sc:Manifest`). The `@context` value may be a string, an array, or an object; all forms are handled. The version segment of the context is accepted version-agnostically.
+- **Viewer-load gate.** Being manifest-shaped is not enough: a document can pass every structural check yet fail to load in the dominant Vault/`@iiif/parser`-based viewers (Mirador 4, Clover, Theseus), which eagerly upgrade every manifest to Presentation 3 and normalise the whole tree on load. A single structural slip – e.g. a `null` where an `AnnotationPage` belongs – crashes that pass, so the manifest renders in no such viewer. The validator reproduces that load path with `@iiif/parser` (`upgrade()` then `normalize()`); if it throws, the verdict is `does-not-load`. `upgrade()` is a no-op for v3, so this one path covers both v2 and v3. There are only two tiers – valid or invalid; cosmetic deviations that still load (a non-canonical `rights` URI, `image/jpg` instead of `image/jpeg`) stay valid.
+- **Strict failure semantics, no retries.** A timeout, network error, non-2xx status, unparseable body, binary media type, missing IIIF `@context`, wrong `type`, or a document that does not load all yield `valid: false` with the corresponding coarse `reason`. There is no deep JSON Schema validation and no dependency on the hosted IIIF Presentation Validator service.
 
 ## Options
 

package/dist/validateManifest.d.ts

@@ -3,7 +3,7 @@
  * *what kind* of failure occurred, not a detailed diagnosis — only enough to
  * tell apart an unreachable host from a malformed document.
  */
-export type ManifestValidationReason = 'valid-manifest' | 'timeout' | 'network-error' | 'http-error' | 'invalid-json' | 'binary-content' | 'not-a-manifest';
+export type ManifestValidationReason = 'valid-manifest' | 'timeout' | 'network-error' | 'http-error' | 'invalid-json' | 'binary-content' | 'not-a-manifest' | 'does-not-load';
 /**
  * Verdict returned by {@link validateManifest}.
  */

package/dist/validateManifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateManifest.d.ts","sourceRoot":"","sources":["../src/validateManifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,gBAAgB,GAChB,SAAS,GACT,eAAe,GACf,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,wBAAwB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAwC7B"}
+{"version":3,"file":"validateManifest.d.ts","sourceRoot":"","sources":["../src/validateManifest.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,gBAAgB,GAChB,SAAS,GACT,eAAe,GACf,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,wBAAwB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}

package/dist/validateManifest.js

@@ -1,3 +1,5 @@
+import { normalize } from '@iiif/parser/presentation-3';
+import { upgrade } from '@iiif/parser/upgrader';
 const IIIF_PRESENTATION_CONTEXT = 'iiif.io/api/presentation/';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /**
@@ -11,7 +13,13 @@ export async function validateManifest(url, options) {
     let response;
     try {
         response = await doFetch(url, {
-            headers: { Accept: 'application/ld+json, application/json' },
+            // Request with `Accept: */*`, matching what real IIIF viewers (Mirador,
+            // Universal Viewer) send via the browser `fetch` default. A more specific
+            // `application/ld+json` is technically correct, but some manifest hosts do
+            // backwards content negotiation: they serve the manifest to `*/*` yet 404
+            // a JSON-specific request. Asking for anything keeps the validator as
+            // permissive as the viewers whose access it stands in for.
+            headers: { Accept: '*/*' },
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
@@ -38,10 +46,34 @@ export async function validateManifest(url, options) {
     catch {
         return { valid: false, reason: 'invalid-json' };
     }
-    if (isPresentationManifest(body)) {
-        return { valid: true, reason: 'valid-manifest' };
+    if (!isPresentationManifest(body)) {
+        return { valid: false, reason: 'not-a-manifest' };
+    }
+    if (!loadsInViewer(body)) {
+        return { valid: false, reason: 'does-not-load' };
+    }
+    return { valid: true, reason: 'valid-manifest' };
+}
+/**
+ * Whether a manifest-shaped document survives the load path that real IIIF
+ * viewers run. The dominant Vault/`@iiif/parser`-based viewers (Mirador 4,
+ * Clover, Theseus) eagerly upgrade every manifest to Presentation 3 and
+ * normalise the whole tree on load; a structural deviation that crashes that
+ * pass — e.g. a `null` where an `AnnotationPage` belongs — makes the manifest
+ * fail to load even though it parses as JSON and is manifest-shaped. Running
+ * the same `upgrade()` then `normalize()` here reproduces that load: a throw
+ * from either step means no viewer would render it. `upgrade()` is
+ * version-agnostic (a no-op for documents already in v3), so this single path
+ * covers both v2 (`sc:Manifest`) and v3 documents.
+ */
+function loadsInViewer(body) {
+    try {
+        normalize(upgrade(body));
+        return true;
+    }
+    catch {
+        return false;
     }
-    return { valid: false, reason: 'not-a-manifest' };
 }
 /**
  * Whether a `Content-Type` header announces a binary media asset (image, audio

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/iiif-validator",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/iiif-validator"
@@ -24,6 +24,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
+    "@iiif/parser": "^2.2.10",
     "tslib": "^2.3.0"
   }
 }