fix: classify Zarr v3 codecs so structural codecs don't hide viewers

The v3 path treated every codecs[].name as a compression codec, so the always-present bytes serialization codec made viewers with a real codec allowlist (e.g. Neuroglancer) falsely incompatible. Add classifyCodec and compare only compression codecs against compression_codecs; ignore structural codecs; warn (not error) on unrecognized codecs.

Author: allison-truhlar

README.md

@@ -205,7 +205,7 @@ The checks performed, in order:
 | Check | Metadata field | Manifest field | Level | Result if mismatch |
 | --- | --- | --- | --- | --- |
 | OME-Zarr version | `version` or `multiscales[0].version` | `ome_zarr_versions` | **Compatibility** | **Error** — viewer cannot load this version |
-| Compression codec | `compressor.id` | `compression_codecs` | **Compatibility** | **Error** if codec not listed; **Warning** if viewer declares no codecs (unknown support) |
+| Compression codec | `compressor.id` (Zarr v2) or compression codecs in `codecs[]` (Zarr v3) | `compression_codecs` | **Compatibility** | **Error** if codec not listed; **Warning** if viewer declares no codecs (unknown support) |
 | Axes metadata | `axes` | `axes` | **Support** | **Warning** — axis names/units may be ignored |
 | Channel support | `axes` contains c/channel | `channels` | **Support** | **Warning** — multi-channel data may not render correctly |
 | Timepoint support | `axes` contains t/time | `timepoints` | **Support** | **Warning** — time-series data may not render correctly |
@@ -216,6 +216,8 @@ The checks performed, in order:
 | Translation offsets | `multiscales[].datasets[].coordinateTransformations` type `translation` | `translation` | **Support** | **Warning** — coordinate offsets may be ignored |
 | bioformats2raw layout | `bioformats2raw_layout` | `bioformats2raw_layout` | **Support** | **Warning** — layout may not be traversed correctly |
 
+> **Note on Zarr v3 codecs:** A Zarr v3 array declares an ordered codec pipeline (`codecs[]`) containing array_to_array transforms (e.g. `transpose`), an array_to_bytes serialization codec (`bytes`, `sharding_indexed` — always present), and bytes_to_bytes codecs (compression such as `blosc`/`zstd`, plus checksums such as `crc32c`). Only the *compression* codecs are compared against `compression_codecs`; serialization, transform, and checksum codecs are ignored. An unrecognized codec produces a **Warning** (compatibility unknown) rather than an error, so a novel codec never silently hides a viewer. See `classifyCodec`.
+
 > **Note on `rfcs_supported`:** Although `rfcs_supported` is a hard compatibility requirement (it determines whether a viewer can parse RFC-mandated metadata structures), no validation check is currently implemented. OME-NGFF metadata does not yet expose which RFCs a dataset requires — this is a spec-level gap. When the spec defines a `rfcs_required` field, the validator will compare it against `viewer.capabilities.rfcs_supported` and produce an error on mismatch.
 
 A viewer is considered **data-compatible** (`dataCompatible: true`) when there are zero errors — it should be shown to the user. `dataFeaturesSupported` is `false` when there are warnings, indicating the viewer can open the data but may not display all features.

src/codecs.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { classifyCodec } from './codecs.js';
+
+describe('classifyCodec', () => {
+  describe('compression codecs', () => {
+    it.each(['blosc', 'gzip', 'zstd', 'lz4', 'lzma', 'zlib'])(
+      'classifies %s as compression',
+      (name) => {
+        expect(classifyCodec(name)).toBe('compression');
+      }
+    );
+
+    it('classifies numcodecs-namespaced compressors as compression', () => {
+      expect(classifyCodec('numcodecs.blosc')).toBe('compression');
+      expect(classifyCodec('numcodecs.zstd')).toBe('compression');
+    });
+  });
+
+  describe('structural codecs', () => {
+    it.each(['bytes', 'endian', 'transpose', 'sharding_indexed', 'crc32c'])(
+      'classifies %s as structural',
+      (name) => {
+        expect(classifyCodec(name)).toBe('structural');
+      }
+    );
+  });
+
+  describe('unknown codecs', () => {
+    it('classifies an unrecognized codec name as unknown', () => {
+      expect(classifyCodec('some-future-codec')).toBe('unknown');
+    });
+  });
+});

src/codecs.ts

