You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| ome_zarr_versions | List of OME-NGFF versions which are supported by the tool. When a Zarr group with multiscales metadata containing a version listed here is given to the tool, the tool promises to do something useful. However, it may not support every feature of the specification. |
100
-
| rfcs_supported | List of supported RFC numbers which have been implemented on top of the released OME-NGFF versions listed in ome_zarr_versions. Given test data produced for a given RFC listed here, the tool promises to do something useful. However, it may not support every feature of the RFC. |
101
-
| bioformats2raw_layout | A tool that advertises support for this will be able to open a Zarr that implements this transitional layout. |
102
-
| omero_metadata | A tool that advertises support for this will be able to open a Zarr that implements this transitional metadata, for example by defaulting channel colors with the provided color values. |
103
-
| labels | A tool that advertises support will open pixel-annotation metadata found in the "labels" group. |
104
-
| hcs_plates | A tool that advertises support will open high content screening datasets found in the "plate" group. |
97
+
Icons for canonical viewers are hosted in the [`public/icons/`](public/icons/) directory and served via GitHub Pages at:
where `{slug}` is the viewer name lowercased with spaces replaced by hyphens (e.g. `"OME-Zarr Validator"` → `ome-zarr-validator.png`). Consumers can derive this URL automatically and fall back to a local placeholder when the icon is unavailable.
104
+
105
+
The `logo` field in the `viewer` section is an optional override for cases where this convention does not apply.
106
+
107
+
## Canonical Manifests
108
+
109
+
This repository hosts canonical capability manifests for well-known OME-Zarr viewers in the [`manifests/`](manifests/) directory:
Consumers can load these manifests by URL directly from GitHub (raw content URLs) or host copies on their own infrastructure.
119
+
120
+
Viewer developers are encouraged to maintain their own manifests and submit PRs to update the canonical versions here when capabilities change.
121
+
122
+
## Manifest Schema (DRAFT)
123
+
124
+
A capability manifest is a YAML file with two top-level sections: `viewer` and `capabilities`.
125
+
126
+
### `viewer` Section
127
+
128
+
Identifies the tool and provides a URL template for launching it.
129
+
130
+
| Field | Type | Required | Description |
131
+
| --- | --- | --- | --- |
132
+
|`name`| string | yes | Human-readable name of the viewer |
133
+
|`version`| string | yes | Version of the viewer these capabilities describe |
134
+
|`repo`| string | no | URL of the source code repository |
135
+
|`logo`| string | no | URL to a logo image for the viewer. Optional override — consumers may derive a logo URL by convention (see [Icons](#icons)). Omit if the conventional path applies. |
136
+
|`template_url`| string | no | URL template for opening a dataset. Use `{DATA_URL}` as a placeholder for the dataset URL — consumers replace it at runtime with the actual OME-Zarr location |
Describes which OME-Zarr features the tool supports. All fields are optional — omitting a field means the capability is unknown/undeclared.
151
+
152
+
| Field | Type | Description |
153
+
| --- | --- | --- |
154
+
| `ome_zarr_versions` | number[] | OME-NGFF specification versions the tool can load (e.g. `[0.4, 0.5]`). When a dataset's multiscales metadata contains a version listed here, the tool should be able to open it. |
155
+
| `compression_codecs` | string[] | Compression codecs the tool can decode (e.g. `["blosc", "zstd", "gzip"]`). An empty array `[]` means the tool does not declare codec support — compatibility is unknown rather than unsupported. |
156
+
| `rfcs_supported` | number[] | RFC numbers implemented on top of the released OME-NGFF versions. Given test data for a listed RFC, the tool should handle it. |
157
+
| `axes` | boolean | Whether axis names and units from the metadata are respected |
158
+
| `scale` | boolean | Whether scaling factors on multiscale datasets are respected |
159
+
| `translation` | boolean | Whether translation offsets (including subpixel offsets for lower scale levels) are respected |
160
+
| `channels` | boolean | Whether the tool supports datasets with multiple channels (c axis) |
161
+
| `timepoints` | boolean | Whether the tool supports datasets with multiple timepoints (t axis) |
162
+
| `labels` | boolean | Whether pixel-annotation metadata in the "labels" group is loaded |
163
+
| `hcs_plates` | boolean | Whether high content screening datasets in the "plate" group are loaded |
164
+
| `bioformats2raw_layout` | boolean | Whether the tool can open Zarr stores using the bioformats2raw transitional layout |
165
+
| `omero_metadata` | boolean | Whether the tool uses OMERO metadata (e.g. to set default channel colors) |
166
+
167
+
Example:
168
+
169
+
```yaml
170
+
capabilities:
171
+
ome_zarr_versions: [0.4, 0.5]
172
+
compression_codecs: ["blosc", "zstd", "gzip"]
173
+
rfcs_supported: []
174
+
axes: true
175
+
scale: true
176
+
translation: true
177
+
channels: true
178
+
timepoints: true
179
+
labels: false
180
+
hcs_plates: false
181
+
bioformats2raw_layout: false
182
+
omero_metadata: true
183
+
```
184
+
185
+
### How `validateViewer()` Uses the Manifest
186
+
187
+
The `validateViewer()` function checks a manifest's declared capabilities against a dataset's `OmeZarrMetadata` and returns a `ValidationResult`:
188
+
189
+
```typescript
190
+
interface ValidationResult {
191
+
dataCompatible: boolean; // true if no errors (viewer can open the data)
192
+
dataFeaturesSupported: boolean; // true if no warnings (viewer fully supports all data features)
193
+
errors: ValidationError[]; // hard failures — data will not load
194
+
warnings: ValidationWarning[]; // soft issues — data loads but features may be missing
195
+
}
196
+
```
197
+
198
+
Capabilities fall into two levels:
199
+
200
+
- **Data compatibility** (`errors`): Hard requirements. If unmet, the viewer cannot open or render the data at all — it should not be shown.
201
+
- **Data support** (`warnings`): Soft requirements. If unmet, the viewer can still open the data but may not display certain features — it should still be shown, with warnings logged or surfaced to the user.
202
+
203
+
The checks performed, in order:
204
+
205
+
| Check | Metadata field | Manifest field | Level | Result if mismatch |
206
+
| --- | --- | --- | --- | --- |
207
+
| OME-Zarr version | `version` or `multiscales[0].version` | `ome_zarr_versions` | **Compatibility** | **Error** — viewer cannot load this version |
208
+
| Compression codec | `compressor.id` | `compression_codecs` | **Compatibility** | **Error** if codec not listed; **Warning** if viewer declares no codecs (unknown support) |
209
+
| Axes metadata | `axes` | `axes` | **Support** | **Warning** — axis names/units may be ignored |
210
+
| Channel support | `axes` contains c/channel | `channels` | **Support** | **Warning** — multi-channel data may not render correctly |
211
+
| Timepoint support | `axes` contains t/time | `timepoints` | **Support** | **Warning** — time-series data may not render correctly |
| OMERO metadata | `omero` present | `omero_metadata` | **Support** | **Warning** — channel colors etc. won't be applied |
215
+
| Scale transforms | `multiscales[].datasets[].coordinateTransformations` type `scale` | `scale` | **Support** | **Warning** — scaling factors may be ignored |
216
+
| Translation offsets | `multiscales[].datasets[].coordinateTransformations` type `translation` | `translation` | **Support** | **Warning** — coordinate offsets may be ignored |
217
+
| bioformats2raw layout | `bioformats2raw_layout` | `bioformats2raw_layout` | **Support** | **Warning** — layout may not be traversed correctly |
218
+
219
+
> **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.
220
+
221
+
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.
0 commit comments