@@ -0,0 +1,77 @@
+/**
+ * Zarr codec classification, dependency-free so it stays portable alongside the
+ * canonical OME-Zarr metadata types in `omezarr.ts`.
+ *
+ * A Zarr v3 array declares an ordered codec pipeline (`codecs[]`) made up of
+ * three transform kinds (per the Zarr v3 spec):
+ *   - array_to_array  e.g. transpose
+ *   - array_to_bytes  serialization; exactly one required, e.g. bytes,
+ *                     sharding_indexed
+ *   - bytes_to_bytes  e.g. blosc, gzip, zstd (compression) and crc32c (checksum)
+ *
+ * Only *compression* codecs determine whether a viewer can read the data: a
+ * viewer that cannot decompress the bytes cannot open the dataset. Serialization
+ * codecs, transposes, and checksums are not compression and must not be compared
+ * against a viewer's declared `compression_codecs` (doing so is the original
+ * false-incompatible bug — every v3 array carries a `bytes` serialization codec).
+ *
+ * Zarr v2 is simpler: a single `compressor.id` that is always an actual
+ * compression codec, so it does not need classification.
+ */
+
+/** Classification of a codec for compression-compatibility purposes. */
+export type CodecCompression = "compression" | "structural" | "unknown";
+
+/**
+ * Codecs that compress data. A viewer must be able to decompress these to read
+ * the dataset, so they are compared against the viewer's `compression_codecs`.
+ * Both the bare Zarr v3 names and the `numcodecs.*`-namespaced variants emitted
+ * by some writers are recognized.
+ */
+const COMPRESSION_CODECS = new Set([
+  "blosc",
+  "gzip",
+  "zstd",
+  "lz4",
+  "lzma",
+  "zlib",
+  "numcodecs.blosc",
+  "numcodecs.gzip",
+  "numcodecs.zstd",
+  "numcodecs.lz4",
+  "numcodecs.lzma",
+  "numcodecs.zlib",
+]);
+
+/**
+ * Codecs that do not compress data: array_to_array transforms (transpose,
+ * bitround), array_to_bytes serialization codecs (bytes, sharding_indexed,
+ * vlen-utf8, json2), and bytes_to_bytes checksums (crc32c). A viewer does not
+ * need to declare support for these to read compressed data, so they are not
+ * compared against `compression_codecs`. Kept in sync with zarrita's codec
+ * registry by codecs.zarrita.test.ts.
+ */
+const STRUCTURAL_CODECS = new Set([
+  "bytes",
+  "endian", // legacy name for the array_to_bytes codec
+  "transpose",
+  "sharding_indexed",
+  "crc32c",
+  "vlen-utf8",
+  "json2",
+  "bitround",
+]);
+
+/**
+ * Classify a Zarr codec by its relevance to compression compatibility.
+ *
+ * Returns `"unknown"` for any codec not in the static registries above, so the
+ * caller can surface uncertainty (a warning) rather than guess — guessing
+ * "compression" re-introduces the false-incompatible bug for novel serialization
+ * codecs, while guessing "structural" silently hides genuine incompatibility.
+ */
+export function classifyCodec(name: string): CodecCompression {
+  if (COMPRESSION_CODECS.has(name)) return "compression";
+  if (STRUCTURAL_CODECS.has(name)) return "structural";
+  return "unknown";
+}

src/index.ts

@@ -65,6 +65,10 @@ export { validateViewer, isCompatible } from "./validator.js";
 // Re-export logo utility
 export { getLogoUrl } from "./logo.js";
 
+// Re-export codec classification
+export { classifyCodec } from "./codecs.js";
+export type { CodecCompression } from "./codecs.js";
+
 // Re-export types for consumers
 export type {
   ViewerManifest,

src/validator.test.ts

@@ -207,6 +207,69 @@ describe('validateViewer', () => {
       expect(result.warnings[0].message).toContain('compatibility unknown');
     });
 
+    it('is compatible when v3 data uses only a structural serialization codec', () => {
+      // Regression: every Zarr v3 array carries a `bytes` (array_to_bytes)
+      // serialization codec. It must not be compared against the viewer's
+      // compression codec list, or every real v3 dataset hides such viewers.
+      const viewer = createViewer({
+        ome_zarr_versions: [0.4, 0.5],
+        compression_codecs: ['blosc', 'zstd', 'zlib', 'lz4', 'gzip']
+      });
+      const metadata = createMetadata({
+        version: '0.5',
+        codecs: [{ name: 'bytes' }]
+      });
+
+      const result = validateViewer(viewer, metadata);
+
+      expect(result.dataCompatible).toBe(true);
+      expect(result.errors).toHaveLength(0);
+      expect(result.warnings.filter(w => w.capability === 'compression_codecs')).toHaveLength(0);
+    });
+
+    it('ignores structural codecs when checking a supported compression codec', () => {
+      const viewer = createViewer({ ome_zarr_versions: [0.4, 0.5], compression_codecs: ['blosc'] });
+      const metadata = createMetadata({
+        version: '0.5',
+        codecs: [{ name: 'transpose' }, { name: 'bytes' }, { name: 'blosc' }, { name: 'crc32c' }]
+      });
+
+      const result = validateViewer(viewer, metadata);
+
+      expect(result.dataCompatible).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('warns but stays compatible when data uses an unrecognized codec the viewer does not list', () => {
+      const viewer = createViewer({ ome_zarr_versions: [0.4, 0.5], compression_codecs: ['blosc'] });
+      const metadata = createMetadata({
+        version: '0.5',
+        codecs: [{ name: 'bytes' }, { name: 'some-future-codec' }]
+      });
+
+      const result = validateViewer(viewer, metadata);
+
+      expect(result.dataCompatible).toBe(true);
+      expect(result.errors).toHaveLength(0);
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings[0].capability).toBe('compression_codecs');
+      expect(result.warnings[0].message).toContain('some-future-codec');
+      expect(result.warnings[0].message).toContain('compatibility unknown');
+    });
+
+    it('does not warn for an unrecognized codec the viewer explicitly lists', () => {
+      const viewer = createViewer({ ome_zarr_versions: [0.4, 0.5], compression_codecs: ['blosc', 'some-future-codec'] });
+      const metadata = createMetadata({
+        version: '0.5',
+        codecs: [{ name: 'bytes' }, { name: 'some-future-codec' }]
+      });
+
+      const result = validateViewer(viewer, metadata);
+
+      expect(result.dataCompatible).toBe(true);
+      expect(result.warnings.filter(w => w.capability === 'compression_codecs')).toHaveLength(0);
+    });
+
     it('returns warning when viewer has empty codec list but data uses compression', () => {
       const viewer = createViewer({ compression_codecs: [] });
       const metadata = createMetadata({ compressor: { id: 'blosc' } });

src/validator.ts

@@ -6,6 +6,7 @@ import type {
   ValidationError,
   ValidationWarning,
 } from "./types.js";
+import { classifyCodec } from "./codecs.js";
 
 function hasTransformationType(
   multiscales: MultiscaleMetadata[],
@@ -75,27 +76,42 @@ export function validateViewer(
     });
   }
 
-  // Collect codecs from Zarr v2 (compressor.id) or Zarr v3 (codecs[].name)
-  const dataCodecs: string[] = [];
+  // Collect the codecs the viewer must be able to decompress. Zarr v2 exposes a
+  // single compressor via compressor.id (always an actual compression codec);
+  // Zarr v3 exposes an ordered pipeline via codecs[] that also contains
+  // serialization codecs, transforms, and checksums, which must NOT be compared
+  // against the viewer's compression codec list. See classifyCodec().
+  const compressionCodecs: string[] = [];
+  const unknownCodecs: string[] = [];
   if (metadata.compressor?.id) {
-    dataCodecs.push(metadata.compressor.id);
-  } else if (metadata.codecs && metadata.codecs.length > 0) {
-    dataCodecs.push(...metadata.codecs.map((c) => c.name));
+    compressionCodecs.push(metadata.compressor.id);
+  } else if (metadata.codecs) {
+    for (const codec of metadata.codecs) {
+      switch (classifyCodec(codec.name)) {
+        case "compression":
+          compressionCodecs.push(codec.name);
+          break;
+        case "unknown":
+          unknownCodecs.push(codec.name);
+          break;
+        // "structural" codecs are not relevant to compression compatibility.
+      }
+    }
   }
 
-  if (dataCodecs.length > 0) {
+  if (compressionCodecs.length > 0) {
     if (
       !viewer.capabilities.compression_codecs ||
       viewer.capabilities.compression_codecs.length === 0
     ) {
       // Viewer doesn't declare codec support - can't guarantee compatibility
-      const codecList = dataCodecs.join("', '");
+      const codecList = compressionCodecs.join("', '");
       warnings.push({
         capability: "compression_codecs",
         message: `Data uses codec '${codecList}' but viewer doesn't declare codec support - compatibility unknown`,
       });
     } else {
-      for (const codec of dataCodecs) {
+      for (const codec of compressionCodecs) {
         if (!viewer.capabilities.compression_codecs.includes(codec)) {
           errors.push({
             capability: "compression_codecs",
@@ -108,6 +124,18 @@ export function validateViewer(
     }
   }
 
+  // Codecs we cannot classify can be neither confirmed compatible nor ruled
+  // incompatible. Warn (rather than error) unless the viewer explicitly lists
+  // the codec, so a novel codec never silently hides a viewer or passes as fine.
+  for (const codec of unknownCodecs) {
+    if (!viewer.capabilities.compression_codecs?.includes(codec)) {
+      warnings.push({
+        capability: "compression_codecs",
+        message: `Data uses unrecognized codec '${codec}' - compatibility unknown`,
+      });
+    }
+  }
+
   // TODO: Check rfcs_supported (hard compatibility requirement)
   // Blocker: OME-NGFF metadata does not expose which RFCs a dataset requires.
   // After determing how to implement this check, compare metadata.rfcs_required against

tsconfig.lib.json

@@ -13,7 +13,8 @@
     "src/validator.ts",
     "src/logo.ts",
     "src/types.ts",
-    "src/omezarr.ts"
+    "src/omezarr.ts",
+    "src/codecs.ts"
   ],
   "exclude": ["src/app.ts"]
 }