From 08df0218c28bde14a2aae3f43f5d9b4fc096b306 Mon Sep 17 00:00:00 2001 From: Norman Rzepka Date: Mon, 16 Nov 2026 13:13:27 +0100 Subject: [PATCH] RFC-8: revision 2 Update the RFC-8 text with the revisions developed in https://github.com/ome/ngff-rfc8-revisions. Co-Authored-By: Claude Opus 5.5 --- rfc/8/index.md | 1702 ++++++++++++++++++++++++++++-------------------- 1 file changed, 993 insertions(+), 709 deletions(-) diff --git a/rfc/8/index.md b/rfc/8/index.md index 8c7a3c99..cb0f055b 100644 --- a/rfc/8/index.md +++ b/rfc/8/index.md @@ -35,6 +35,21 @@ authors: affiliation: German BioImaging e.V. role: Co-author date: "2025-10-28" + - name: Damien Goutte-Gattat + github: gouttegd + affiliation: German BioImaging e.V. + role: Co-author + date: "2026-10-22" + - name: Draga Doncila Pop + github: DragaDoncila + affiliation: Image Cooperative + role: Co-author + date: "2026-11-10" + - name: Juan Nunez-Iglesias + github: jni + affiliation: Image Cooperative + role: Co-author + date: "2026-11-10" manual_status: R1 description: Collections date: "2026-06-03" @@ -69,7 +84,7 @@ reading this paragraph(s). This proposal introduces a general extensibility mechanism for OME-Zarr metadata. It defines a common Node interface, a system for referencing nodes -locally and remotely, and a naming scheme that allows OME-Zarr to be extended +locally and remotely, and an extension scheme that allows OME-Zarr to be extended with new node types and metadata while maintaining interoperability. The mechanism also provides a general way to represent collections: groups of @@ -167,15 +182,16 @@ illustrating individual aspects of the proposal, e.g.: "ome": { "version": "0.x", "type": "multiscale", + "id": "000001", "name": "our_first_example", - "nodes": [ + "data": [ { - "id": "s0", "name": "s0", - "type": "singlescale", + "type": "array", "path": { "type": "zarr", - "path": "./s0" + "format": "relative", + "href": "./s0" }, } ] @@ -186,10 +202,29 @@ illustrating individual aspects of the proposal, e.g.: More complete examples showing how these components can be combined to support the use cases described in the Background are provided later in the document. +### Features deferred to subsequent sub-RFC + +This RFC will defer the definition of some features to forthcoming sub-RFCs. +In doing so, we aim to help reviewers focus on providing feedback on the core building being defined in this RFC. +In parallel to the review of RFC-8, we will author sub-RFCs for each deferred feature that propose how they will be expressed using the core RFC-8 building blocks. +As we iterate on the design of RFC-8, we will update the sub-RFCs. +All deferred features will be proposed and evaluated via the RFC process before the v1.0 specification is released. + +The following features are being deferred to sub-RFCs: + +| Topic | Scope | +|---|---| +| **HCS** | Plate and well traits | +| **Labels** | Label image traits and per-label properties | +| **bioformats2raw and OME-XML** | Series layout and the OME/METADATA.ome.xml mapping | +| **Absolute and remote references** | Absolute paths and URLs, authentication and security | +| **snake_case** | Making keys and identifiers consistent with Zarr | +| **Legacy multiscales** | A `legacy_multiscale` node type for unchanged 0.5 and 0.6 images | +| **Singlescale images** | A node type for images with a single resolution level. | ### Building blocks -The building blocks define how objects are represented using paths and references. +The building blocks define how objects are represented using paths, declarations and references. (rfcs:rfc8:path-interface)= #### `Path` interface @@ -206,7 +241,8 @@ used to build up the definition of an image. ```jsonc "path": { "type": "zarr", - "path": "./s0" + "format": "relative", + "href": "./s0" } ``` @@ -216,7 +252,8 @@ used to build up the definition of an image. | Field | Type | Required? | Notes | | - | - | - | - | | `"type"` | string | yes | Value MUST be a valid path type. | -| `"path"` | string | yes | Value MUST be a string containing a path. See below. | +| `"format"` | string | yes | Value MUST be a valid path format. See below. | +| `"href"` | string | yes | Value MUST be a string containing a path in the declared `format`. See below. | (rfcs:rfc8:path-interface-field-type)= ##### Field: `type` @@ -230,55 +267,145 @@ The `type` field of a `Path` object defines how the path is interpreted. This RF The `type` field of a `Path` object is an extension point. For detail on how to extend the `type` field with new values, see [Extensions](#extensions). -(rfcs:rfc8:path-interface-field-path)= -##### Field: `path` +(rfcs:rfc8:path-interface-field-format)= +##### Field: `format` + +The `format` field of a `Path` object declares how the `href` string is to be interpreted. +Implementations MUST use the `format` field to interpret the `href` and MUST NOT infer the format from the `href` string itself (e.g. from a `file://` or `https://` prefix). + +The following path formats are defined: + +| Format | Defined in | Description | +| - | - | - | +| `"relative"` | this RFC | A path relative to the metadata document that contains the `Path` object. | + +Only `relative` is a core path format of this RFC. +Implementations that do not support the declared `format` MUST NOT attempt to resolve the path and SHOULD treat the referenced node as unavailable. + +Future RFCs may propose additional path formats, such as S3 URLs or chained paths (e.g. for referencing files within a zip file). + +(rfcs:rfc8:path-interface-field-href)= +##### Field: `href` -The `path` string can be one of the following types: +The `href` string locates the referenced document in the declared `format`. +This RFC defines the rules for `href` values with the `relative` format only. -- **Relative paths.** - To reference nodes that are on the same file system namespace as the json file describing the collection, relative paths may be used. - Relative paths are interpreted relative to the json file describing the collection. - Relative paths follow the relative path notation defined in [IETF RFC1808](https://datatracker.ietf.org/doc/html/rfc1808). +- Relative paths are resolved from the location of the metadata document that contains the `Path` object, + i.e. from the Zarr group whose `zarr.json` contains it, or from the directory of the standalone JSON file that contains it. +- Relative paths follow the relative path notation defined in [IETF RFC1808](https://datatracker.ietf.org/doc/html/rfc1808). Briefly, `.` and `..` are used to navigate the hierarchy and the hierarchy is separated by `/`. - Relative paths may be used for data stored on traditional file systems as well as other storage protocols, such as HTTP or S3. - Examples: - - `./image.ome.zarr` - - `../image.ome.zarr` -- **Absolute file paths.** - On traditional file systems, absolute paths may be used with the `file` scheme as specified by [IETF RFC8089](https://datatracker.ietf.org/doc/html/rfc8089). - Please note that absolute file paths are generally not portable across operating systems or file systems. - Examples: - - `file:///home/user/data/image.ome.zarr` - - `file://C:/Users/user/data/image.ome.zarr` -- **HTTP(S) URLs.** - To reference nodes that are stored remotely, URLs with the `http` or `https` scheme may be used. - URLs follow the notation defined in [IETF RFC1738](https://datatracker.ietf.org/doc/html/rfc1738). - Examples: - - `https://example.com/image.ome.zarr` - - `http://example.com/image.ome.zarr` - -Future RFCs may propose additional path types, such as S3 URLs or chained paths (e.g. for referencing files within a zip file). +- Relative paths may be used for data stored on traditional file systems as well as other storage protocols, such as HTTP or S3. + The storage protocol is determined by how the containing document was accessed, not by the `href`. + +Examples: +- `./image.ome.zarr` +- `../image.ome.zarr` +- `./registered/em.ome.zarr` +- `s0` + See the [Security](#security) section for guidance on access restrictions. +(rfcs:rfc8:path-interface-resolution)= +##### Path resolution + +Resolving a node's `path` means loading the document it locates, and, if the root node of that document has child nodes with a `path`, resolving those in turn. +Resolving node paths MUST NOT form a cycle: a node's `path` MUST NOT resolve to a document that contains that node, directly or through a chain of other node paths. +Implementations MUST detect cycles and MUST stop resolving and report an error when they encounter one. + +This rule applies to the `path` fields of nodes. +The `path` field of a [`Reference`](#reference-interface) only locates the document that contains the referenced object and MAY point back to an enclosing document, e.g. from a resolution level to the coordinate systems of its multiscale. + +(rfcs:rfc8:ids)= +#### IDs + +IDs identify the objects that are declared with the [`Declaration` interface](#declaration-interface). +All IDs MUST follow these rules: + +- IDs MUST be non-empty strings. +- IDs MUST only use characters in the sets `a-z`, `A-Z`, `0-9`, `-`, `_` and `.`. +- IDs MAY be UUIDs, in which case they SHOULD be UUIDv7+, e.g. `01a13520-b697-70c4-979b-b52c01fbbe30`. +- IDs SHOULD NOT encode semantics, such as the name, type or location of the declared object, because such information may change while the ID needs to stay stable (see [McMurry et al. 2017](https://doi.org/10.1371/journal.pbio.2001414)). + Human-readable information belongs in other fields, e.g. `name`. + +For readability, the examples in this document use short IDs such as `"000001"`. + +(rfcs:rfc8:declaration-interface)= +#### `Declaration` interface + +Every object that can be referenced is declared exactly once. +A declaration is the place where an object's `id` and its other fields are defined, e.g. an entry in a `nodes` or `coordinateSystems` array. + +Every declaration MUST have the following fields: + +| Field | Type | Required? | Notes | +| - | - | - | - | +| `"type"` | string | yes | Value MUST be the kind of the declared object, e.g. `"collection"` or `"multiscale"` for nodes and `"coordinate_system"` for coordinate systems. | +| `"id"` | string | yes | Value MUST be the identifier of the declared object. IDs MUST be unique within the JSON document. IDs MUST follow the [ID rules](#ids). | + +Additional fields, traits and child nodes of an object are defined on its declaration. +Everywhere else, the object is referred to with a [`Reference`](#reference-interface). +Declarations use the `id` key and references use the `ref` key, so that a declaration can always be told apart from a reference. + (rfcs:rfc8:reference-interface)= #### `Reference` interface -The `Reference` interface is a consistent system for referring to local and remote OME-Zarr metadata objects. +The `Reference` interface is a consistent system for referring to OME-Zarr metadata objects. +A reference points to an object that is [declared](#declaration-interface) elsewhere, e.g. in the `input` and `output` fields of coordinate transformations. +A reference is either a string (the short form) or an object (the full form). + +(rfcs:rfc8:reference-interface-example)= +##### Example + +A reference to a coordinate system that is declared in the same document, in the short form: + +```jsonc +"output": "000002" +``` + +The same reference in the full form: + +```jsonc +"output": { "type": "coordinate_system", "ref": "000002" } +``` + +A reference to a coordinate system that is declared in another document: + +```jsonc +"input": { + "type": "coordinate_system", + "path": { "type": "zarr", "format": "relative", "href": "./raw" }, + "ref": "000005" +} +``` (rfcs:rfc8:reference-interface-schema)= ##### Schema -A reference MUST be an object with the following fields: +A reference MUST be either a string or an object. + +A string reference MUST be the `id` of a declaration in the current metadata document. +A string reference MAY only be used where the field that holds it determines the `type` of the referenced declaration, e.g. the `output` of a coordinate transformation, which always references a coordinate system. +A string reference is equivalent to an object reference whose `type` is the type determined by the field, whose `ref` is the string, and which has no `path`. + +An object reference MUST have the following fields: | Field | Type | Required? | Notes | | - | - | - | - | -| `"id"` | string | yes | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. | -| `"path"` | object | no | Value MUST be a `Path` object. | +| `"type"` | string | yes | Value MUST be the `type` of the referenced declaration. | +| `"ref"` | string | yes | Value MUST be the `id` of the referenced declaration. | +| `"path"` | object | no | Value MUST be a `Path` object locating the document that contains the referenced declaration. | + +An object reference MUST NOT contain any other fields. +In particular, a reference MUST NOT carry traits or child nodes; these belong to the declaration. -(rfcs:rfc8:reference-interface-field-path)= -##### Field: `path` +(rfcs:rfc8:reference-interface-resolution)= +##### Resolution -For external references, the `path` field MUST be present. +- A string reference is resolved within the current metadata document. +- If the `path` of an object reference is absent, `ref` is resolved within the current metadata document. +- If the `path` of an object reference is present, `ref` is resolved within the metadata document that `path` locates. +- The resolved declaration MUST have the `type` that the reference names or, for a string reference, the type that the field determines. + Implementations MUST report an error if no declaration with the given ID exists in the resolved document, or if its `type` does not match. (rfcs:rfc8:abstract-structure)= ### Abstract structure @@ -294,14 +421,15 @@ added to collections or nodes, which is an opportunity to add metadata that is only valid for a node in the context of a collection (e.g. rendering settings). (rfcs:rfc8:abstract-structure-node)= -#### `Node` +#### `Node` interface This RFC defines a basic interface for an OME-Zarr metadata object, which we name `Node`. The [Node interface](#node) is a consistent JSON structure for -several different types of OME-Zarr metadata object, where fields specific to -the node type are inside an attributes field, and the root only stores +several different types of OME-Zarr metadata object and the root only stores information used for identifying and referencing the object. +Nodes conform to the [`Declaration` interface](#declaration-interface) and therefore require the `type` and `id` fields. + (rfcs:rfc8:abstract-structure-node-schema)= ##### Schema @@ -310,16 +438,18 @@ Objects that implement `Node` have the following fields: | Field | Type | Required? | Notes | | - | - | - | - | | `"type"` | string | yes | Value MUST be a string identifying the node type. | -| `"id"` | string | no | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | yes | Value MUST be a non-empty string intended for human-readable display. Names MUST be unique within the enclosing collection. | -| `"attributes"` | object | no | Value MUST be a dictionary. [See attributes section](#attributes) | +| `"id"` | string | yes | Value MUST be the identifier of the declared object. IDs MUST be unique within the JSON document. IDs MUST follow the [ID rules](#ids). | +| `"name"` | string | no | Value MUST be a non-empty string intended for human-readable display. | +| `"traits"` | array | no | Value MUST be an array of `Trait` objects. [See traits section](#traits) | (rfcs:rfc8:abstract-structure-node-field-type)= ##### Field: `type` The `type` field of a `Node` defines its structure and semantics, including any additional fields it might have. -This RFC defines three node types: `collection`, `multiscale`, and `singlescale`. +Additional functionality of a node can be expressed through its [traits](#traits). +This RFC defines two node types: `collection` and `multiscale`. +A third kind of object, the `array`, is not a node type: `array` objects are stored in the `data` field of a `multiscale` node. The `type` field of a `Node` is an extension point. For detail on how to extend the `type` field with new values, see [Extensions](#extensions). @@ -329,19 +459,22 @@ The `type` field of a `Node` is an extension point. For detail on how to extend A `Node` object may be used as the root object of the `ome` key, in which case a `version` field, as defined in previous spec versions, is also required. Non-root `Node` objects SHOULD NOT have a `version` field and MUST NOT have a different `version` value than the root `Node`. -(rfcs:rfc8:abstract-structure-attributes)= -#### Attributes +(rfcs:rfc8:abstract-structure-traits)= +#### Traits + +Each `Node` has a `traits` field that accepts a list of `Trait` objects. +The node type and the traits of a node have separate roles. +The node type defines the structure of a node: which fields it has and how readers traverse it and resolve its children. +Traits define the function of a node: what the data represents and how it relates to other nodes, e.g. that a collection is a plate, a well or a scene, or that an image contains labels. +A node may carry any number of traits, so independent aspects can be combined on the same node without defining a new node type for each combination. -Each `Node` has an `attributes` field that can be populated with JSON metadata. -A primary use case for the `attributes` field is the specialization of collections and nodes through additional metadata. +Each trait has minimally a `type` field, which dictates how the trait should be interpreted and defines the other fields it may contain. +Trait fields are stored inside the trait object, not on the node. +Readers that do not understand a trait MAY ignore it and still traverse the node based on its node type. -Attribute keys that are defined as part of this RFC are: -- `coordinateSystems` -- `coordinateTransformations` -- `labels`, as well as `labelValue` and `color` in label attributes -- `plate`, `well`, `acquisition` for HCS metadata +This RFC defines one type of trait: [`scene`](#scene-trait). -Attribute keys within the `attributes` dictionary of nodes are an extension point. Custom extensions can add prefixed keys (e.g., `neuroglancer:shader`, `webknossos:settings`). See [Extensions](#extensions) for more details. +Trait types are also an extension point, so any extension can define its own traits following the rules set forth in the [“Extensions” section](#extensions). #### Metadata storage @@ -358,9 +491,10 @@ This is particularly useful for defining the nodes that are stored within a Zarr "attributes": { "ome": { "version": "0.x", - // Our `collection`-typed node attributes + // Our `collection`-typed node fields // are listed here "type": "collection", + "id": "000001", "name": "zarr.json-example", "nodes": [...] } @@ -379,23 +513,87 @@ Standalone files are useful for persisting groupings of images that may or may n // an arbitrary json "ome": { "version": "0.x", - // Our `collection`-typed node attributes + // Our `collection`-typed node fields // are listed here "type": "collection", + "id": "000001", "name": "standalone-example", "nodes": [...] } } ``` +(rfcs:rfc8:metadata-storage-consolidated)= +##### Consolidated metadata (non-normative) + +This section is non-normative. + +Resolving a tree of path-referenced nodes requires fetching the `zarr.json` of each referenced Zarr group (see [Performance](#performance)). +To reduce the number of requests, writers MAY use [Zarr consolidated metadata](https://github.com/zarr-developers/zarr-specs/pull/309) to bundle the `zarr.json` documents of referenced nodes into the `zarr.json` of the root group. +Consolidated metadata stores a copy of the `zarr.json` of every group and array below the root group as a flat mapping, keyed by the path relative to the root group. +A reader that supports consolidated metadata can then load the whole tree in a single request. +This also applies to nested collections: their `zarr.json` documents may be consolidated into the root, while they remain separate documents with their own `ome` metadata. + +```jsonc +{ + // zarr.json of the root group + "zarr_format": 3, + "node_type": "group", + "attributes": { + "ome": { + "version": "0.x", + "type": "collection", + "id": "000001", + "name": "consolidated-example", + "nodes": [ + { + "type": "multiscale", + "id": "000002", + "name": "image", + "path": { "type": "zarr", "format": "relative", "href": "./image" } + } + ] + } + }, + "consolidated_metadata": { + "kind": "inline", + "must_understand": false, + "metadata": { + "image": { + // copy of ./image/zarr.json + "zarr_format": 3, + "node_type": "group", + "attributes": { "ome": { ... } } + }, + "image/s0": { + // copy of ./image/s0/zarr.json + "zarr_format": 3, + "node_type": "array", + ... + } + } + } +} +``` + +The individual `zarr.json` files remain the source of truth. +The consolidated copy is only a cache, and it can go stale when a referenced node is modified without updating the root. +Readers that support consolidated metadata use the consolidated copy when it is present, so they see outdated metadata until the root is consolidated again. +Keeping the cache consistent with the individual files would require an external transaction system, such as [Icechunk](https://icechunk.io) or a custom database. + +Consolidated metadata is a pure Zarr mechanism, and this RFC adds no OME-specific rules to it. +Readers that do not support consolidated metadata fetch the `zarr.json` of each referenced node as usual. +Consolidated metadata can only cover Zarr nodes within the hierarchy of the root group; standalone JSON files and nodes outside the root group are always fetched individually. + +At the time of writing, the Zarr-level specification of consolidated metadata is incomplete, which limits what this RFC can say about it. +A future revision may give more guidance once the Zarr specification is finalized. ### New and modified core classes Building on the core building blocks and the abstract structure, the following -sections define concrete node types for collections, single-scale images, and +sections define concrete node types for collections and multiscale images, and integrate coordinate systems and transformations from -RFC-5. Existing OME-Zarr structures such as multiscales and -bioformats2raw.layout are reworked within the Node/Collection-based framework. +RFC-5. Existing OME-Zarr structures such as multiscales are reworked within the Node/Collection-based framework. (rfcs:rfc8:collection-node)= #### `Collection` node @@ -406,8 +604,7 @@ images, including segmentations, prediction maps and other derived images as well as other data types ("nodes"). Collections can be nested. Collections can have metadata attached. Within collections, nodes can also have metadata, which complements or overrides the nodes' own metadata. Nodes within collections are -referenced by paths instead of relying on a file system hierarchy. Paths may -also be absolute and point to remote storage. +referenced by paths instead of relying on a file system hierarchy. (rfcs:rfc8:collection-node-schema)= ##### Schema @@ -415,74 +612,99 @@ also be absolute and point to remote storage. | Field | Type | Required? | Notes | | - | - | - | - | | `"type"` | string | yes | Value MUST be `"collection"`. | -| `"id"` | string | no | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | yes | Value MUST be a non-empty string intended for human-readable display. Names MUST be unique within the enclosing collection. | +| `"id"` | string | yes | Value MUST be the identifier of the declared object. IDs MUST be unique within the JSON document. IDs MUST follow the [ID rules](#ids). | +| `"name"` | string | no | Value MUST be a non-empty string intended for human-readable display. | | `"nodes"` | array | no | Value MUST be an array of `Node` objects. | | `"path"` | object | no | Value MUST be a `Path` object. | -| `"attributes"` | object | no | Value MUST be a dictionary. [See attributes section](#attributes). | +| `"traits"` | array | no | Value MUST be an array of `Trait` objects. [See traits section](#traits). | Either `"nodes"` or `"path"` MUST be present, but not both. +If `"path"` is present, the document it resolves to MUST have a root node of type `collection`. + ```jsonc { "ome": { "version": "0.x", "type": "collection", + "id": "000001", "name": "proj_gallery", "nodes": [{ "type": "collection", + "id": "000002", "name": "gallery1", "path": { "type": "json", - "path": "../gallery.json" + "format": "relative", + "href": "../gallery.json" } }, ...] } } ``` -(rfcs:rfc8:singlescale-node)= -#### `Singlescale` node +(rfcs:rfc8:array-node)= +#### `Array` object -A `Singlescale` node represents one resolution level of an OME-Zarr multiscale image. +An `Array` object represents one resolution level of an OME-Zarr multiscale image. This new interface replaces the dataset metadata defined in the previous versions of the OME-Zarr specification. -(rfcs:rfc8:singlescale-node-schema)= +`Array` objects are not nodes: they cannot appear in a `nodes` array and cannot be the root object of the `ome` key. +Instead, they are stored in the `data` field of a [`Multiscale` node](#multiscale-node), which is a leaf node. + +(rfcs:rfc8:array-node-schema)= ##### Schema | Field | Type | Required? | Notes | | - | - | - | - | -| `"type"` | string | yes | Value MUST be `"singlescale"`. | -| `"id"` | string | no | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | yes | Value MUST be a non-empty string intended for human-readable display. Names MUST be unique within the enclosing collection. | +| `"type"` | string | yes | Value MUST be `"array"`. | +| `"name"` | string | no | Value MUST be a non-empty string intended for human-readable display. | | `"path"` | object | no | Value MUST be a `Path` object. | -| `"attributes"` | object | yes | Value MUST be a dictionary. [See attributes section](#attributes). Required because it MUST contain `coordinateTransformations`.| +| `"downsamplingTransformations"` | array | no | Value MUST be an array of [`Downsampling Transformation`](#downsampling-transformation-interface) objects, from this resolution level to the highest-resolution level. | + +`Array` objects represent resolution levels within a multiscale pyramid. -`Singlescale` nodes represent resolution levels within a multiscale pyramid. +(rfcs:rfc8:array-node-field-downsamplingTransformations)= +##### Field: `downsamplingTransformations` -(rfcs:rfc8:singlescale-node-field-coordinateTransformations)= -##### Field: `coordinateTransformations` +`Array` objects other than the highest-resolution object MUST have a `downsamplingTransformations` field, which +- is an array of objects that conform to the [`Downsampling Transformation` interface](#downsampling-transformation-interface). +- contains and only contains either a single `scale` transformation, or a `scale` transformation followed by a `translation` transformation. -`Singlescale` nodes MUST have a `coordinateTransformations` key in their `attributes`, which -- is an array of transformation objects, that conform to the [coordinate transformations](#coordinate-transformations) specification -- contain and only contain a single `scale` transformation, or a `sequence` of a `scale` transformation followed by a `translation` transformation. -- The `input` field of these transformations references the `id` of the `Singlescale` node itself. -- The `output` field references the `id` of a coordinate system defined under `coordinateSystems` in a `Multiscale` node. +The `input` and `output` of these transformations are implicit: +the `input` is the `Array` object itself, and the `output` is the highest-resolution `Array` object in the `data` field of the enclosing `multiscale` node. ```jsonc { "ome": { "version": "0.x", - "type": "singlescale", - "id": "s0", - "name": "s0", - "path": { - "type": "zarr", - "path": "./s0" - }, - "attributes": { - ... - } + "type": "multiscale", + "id": "000001", + "name": "our_first_pyramid", + "coordinateSystems": [...], + "coordinateTransformations": [...], + "data": [ + { + "type": "array", + "path": { + "type": "zarr", + "format": "relative", + "href": "s0" + } + }, + { + "type": "array", + "path": { + "type": "zarr", + "format": "relative", + "href": "s1" + }, + "downsamplingTransformations": [ + {"type": "scale", "scale": [1, 2, 2]}, + {"type": "translation", "translation": [0, 0.5, 0.5]} + ] + } + ] } } ``` @@ -492,6 +714,7 @@ This new interface replaces the dataset metadata defined in the previous version A `Multiscale` node represents an OME-Zarr multiscale image. This new interface replaces the multiscale metadata defined in the previous versions of the OME-Zarr specification. +A `Multiscale` node is a leaf node: it has no child nodes. Its resolution levels are [`Array` objects](#array-object) stored in its `data` field. (rfcs:rfc8:multiscale-node-schema)= ##### Schema @@ -499,31 +722,33 @@ This new interface replaces the multiscale metadata defined in the previous vers | Field | Type | Required? | Notes | | - | - | - | - | | `"type"` | string | yes | Value MUST be `"multiscale"`. | -| `"id"` | string | no | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | yes | Value MUST be a non-empty string intended for human-readable display. Names MUST be unique within the enclosing collection. | -| `"nodes"` | array | no | Value MUST be an array of `Singlescale` objects. | +| `"id"` | string | yes | Value MUST be the identifier of the declared object. IDs MUST be unique within the JSON document. IDs MUST follow the [ID rules](#ids). | +| `"name"` | string | no | Value MUST be a non-empty string intended for human-readable display. | +| `"data"` | array | no | Value MUST be an array of `Array` objects. [See array object](#array-object). | | `"path"` | object | no | Value MUST be a `Path` object. | -| `"attributes"` | object | yes | Value MUST be a dictionary. [See attributes section](#attributes). Required because it MUST contain `coordinateSystems`.| +| `"coordinateSystems"` | array | yes | Value MUST be an array of `coordinateSystem` objects. | +| `"coordinateTransformations"` | array | yes | Value MUST be an array of `coordinateTransformation` objects, the output of which MUST be present in the `coordinateSystems` array. | +| `"traits"` | array | no | Value MUST be an array of `Trait` objects. [See traits section](#traits).| -Either `"nodes"` or `"path"` MUST be present, but not both. +Either `"data"` or `"path"` MUST be present, but not both. + +If `"path"` is present, the document it resolves to MUST have a root node of type `multiscale`. ```jsonc { "ome": { "version": "0.x", "type": "multiscale", + "id": "000001", "name": "imagepyramid1", - "nodes": [ + "data": [ { - "id": "s0", "name": "s0", - "type": "singlescale", + "type": "array", "path": { "type": "zarr", - "path": "./s0" - }, - "attributes": { - ... + "format": "relative", + "href": "./s0" } }, ... @@ -532,11 +757,12 @@ Either `"nodes"` or `"path"` MUST be present, but not both. } ``` +(coordinate-transformations)= #### Coordinate transformations Coordinate systems and transformations can be stored in two distinct locations: -- For single multiscale or singlescale images, they can be stored in the `ome` key of the `attributes` container in a `zarr.json` file of the multiscales zarr group. +- For multiscale images, they can be stored directly in the coordinateSystems and coordinateTransformations fields of the multiscale node. - For collections of two or more images in a common coordinate system, RFC-5 defines a parent-level metadata format. In this layout, `coordinateTransformations` define relationships between different `coordinateSystems`, which may be associated to multiscale images: @@ -547,14 +773,23 @@ Coordinate systems and transformations can be stored in two distinct locations: { "type": "translation", "translation": [0, 0, 100], - "input": {"id": "physical", "path": "./image_1"}, // references collection node ID - "output": {"id": "world"} // references coordinate system ID + "input": { + // references coordinate system 'physical' defined in image_1 + "type": "coordinate_system", + "ref": "000005", + "path": {"type": "zarr", "format": "relative", "href": "./image_1"} + }, + // references coordinate system 'world' defined in the same document + "output": "000002" } ] } ``` -In a change from the previous specification, coordinate systems are referenced using the [Reference mechanism](#reference-interface), i.e. via IDs, and not via names. +In a change from RFC-5, coordinate systems are referenced by ID and not by name. +Each `input` and `output` is a [`Reference`](#reference-interface). +A coordinate system that is declared in the same document is referenced by its ID as a string. +A coordinate system that is declared in another document is referenced with an object reference that names the kind of the target (`coordinate_system`), its ID in the `ref` field, and the `path` of the document. ```jsonc { @@ -562,12 +797,15 @@ In a change from the previous specification, coordinate systems are referenced u "version": "0.x", "type": "collection", "name": "Tiles", - "id": "tiles", - "attributes": { - "scene": { + "id": "000001", + "traits": [ + { + "type": "scene", "coordinateSystems": [ { - "id": "world", + "type": "coordinate_system", + "id": "000002", + "name": "world", "axes": [...] } ], @@ -576,46 +814,52 @@ In a change from the previous specification, coordinate systems are referenced u "type": "translation", "translation": [0, 0, 100], "input": { + "type": "coordinate_system", + "ref": "000005", "path": { "type": "zarr", - "path": "./tile_0.zarr" - }, - "id": "physical" + "format": "relative", + "href": "./tile_0.zarr" + } }, // references coordinate system "physical" defined in tile_0 - "output": {"id": "world"} // references coordinate system "world" defined in same node + "output": "000002" // references coordinate system "world" defined in same node }, { "type": "translation", "translation": [100, 0, 0], "input": { + "type": "coordinate_system", + "ref": "000006", "path": { "type": "zarr", - "path": "./tile_1.zarr" - }, - "id": "physical" + "format": "relative", + "href": "./tile_1.zarr" + } }, // references coordinate system "physical" defined in tile_1 - "output": {"id": "world"} // references coordinate system "world" defined in same node + "output": "000002" // references coordinate system "world" defined in same node } ] } - }, + ], "nodes": [ { "type": "multiscale", - "id": "tile_0", + "id": "000003", "name": "Tile 0", "path": { "type": "zarr", - "path": "./tile_0.zarr" + "format": "relative", + "href": "./tile_0.zarr" } }, { "type": "multiscale", - "id": "tile_1", + "id": "000004", "name": "Tile 1", "path": { "type": "zarr", - "path": "./tile_1.zarr" + "format": "relative", + "href": "./tile_1.zarr" } } ] @@ -633,9 +877,10 @@ The `Coordinate System` objects have the following fields: | Field | Type | Required? | Notes | | - | - | - | - | -| `"id"` | string | yes | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. ID to use when referencing the coordinate system from a transformation. IDs MUST be unique within the JSON document. | +| `"type"` | string | yes | Value MUST be `"coordinate_system"`. | +| `"id"` | string | yes | Value MUST be the identifier of the declared object. IDs MUST be unique within the JSON document. IDs MUST follow the [ID rules](#ids). | | `"name"` | string | no | More descriptive name for the coordinate system, if needed. | -| `"axes"` | array of strings | yes | Value MUST be an array of axes, as defined in RFC-5. | +| `"axes"` | array of Axis objects | yes | Value MUST be an array of axes, as defined in RFC-5. | The `type` field of an `Axis` object is an extension point. For detail on how to extend the `type` field with new values, see [Extensions](#extensions). @@ -646,257 +891,376 @@ The `Coordinate Transformation` objects have the following fields: | Field | Type | Required? | Notes | | - | - | - | - | | `"type"` | string | yes | Value MUST be a valid coordinate transform type, as defined in RFC-5. | -| `"input"` | object | yes | Value MUST be a [`Reference`](#reference-interface) to the input [`Coordinate System`](#coordinate-system-interface). | -| `"output"` | object | yes | Value MUST be a [`Reference`](#reference-interface) to the output [`Coordinate System`](#coordinate-system-interface). | +| `"input"` | string or object | yes | Value MUST be a [`Reference`](#reference-interface) to the input of the transformation. | +| `"output"` | string or object | yes | Value MUST be a [`Reference`](#reference-interface) to the output of the transformation. | Additional fields MAY be added as required by the transform type. -Depending on the context, different fields are required: +Depending on the context, the `input` and `output` references point to different kinds of objects: | Context | `input` | `output` | | - | - | - | -| **scene** | {"id": "imageA", "name": "physical" } | { "id": "imageB", "name": "physical" } | -| **Multiscale > attributes > coordinateTransformations** | { "id": "scale0"} | { "id": "image", "name": "physical" } | +| **scene** | `"000002"` or `{"type": "coordinate_system", "path": {..., "href": "./imageA"}, "ref": "000005"}` | `"000003"` or `{"type": "coordinate_system", "path": {..., "href": "./imageB"}, "ref": "000006"}` | +| **Multiscale > coordinateTransformations** | `"000001"` (the enclosing multiscale) | `"000002"` | -**Multiscale > attributes > coordinateTransformations**: In the context of multiscales transformations, the following requirements apply: -- The `input` field MUST reference a [singlescale node](#singlescale-node). -- The `id` field MUST be present. -- The `path` field MAY be omitted or null. -- The `output` fields of all transformations MUST reference the same coordinate system via the `id` field. +**Multiscale > coordinateTransformations**: In the context of multiscales transformations, the following requirements apply: +- The `input` field MUST be a reference of type `multiscale` to the enclosing [`Multiscale` node](#multiscale-node). + It stands for the highest-resolution `Array` object in the `data` field of the multiscale. + Lower-resolution `Array` objects are related to the highest-resolution one by their [downsampling transformations](#downsampling-transformation-interface). +- The `output` field MUST be a reference of type `coordinate_system` to a coordinate system in the `coordinateSystems` field of the multiscale. +- The `output` fields of all transformations MUST reference the same coordinate system. +- Both references SHOULD be strings. -**Node/Multiscales > attributes > scene > coordinateTransformations**: -In the context of node-level transformations between different multiscale collections, -the following requirements apply: -- The `input` field MUST reference a coordinate system via the `id` field. -- The `output` field MUST reference a coordinate system via the `id` field. -- If the referenced coordinate system is in the same metadata document, the `path` field MAY be omitted or null. - If the referenced coordinate system is in a different metadata document, both the `id` and `path` fields MUST be present. +**Node/Multiscales > scene > coordinateTransformations**: +In the context of node-level transformations between different multiscales, the following requirements apply: +- The `input` and `output` fields MUST be references of type `coordinate_system`. +- If the referenced coordinate system is declared in the same metadata document, the reference SHOULD be a string. +- If the referenced coordinate system is declared in a different metadata document, the reference MUST be an object with a `path` field. +##### `Downsampling Transformation` interface -##### `Scene` attribute +A downsampling transformation relates a lower-resolution `Array` object to the highest-resolution `Array` object of the same multiscale. +It is a constrained version of the [`Coordinate Transformation` interface](#coordinate-transformation-interface): +its `input` and `output` are implicit, and only the `scale` and `translation` types are allowed. -The `scene` attribute MUST be an object with the following fields: +The `Downsampling Transformation` objects have the following fields: + +| Field | Type | Required? | Notes | +| - | - | - | - | +| `"type"` | string | yes | Value MUST be either `"scale"` or `"translation"`. | +| `"scale"` | array of numbers | if `type` is `"scale"` | Value MUST be as defined for the `scale` transformation in RFC-5. | +| `"translation"` | array of numbers | if `type` is `"translation"` | Value MUST be as defined for the `translation` transformation in RFC-5. | + +A downsampling transformation MUST NOT contain any other fields; in particular, it MUST NOT contain `input` or `output` fields. + +A `downsamplingTransformations` array MUST contain exactly one `"scale"` transformation, which MAY be followed by exactly one `"translation"` transformation. +The translation accounts for the offset of the origin pixel due to the downsampling grid. + +The downsampling transformations of an `Array` object can be cast into a coordinate transformation by adding the implicit fields: + +- The `input` is the array coordinate system of the `Array` object that contains the transformations. +- The `output` is the array coordinate system of the highest-resolution `Array` object in the `data` field of the enclosing `Multiscale` node. +- A single `scale` is cast into a `scale` transformation. + A `scale` followed by a `translation` is cast into a `sequence` transformation that applies them in that order. + +The result conforms to the [`Coordinate Transformation` interface](#coordinate-transformation-interface). + +##### `Scene` trait + +The `scene` trait MUST be an object with the following fields: | Field | Type | Required? | Notes | | - | - | - | - | | `"coordinateSystems"` | array | no | Values MUST be valid instances of [`Coordinate System`](#coordinate-system-interface) objects. | -| `"coordinateTransformations"` | array | yes | Values MUST be valid instances of [`Coordinate transformation`](#coordinate-transformation-interface) objects | +| `"coordinateTransformations"` | array | yes | Values MUST be valid instances of [`Coordinate transformation`](#coordinate-transformation) objects | -A `scene` metadata object can be defined in the `attributes` of a collection to enrich the collection with spatial information of the nodes within the collection. -The `scene` field allows to clearly distinguish between the spatial information pertaining to an individual multiscale image (which is stored in the `attributes` of the multiscale) -and the spatial information pertaining to the collection of images (which is stored in the `attributes` of the collection). +A `scene` metadata object can be defined in the `traits` of a collection to enrich the collection with spatial information of the nodes within the collection. +The `scene` trait allows to clearly distinguish between the spatial information pertaining to an individual multiscale image (which is stored in the `coordinateSystems` and `coordinateTransformations` fields of the multiscale node) +and the spatial information pertaining to the collection of images (which is stored in the `scene` trait of the collection). -#### Label maps and other derived images +## Extensions -Previous versions of the OME-Zarr specification defined a mechanism for associating label images with a single multiscale image. -This was achieved by using a `labels` Zarr group that had to be a direct child of the multiscale Zarr group with some specific metadata. -This proposal replaces this mechanism. +This section describes an extensibility mechanism by which anyone can unilateraly extend the OME-Zarr specification and store, under the `ome` attribute of a `zarr.json` file (or any standalone JSON file), additional metadata that were not envisioned by the specification, all the while maintaining interoperability with OME-Zarr applications. -To denote a multiscale image as a label map, the `labels` attribute MUST be present. -If present, the value of the `labels` attribute MUST be an object with the following fields: +The basic principle is that an extension compliant with this extensibility mechanism can extend the specification by **defining additional, custom types**. An OME-Zarr extension is therefore essentially a set of custom types. -| Field | Type | Required? | Notes | -| - | - | - | - | -| `"labelAttributes"` | array of objects | no | Attributes for individual labels. Each object MUST be a [`Label Attributes` object](#label-attributes-interface). -| `"source"` | array of strings | no | An array with [`Reference`s](#reference-interface) to the source multiscales. | +### Rationale for OME-Zarr extensions -Because no fields are required, an empty object MAY be used. +We must acknowledge from the very beginning that, by its very nature, OME-Zarr is already _de facto_ extensible, even before the word “extensibility” makes it into the OME-Zarr specification. Anyone can craft an OME-Zarr fileset that contains data beyond what is described in the current version of the specification. Most if not all OME-Zarr readers are inherently “permissive”, in that they will silently ignore anything that they don’t recognise or don’t expect within an OME-Zarr fileset, so that the presence of additional data will typically not result in an unreadable fileset. -In this proposal, the previous `colors` and `properties` fields are combined into a single `labelAttributes` field. -The `rgba` field in the `colors` objects has been renamed to `color`. +However, if left unchecked, this _de facto_ extensibility could quickly become a barrier to interoperability. If every single creator of OME-Zarr filesets can singlehandedly come up with its own way of representing a particular piece of data, then there is a risk that a particular piece of data may be understandable only by the very same implementation that created it; or (arguably even worse) that a particular piece of data may be understood _differently_ by different implementations. Ultimately, OME-Zarr could end up as a file format that is interoperable in name only: everybody would be using OME-Zarr, but all in slightly incompatible ways. -##### `Label Attributes` interface +The solution to that risk is _not_ to “close down” OME-Zarr, to mandate implementations to be non-permissive and to consider that anything that is not explicitly allowed by the specification is forbidden. In fact, even if we wanted to do that, we would have little to no leverage to actually enforce such a policy. Instead, we believe the proper solution is for OME-Zarr to provide a built-in extensibility mechanism. There will be no _obligation_ for people willing to extend OME-Zarr to use the mechanism defined here (again, we would have very little leverage to enforce such an obligation anyway), but (voluntarily) using it would allow the OME-Zarr community to _manage_ the interoperability issues. -The `labelAttributes` field is an array of objects with the following fields: +The manageability aspect is important because an extensibility system alone cannot prevent (a) the risk of a fragmented ecosystem, with an uncontrolled proliferation of redundant extensions; (b) the risk of uninterpretable extensions, that cannot be understood beyond their originating implementations. Instead, the OME-Zarr community will need to take steps to actively monitor the extension ecosystem and intervene as needed to try avoiding redundant or concurrent extensions in favour of promoting cooperation. -| Field | Type | Required? | Notes | -| - | - | - | - | -| `"labelValue"` | number | yes | Value MUST be the label value. | -| `"color"` | array of number | no | Value MUST be a color in array format. | +In short, we propose that OME-Zarr should offer a system of _manageable_ extensibility, which would be preferred over the _de facto_ extensibility that is already offered by the very nature of OME-Zarr. -If present, the `color` field MUST have an array with four integers between 0 and 255, inclusive. These integers represent the uint8 values of red, green, blue and alpha. +This proposal requires that extensions be treated as first-class objects within the OME-Zarr specification, which is the purpose of this section of the present RFC. -Additional keys MAY be added, [following the attribute key naming rules](#extensions). +In the rest of this document, the word “extension” will be understood as referring strictly to “an extension compliant with the proposed extensibility mechanism”, ignoring all other possibilities of extensions. -The previous `label-value` key is now renamed to `labelValue` for consistency. +#### Desired characteristics for OME-Zarr’s extensibility mechanism +(Those characteristics are _not_ listed in any particular order.) -##### Example +1. Anyone can define an extension. Prior permission is not required. +2. An extension can extend another extension, without arbitrary limits as to the “depth” of an extension chain. +3. Data from an extension must be preserved by all implementations – including implementations that are not explicitly aware of that particular extension. OME-Zarr readers must be able to pass unknown extensions’ data down to their client code. +4. Extensions must be unambiguously identifiable. +5. An OME-Zarr reader must be able to quickly determine (and report to client code) the extensions that are being used within an OME-Zarr fileset, if any. +6. OME-Zarr implementations must be able to unambiguously state which extensions they explicitly support, preferably in machine-readable form. +7. Any extension must be clearly documented. The documentation must state what additional data the extension is intended to store, the purpose of such data, and where to find them. +8. Any extension must provide a formal schema describing the shape of its data and allowing even an implementation that does not explicitly support the extension to perform basic validation of the extension’s data. +9. An extension should have a way to self-declare how “important” the extension is for a correct understanding of the OME-Zarr fileset in which it is used. +10. The extensibility mechanism must ensure the absence of naming conflicts between two extensions developed independently. +11. There must be a reasonably straightforward way to “promote” an extension so that it becomes part of the next version of the OME-Zarr specification, if there is agreement among the OME-Zarr community (as reached, most likely, through the existing RFC process) about the usefulness of the extension. +12. The promotion of an extension must not invalidate existing data created before the extension was promoted. -```jsonc -{ - "ome": { - "version": "0.x", - "type": "collection", - "name": "label-example", - "attributes": { ... }, - "nodes": [{ - "id": "raw", - "name": "raw", - "type": "multiscale", - "nodes": [ ... ] - }, { - "name": "nuclei", - "type": "multiscale", - "nodes": [ ... ], - "attributes": { - "labels": { - "source": [ {"id": "raw"} ], - "labelAttributes": [{ - "labelValue": 1, - "color": [ 255, 0, 0, 255 ] - }, { - "labelValue": 2, - "color": [ 0, 255, 0, 255 ] - }] - } - } - }] - } -} -``` +### Extension and custom type identifiers -#### High-content screening (HCS) metadata +An extension MUST have a unique identifier, which SHOULD be an absolute URI that SHOULD end with either `#` or `/`. -High-content screening data is typically organized as a grid of wells on a plate, where each well contains one or more multiscale images from one or more acquisition rounds. -This section introduces additional metadata for organizing wells on a plate. +All custom types defined by an extension MUST have their own unique identifier, which MUST be built by appending a type-specific suffix (the type’s _local name_, within the context of the extension that defines it) to the extension’s identifier. -This proposal changes the HCS references from numeric IDs and names to string-based ID references, consistent with the [References mechanism](#reference-interface) defined above. +> For example, if an extension with the identifier `https://example.org/my-ngff-extension/` defined a new type of coordinate transformation named `NonLinearTransform`, the identifier for the new type would be `https://example.org/my-ngff-extension/NonLinearTransform`, with `NonLinearTransform` being the type’s local name. -##### `Plate` attribute +Extensions that add functions to existing structures SHOULD define new trait types rather than new node types. +New node types are intended for data whose structure cannot be represented by the existing node types. -A `collection` node representing a plate MUST have a `plate` attribute with the following fields: +### Extension points -| Field | Type | Required? | Notes | -| - | - | - | - | -| `"acquisitions"` | array of objects | no | List of acquisitions performed on the plate. Each object MUST be [`Acquisition` objects](#acquisition-interface). | -| `"columns"` | array of objects | yes | List of columns in the plate. Each object MUST be [`Column` objects](#column-interface). | -| `"rows"` | array of objects | yes | List of rows in the plate. Each object MUST be [`Row` objects](#row-interface). | +Custom types can be used in lieu of existing types defined by the specification, at defined extension points. -##### `Acquisition` interface +An extension point is a `type` field within an object where (1) the value of the `type` field dictates how the rest of the object is to be interpreted, and (2) the OME-Zarr specification explicitly states that the allowed values in the `type` field “MAY be extended” (exact phrasing does not matter as long as the intention is clear). -| Field | Type | Required? | Notes | -| - | - | - | - | -| `"id"` | string | yes | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | no | A human-readable name for the acquisition. | +At such an extension point, a custom type may be used by specifying its identifier in the `type` field, in lieu of one the values allowed by the specification. The custom type, as defined by the extension it belongs to, will then dictate how the object is to be interpreted. -##### `Column` interface +For example, the [`Path` interface](#path-interface) proposed by this very RFC has an extension point: it has a `type` field defined as accepting two values (`zarr` and `json`); the value dictates how the entire `Path` object is to be interpreted; and the specification explicitly states it is an extension point. An extension could then define a new, custom type of `Path` object. + +### Extension manifest + +Any JSON file that makes use of extension-defined custom types MUST declare an extension manifest, which MUST list every extension used within the file. The manifest is stored under the `extensionManifest` key of the `ome` object. + +The extension manifest has several purposes, all stemming from the intention of making extensions “manageable”. Notably, it is intended to: + +- allow figuring out at a glance (1) whether an OME-Zarr image is making use of extensions at all, and (2) if so, which extensions are being used; +- provide informations about an extension, including pointers to human-readable documentation and machine-readable schemas. + +When the metadata of an OME-Zarr image are spread over several JSON files in different Zarr groups, each file MUST carry its own manifest, listing the extensions used in that file. Additionally, the manifest in the root-level `zarr.json` file SHOULD list every extension used in any of the downstream files, so that a reader can find out which extensions are being used in an entire image without having to check all the JSON files in the Zarr hierarchy. + +The manifest MUST be an array of extension objects. Each listed extension MUST be an object with the following fields: | Field | Type | Required? | Notes | | - | - | - | - | -| `"id"` | string | yes | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | no | A human-readable name for the column. | +| `"id"` | string | yes | Identifier for the extension. SHOULD be an absolute URI. MUST be unique within the manifest. | +| `"version"` | string | yes | Version of the extension used in the document. | +| `"name"` | string | no | Short human-readable name, for display. | +| `"description"` | string | no | One-sentence human-readable description of the extension. | +| `"mustUnderstand"` | boolean | no | Whether knowledge of this extension is required for faithful processing of the data. Default `false`. | +| `"homepage"` | string | no | URL to a homepage or documentation page for the extension. | +| `"schemas"` | list[Schema] | yes | Formal schemas describing the custom types defined by the extension. | -##### `Row` interface +Each item in the `schemas` list MUST be an object with the following fields: | Field | Type | Required? | Notes | | - | - | - | - | -| `"id"` | string | yes | Value MUST be a string that matches `[a-zA-Z0-9-_.]+`. IDs MUST be unique within the JSON document. | -| `"name"` | string | no | A human-readable name for the row. | +| `"type"` | string | yes | Value MUST be either `linkml` or `jsonschema`. | +| `"url"` | string | yes | A URL pointing to the schema. | -##### `Well` attribute +Future versions of this specification may add new types of schemas. -A `collection` node representing a well MUST have a `well` attribute with the following fields: +#### Use of schemas -| Field | Type | Required? | Notes | -| - | - | - | - | -| `"column"` | string | yes | Value MUST be a [`Reference`](#reference-interface) to one of the columns listed in the `plate` attribute on the enclosing plate-level collection. | -| `"row"` | string | yes | Value MUST be a [`Reference`](#reference-interface) to one of the rows listed in the `plate` attribute on the enclosing plate-level collection. | +An extension MUST provide at least one schema in one of the supported schema definition languages (currently `linkml` or `jsonschema`). + +When using a JSON-Schema, every custom object type defined by the extension MUST be formally described in an entry within the `$defs` key of the JSON-Schema, where the name of the entry MUST match the custom type’s local name. + +When using a LinkML schema, every custom object type defined by the extension MUST be formally described by a LinkML class definition whose name MUST match the custom type’s local name. + +Readers that do not explicitly support an extension MAY use the provided schema(s) to attempt to validate the extension’s data. If they do so, they SHOULD treat any validation error the same way as they would treat any non-compliant data. + +Viewers that do not explicitly support an extension MAY use the provided schema(s) to display the extension’s data in a meaningful way, for example by using any provided human-readable labels and descriptions for the objects and fields that make up the extension’s data. + +#### The `mustUnderstand` flag + +Some extensions are intended to only add non-essential information, such as a viewer’s display settings, or a description of how the image was acquired. A reader that ignores such extensions can still interpret the rest of the data correctly. Other extensions may change what the data _means_, e.g. a coordinate transformation the reader cannot apply, or pixel values that are not intensities. A reader that ignores those would be at risk at misleading its users. The `mustUnderstand` flag lets writers state which case applies for any given extension. -##### `Acquisition` attribute +When a reader encounters a custom type that (1) it does not explicitly support and (2) is defined by an extension whose `mustUnderstand` flag is set to `true`, the reader MUST NOT silently fall back to a generic interpretation of the object; it MAY skip the object and report it as unsupported; it MAY continue to interpret the rest of the dataset. When the custom type is a [trait](#traits), this paragraph applies to the object that is carrying the trait. -The `acquisition` attribute MUST be a [`Reference`](#reference-interface) to one of the acquisitions. -It MAY be set on individual `multiscale` nodes within a well or on a `collection` sub-node grouping all images from a single acquisition. +Readers MAY use the extension manifest to decide up front whether an OME-Zarr image is likely to be fully supported, without waiting to encounter an unknown custom type. -We suggest two possible layouts for HCS data, which are not mutually exclusive and can be used in combination: a "wide" layout where all images are direct children of the well collection and a "tall" layout where images are grouped in sub-collections by acquisition. +Writers SHOULD set `mustUnderstand: true` for a given extension only when ignoring the extension’s data would cause _incorrect_ interpretation, not merely _less complete_ interpretation. -##### Wide example (acquisitions flat in the well) +### Examples + +#### Extending the `Path` object -In this layout, all multiscale nodes are direct children of the well collection. -Each node carries an `acquisition` attribute. -Derived images such as label maps are siblings of their source image and can still be linked via the `source` reference in their `labels` attribute. This layout is more compact but can become cluttered when there are multiple acquisitions and derived nodes. +This example illustrates an extension with ID `https://ngff.example.org/omero/` that adds a custom type of `Path` that points to an image on an OMERO server rather than to a file. ```jsonc { "ome": { "version": "0.x", - "type": "collection", - "name": "hcs-plate-001", - "attributes": { - "plate": { - "acquisitions": [ - { - "id": "acq_0", - "name": "Acquisition Round 1" - } - ], - "columns": [ - { - "id": "1", - "name": "1" - } - ], - "rows": [ + "extensionManifest": [ + { + "id": "https://ngff.example.org/omero/", + "version": "0.3", + "name": "OMERO connector extension for OME-Zarr", + "description": "An extension to allow referring to remote OMERO images from within a OME-Zarr image.", + "homepage": "https://ngff.example.org/omero/", + "schemas": [ { - "id": "A", - "name": "A" + "type": "jsonschema", + "url": "https://schemas.ngff.example.org/omero/0.3/omero.json" } ] } - }, + ], + "type": "collection", "nodes": [ { - "type": "collection", - "name": "well A01", - "attributes": { - "well": { - "column": {"id": "1"}, - "row": {"id": "A"} - } + "name": "original-acquisition", + "type": "multiscale", + "path": { + "type": "https://ngff.example.org/omero/OMEROPath", + "href": "https://omero.example.org/webclient/?show=image-48213", + "host": "omero.example.org", + "port": 4064, + "imageId": 48213 + } + }, + { + "name": "segmentation", + "type": "multiscale", + "path": {"type": "zarr", "format": "relative", "href": "./segmentation"} + } + ] + } +} +``` + +The JSON-Schema for that extension could be: + +```jsonc +{ + "$defs": { + "OMEROPath": { + "description": "A Path that points to an image on an OMERO server.", + "properties": { + "type": { + "description": "The object's type", + "type": "string" + }, + "href": { + "description": "Full URL to the image.", + "type": "string" }, - "nodes": [ + "host": { + "description": "The hostname of the OMERO server.", + "type": "string" + }, + "port": { + "description": "The TCP port to use when connecting to the server.", + "type": "number", + "default": 4064 + }, + "imageId": { + "description": "The ID of the image on the OMERO server.", + "type": "number" + } + }, + "required": [ + "type", + "href", + "host", + "imageId" + ], + "type": "object" + } + } +} +``` + +A LinkML schema for the same extension, if one were provided, could be: + +```yaml +id: https://ngff.example.org/omero/ +name: OMERO connector extension for OME-Zarr +prefixes: + linkml: https://w3id.org/linkml/ +imports: + - linkml:types +default_range: string +classes: + OMEROPath: + description: A Path that points to an image on an OMERO server. + attributes: + type: + description: The object’s type. + required: true + href: + description: Full URL to the image. + range: uri + required: true + host: + description: The hostname of the OMERO server. + required: true + port: + description: The TCP port to use when connecting to the server. + range: integer + ifabsent: int(4064) + imageId: + description: The ID of the image on the OMERO server. + range: integer + required: true +``` + +#### A custom `coordinateTransformation` + +In this example, a `https://ngff.example.com/transforms/` extension defines a custom type of coordinate transformation that uses the “thin plate spline” technique. + +```jsonc +{ + "ome": { + "version": "0.x", + "extensionManifest": [ + { + "id": "https://ngff.example.com/transforms/", + "version": "0.1", + "name": "OME-Zarr additional transforms", + "description": "An extension providing additional coordinate transformations.", + "homepage": "https://example.com/ngff-extensions/transforms/", + "schemas": [ { - "id": "A01_0", - "type": "multiscale", - "name": "A01_0", - "path": { - "type": "zarr", - "path": "./A/01/001.img" - }, - "attributes": { - "acquisition": {"id": "acq_0"} - } - }, + "type": "jsonschema", + "url": "https://schemas.example.org/transforms/0.1/transforms.json" + } + ] + } + ], + "type": "collection", + "id": "000001", + "nodes": [ /* ... */ ], + "traits": [ + { + "type": "scene", + "coordinateSystems": [ { - "type": "multiscale", - "name": "A01_0_ill_corrected", - "path": { - "type": "zarr", - "path": "./A/01/001_ill_corrected.img" - }, - "attributes": { - "acquisition": {"id": "acq_0"}, - "source": [{"id": "A01_0"}] - } + "type": "coordinate_system", + "id": "000002", + "name": "physical", + "axes": [ + {"name": "y", "type": "space", "units": "micrometer"}, + {"name": "x", "type": "space", "units": "micrometer"} + ] }, { - "type": "multiscale", - "name": "A01_0_nuclei", - "path": { + "type": "coordinate_system", + "id": "000003", + "name": "registered", + "axes": [ + {"name": "y", "type": "space", "units": "micrometer"}, + {"name": "x", "type": "space", "units": "micrometer"} + ] + } + ], + "coordinateTransformations": [ + { + "type": "https://ngff.example.com/transforms/ThinPlateSpline", + "input": "000002", + "output": "000003", + "controlPoints": { "type": "zarr", - "path": "./A/01/001_nuclei.img" + "format": "relative", + "href": "./tps/control_points" }, - "attributes": { - "acquisition": {"id": "acq_0"}, - "labels": { - "source": [{"id": "A01_0"}] - } - } + "regularization": 0.01 } ] } @@ -905,116 +1269,63 @@ Derived images such as label maps are siblings of their source image and can sti } ``` -##### Tall example (acquisitions as sub-collections) +#### Viewer rendering states -In this layout, each acquisition is wrapped in a sub-collection inside the well. -The `acquisition` attribute is set on the sub-collection rather than on individual nodes. -This serves as an example that wells can consist of collections, not just multiscales. +In this example, two OME-Zarr viewers, “Viewer A” and “Viewer B” each have their own extension providing a custom trait to store their own display settings for the same image. ```jsonc { "ome": { "version": "0.x", - "type": "collection", - "name": "hcs-plate-001", - "attributes": { - "plate": { - "acquisitions": [ - { - "id": "acq_0", - "name": "Acquisition Round 1" - }, - { - "id": "acq_1", - "name": "Acquisition Round 2" - } - ], - "columns": [ + "extensionManifest": [ + { + "id": "https://viewer-a.example.com/settings/", + "version": "0.1", + "name": "Viewer-A visualisation settings", + "description": "An extension to store Viewer A-specific settings into an OME-Zarr image", + "homepage": "https://viewer-a.example.com/", + "schemas": [ { - "id": "1", - "name": "1" + "type": "jsonschema", + "url": "https://viewer-a.example.com/ngff/schemas/settings-0.1.json" } - ], - "rows": [ + ] + }, + { + "id": "https://viewer-b.example.org/rendering/", + "version": "0.2", + "name": "Viewer-B visualisation settings", + "description": "An extension to store Viewer B-specific settings into an OME-Zarr image", + "homepage": "https://viewer-b.example.org/", + "schemas": [ { - "id": "A", - "name": "A" + "type": "jsonschema", + "url": "https://viewer-b.example.org/ngff-embedded-settings.json" } ] } - }, + ], + "type": "collection", + "id": "000001", "nodes": [ { - "type": "collection", - "name": "well A01", - "attributes": { - "well": { - "column": {"id": "1"}, - "row": {"id": "A"} - } - }, - "nodes": [ + "name": "nuclei", + "type": "multiscale", + "id": "000002", + "path": {"type": "zarr", "format": "relative", "href": "./nuclei"}, + "traits": [ { - "type": "collection", - "name": "A01_acq0", - "attributes": { - "acquisition": {"id": "acq_0"} - }, - "nodes": [ - { - "id": "A01_0", - "type": "multiscale", - "name": "A01_0", - "path": { - "type": "zarr", - "path": "./A/01/001.img" - } - }, - { - "type": "multiscale", - "name": "A01_0_nuclei", - "path": { - "type": "zarr", - "path": "./A/01/001_nuclei.img" - }, - "attributes": { - "labels": { - "source": ["A01_0"] - } - } - } - ] + "type": "https://viewer-a.example.com/settings/Layer", + "visible": true, + "opacity": 1.0, + "shader": "void main() { emitRGB(vec3(0.0, 0.0, toNormalized(getDataValue()))); }" }, { - "type": "collection", - "name": "A01_acq1", - "attributes": { - "acquisition": {"id": "acq_1"} - }, - "nodes": [ - { - "id": "A01_1", - "type": "multiscale", - "name": "A01_1", - "path": { - "type": "zarr", - "path": "./A/01/002.img" - } - }, - { - "type": "multiscale", - "name": "A01_1_nuclei", - "path": { - "type": "zarr", - "path": "./A/01/002_nuclei.img" - }, - "attributes": { - "labels": { - "source": [{"id": "A01_1"}] - } - } - } - ] + "type": "https://viewer-b.example.org/rendering/Display", + "colormap": "blue", + "contrastLimits": [110, 3800], + "gamma": 1.0, + "blending": "additive" } ] } @@ -1023,75 +1334,44 @@ This serves as an example that wells can consist of collections, not just multis } ``` -While inlined plate collections are shown above for simplicity, an on-disk plate collection could still refer to separate on-disk collections within each well that carry a `well` attribute. - -#### `bioformats2raw.layout` metadata - -The `bioformats2raw.layout` metadata is replaced by this proposal. -A series of images can now be represented as a collection of multiscale images. - -## Extensions - -This section describes how existing classes and class attributes can be extended -in a controlled manner, enabling custom functionality while maintaining interoperability. - -Extensions to the specification can be made at defined extension points, and -they are declared using a prefix naming scheme. - -### Extension points - -The extension system defines several points at which OME-Zarr can be extended -while maintaining a common framework. These include node types, attribute keys, -path types, coordinate transformation types, and coordinate system axis -types. Each extension point is identified and declared in the -corresponding sections of this proposal. - - -### Naming scheme - -Extension identifiers follow a prefixed vs unprefixed convention: - -- **Unprefixed identifiers** are reserved for the core specification and can only be added or modified through the RFC process. -- **Prefixed identifiers** (separated by `:`) can be freely introduced by custom extensions without requiring an RFC. The prefix identifies the user or organization that introduces and maintains the extension. Prefixes SHOULD be registered in a central registry (a Github repository under the `ome` organization). Registration of a prefix claims maintainership for that prefix and provides a discoverable location for the specification of custom extensions. -- The `ome:` prefix is reserved for official extensions that have not yet been incorporated into the core specification. - -This naming scheme applies uniformly to all extension points. Implementations that do not recognize a prefixed extension point SHOULD treat the referenced value as opaque and MAY skip it or display it with a generic representation. - -Custom-prefixed keys can also be used to add additional sub-keys or behavior to existing unprefixed keys. -This can be thought of as a way of achieving inheritance. -For example, the `well` key in a `Node`'s `attributes` could be specialized by a `fractal:well` key that adds additional sub-keys or alters behavior. -It is out-of-scope of this RFC to fully define the inheritance behavior. -That is left to be defined on a case-by-case basis for individual key specifications and may be standardized in a future RFC. +## Type tiers -### Examples - -#### A `Path` with an extension `type` value - -```jsonc - "path": { - "type": "myorg:zip", - "path": "./mylab.zip" - } -``` +All object types that may be found in a OME-Zarr JSON file ultimately belong to one of two categories: **built-in types**, which are defined by the OME-Zarr specification, and **custom types**, which are defined by [extensions](#extensions). -#### A `coordinateTransformation` with an extension `type` value +Built-in types are identified by a specification-defined keyword, while custom types are identified by an identifier derived from the identifier of the extension that defines them, as explained in the [“Extensions” section](#extension-and-custom-type-identifiers). -```jsonc -"coordinateTransformations": [ - { - "type": "translation", - "translation": [0, 0, 100], - ... - }, - { - "type": "myorg:nonlinear", - ... - } -] -``` +Built-in types can further be subdivided into **core types**, **recommended types**, and **optional**. As the name suggests, the difference between the two categories lies in what is required from OME-Zarr implementations: a compliant OME-Zarr implementation MUST support all core types, SHOULD support recommended types, and MAY support optional types. +Custom types are initially all OPTIONAL. However, future revisions of the specification may promote a particular custom type to the level of a recommended type, if there is agreement within the community (through the specification revision process, that is RFCs) that the custom type is well designed, useful, and widespread enough to warrant such a promotion. +The following table recapitulates the currently defined built-in types along with their assigned tier. +| Type name | Type of… | Tier | Origin | +| - | - | - | - | +| `collection` | Node | Core type | This RFC | +| `multiscale` | Node | Core type | This RFC | +| `zarr` | Path | Core type | This RFC | +| `json` | Path | Core type | This RFC | +| `scene` | Trait | Core type | This RFC | +| `array` | Data object (multiscale `data` field) | Core type | This RFC | +| `index` | Axis | Core type | RFC-5 | +| `space` | Axis | Core type | RFC-5 | +| `time` | Axis | Core type | RFC-5 | +| `channel` | Axis | Core type | RFC-5 | +| `coordinate` | Axis | Core type | RFC-5 | +| `identity` | Coordinate transformation | Core type | RFC-5 | +| `scale` | Coordinate transformation | Core type | RFC-5 | +| `translation` | Coordinate transformation | Core type | RFC-5 | +| `mapAxis` | Coordinate transformation | Recommended type | RFC-5 | +| `affine` | Coordinate transformation | Recommended type | RFC-5 | +| `rotation` | Coordinate transformation | Recommended type | RFC-5 | +| `sequence` | Coordinate transformation | Optional | RFC-5 | +| `displacements` | Coordinate transformation | Optional | RFC-5 | +| `coordinates` | Coordinate transformation | Optional | RFC-5 | +| `bijection` | Coordinate transformation | Optional | RFC-5 | +| `byDimension` | Coordinate transformation | Optional | RFC-5 | + +Any future RFC that defines its own types MUST explicitly state for each type whether it is intended that implementations MUST support it (categorizing it as a core type), SHOULD support it (categorizing it as a recommended type), or MAY support it (categorizing it as an optional type). A type defined without such an explicit statement is inferred to be an optional type. ## User stories @@ -1156,7 +1436,7 @@ that is defined by coordinate systems and coordinate transformations. Since the relationships between images are already defined in a graph-like schema as proposed in this RFC, the transformations metadata can be represented as a specialized collection -with coordinate systems and transformations as attributes of the collection and nodes. +with coordinate systems and transformations as traits of the collection and its nodes. In a way, coordinate transformations and systems simply become a subset of the more general collection concept. @@ -1175,7 +1455,7 @@ There are multiple areas where it would be interesting to extend this spec. There are [ongoing discussions](https://github.com/ome/ngff/pull/137) about whether individual microscope fields of view (ie. well) should be stored as individual OME-Zarr images or as a single OME-Zarr image and how one would represent [different processing intermediates in a plate](https://forum.image.sc/t/how-to-build-hcs-zarrs-with-multiple-image-types-per-fov/119329). In these contexts, the current HCS spec lacks flexibility to get additional metadata about how images in a well are related and what a viewer should do with them. For example, depending on whether an OME-Zarr image in a well is an individual field of view of a given acquisition, a second acquisition of the same region in a plate or an image derived from a given processing operation, the optimal viewer default on whether to show or not show multiple images at once will vary. -A flexible metadata field like `attributes` would allow us to better define such image metadata. +A flexible mechanism for attaching metadata to nodes, such as `traits`, would allow us to better define such image metadata. A more flexible HCS collection system could also allow to provide advanced metadata on well positions [when wells have different sizes](https://github.com/ome/ome-zarr-py/issues/240) or address other edge-cases in the current HCS configuration. @@ -1206,8 +1486,7 @@ While the segmentation would now be published on its own, it could still be publ When processing images in the OME-Zarr format, a diversity of derived data like segmentation, probability maps, meshes, tables and other formats can be generated. This proposal does not intend to provide a specification to all these datatypes, but to define the metadata of how related data in Zarr or other formats can be linked to OME-Zarr images. -Because there is already a specification for labels in the spec, the label definition is broadened by this spec. -For other datatypes like tables, [past proposals](https://github.com/ome/ngff/pull/64) have focused on how tables can be serialised to OME-Zarr. +For past proposals that have proposed adding datatypes such as [tables](https://github.com/ome/ngff/pull/64) have focused on how tables can be serialised to OME-Zarr. As these proposals did not proceed to become part of the OME-Zarr spec, different implementers have built their own sub-specs for tables (see e.g. the [ngio table definition](https://fractal-analytics-platform.github.io/ngio/v0.3.2/table_specs/overview/) coming from the Fractal project or the [label table](https://mobie.github.io/specs/mobie_spec.html#table-data) in MoBIE). While future proposals and extensions may define datatypes like tables more strictly, this proposal offers a general way to make such additional data types discoverable. @@ -1225,106 +1504,17 @@ For example, [this table](https://docs.google.com/spreadsheets/d/1t5xB0p0zd2-a6y ![MoBIE grid view](./assets/mobie_grid_view.jpg) -#### Example: A grid view gallery +Note: this use case can be served by local Collections but will most benefit +from remote references, which has been deferred to a subsequent RFC. -A gallery view could also be represented within the proposed collection JSON as shown in the below example. +### 11. Training crops cut from non-OME-Zarr sources -Note that the grid view is modelled here as a collection of collections, where the collection at each grid position includes the raw EM image and the mitochondria segmentation label mask image. +Machine-learning pipelines train on small patches ("crops") cut from published datasets. The sources may be OME-Zarr images, but are often archived in other formats such as TIFF, MRC, HDF5 and N5. A data preparation pipeline downloads the files, cuts the planned crops at several resolution levels, writes them as OME-Zarr images, and finally tensorizes them for training. +For reproducibility, four questions should be answerable from the metadata: how the image was made (software, environment, parameters, time); which file the voxels came from, and whether that file has changed since; where in the source volume each crop sits, at each level; and which parts of the image hold data and what was deliberately omitted. -Also note some MoBIE specific attributes: - -- `"mobie:grid": "true"` specifies that the data should be laid out in a grid. - -```jsonc -{ - "ome": { - "version": "0.x", - "type": "collection", - "name": "openorganelle-mito-gallery", - "attributes": { - "mobie:grid": "true" - }, - "nodes": [ - { - "name": "jrc_hela-3", - "type": "collection", - "nodes": [ - { - "name": "fibsem-uint16", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_hela-3/jrc_hela-3.zarr/em/fibsem-uint16", - } - }, - { - "name": "mito_seg", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_hela-3/jrc_hela-3.zarr/labels/mito_seg", - }, - "attributes": { - "labels": {} - } - } - ] - }, - { - "name": "jrc_macrophage-2", - "type": "collection", - "nodes": [ - { - "name": "fibsem-uint16", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_macrophage-2/jrc_macrophage-2.zarr/em/fibsem-uint16" - } - }, - { - "name": "mito_seg", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_macrophage-2/jrc_macrophage-2.zarr/labels/mito_seg" - }, - "attributes": { - "labels": {} - } - } - ] - }, - { - "name": "jrc_jurkat-1", - "type": "collection", - "nodes": [ - { - "name": "fibsem-uint16", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_jurkat-1/jrc_jurkat-1.zarr/em/fibsem-uint16" - } - }, - { - "name": "mito_seg", - "type": "multiscale", - "path": { - "type": "zarr", - "path": "https://janelia-cosem-datasets.s3.amazonaws.com/jrc_jurkat-1/jrc_jurkat-1.zarr/labels/mito_seg" - }, - "attributes": { - "labels": {} - } - } - ] - } - ] - } -} -``` +The first question is answered by a provenance record on the node, such as the [`provenance:` Zarr convention](https://github.com/BioImageTools/zarr-convention-provenance), which lists the steps that made it with their inputs and outputs as paths, URIs or identifiers. The other three are relationships, and a provenance record cannot express them: its references are strings, not references to declared objects with coordinate systems, so nothing ties "the file this image was cut from" to a frame or an extent, and nothing says that the raw image and its label share a frame other than a repeated coordinate-system name. +With this proposal the volume is written as a collection rather than as one image with nested labels. The raw image and its label are sibling multiscales placed in a shared coordinate system by the `scene` trait. Each image names the file it was cut from with a reference to a node that stands for that file; the file's own array index space is a coordinate system of that node, so the crop offset is a transform between two declared frames rather than a convention. The planned crops are nodes with an extent and a reference to the image, not copies of its bytes. The provenance record stays beside `ome` in the node's attributes and names the same nodes by their `id`, so a reader can join how a node was made with what it is to the other nodes. ## Other Examples @@ -1332,187 +1522,173 @@ The examples below demonstrate combinations of various features in this proposal. Further example can be found under https://github.com/normanrz/ngff-rfc8-collection-examples/. -### A multiscale group with a single, inlined resolution level -```jsonc -{ - "ome": { - "version": "0.x", - "type": "multiscale", - "name": "multiscales_example", - "id": "image_0", - "nodes": [ - { - "id": "s0", - "name": "s0", - "type": "singlescale", - "path": { - "type": "zarr", - "path": "./s0" - }, - "attributes": { - "coordinateTransformations": [ - { - "type": "scale", - "scale": [1, 1, 1], - "input": {"id": "s0"}, - "output": {"id": "physical"} - } - ] - } - } - ], - "attributes": { - "coordinateSystems": [ - { - "id": "physical", - "axes": [...] - } - ] - } - } -} -``` - ### A multiscale group with a single resolution level -The multiscale group contains the following metadata: ```jsonc { - "ome": { - "version": "0.x", - "type": "multiscale", - "name": "multiscales_example", - "id": "image_0", - "nodes": [ - { - "id": "s0", - "name": "s0", - "type": "singlescale", - "path": { - "type": "zarr", - "path": "./s0" - }, - } - ], - "attributes": { - "coordinateSystems": [ - { - "id": "physical", - "name": "The physical coordinate system", - "axes": [...] - } - ] + "ome": { + "version": "0.x", + "type": "multiscale", + "name": "multiscales_example", + "id": "000001", + "data": [ + { + "type": "array", + "path": { + "type": "zarr", + "format": "relative", + "href": "./s0" } - } + } + ], + "coordinateSystems": [ + { + "type": "coordinate_system", + "id": "000002", + "name": "physical", + "axes": [...] + } + ] + } } ``` -And the `zarr.json` at the location of the resolution level (`./s0/zarr.json`) contains the following metadata: +### A multiscale group with two resolution levels + ```jsonc { - "ome": { - "version": "0.x", - "type": "singlescale", - "name": "s0", - "id": "s0", - "attributes": { - "coordinateTransformations": [ - { - "type": "scale", - "scale": [1, 1, 1], - "input": {"id": "s0"}, - "output": { - "id": "physical", - "path": { - "type": "json", - "path": "../zarr.json" - } - } - } - ] + "ome": { + "version": "0.x", + "type": "multiscale", + "name": "multiscales_example", + "id": "000001", + "data": [ + { + "type": "array", + "path": { + "type": "zarr", + "format": "relative", + "href": "./s0" } - } + }, + { + "type": "array", + "path": { + "type": "zarr", + "format": "relative", + "href": "./s1" + }, + "downsamplingTransformations": [ + {"type": "scale", "scale": [1, 2, 2]}, + {"type": "translation", "translation": [0, 0.5, 0.5]} + ] + } + ], + "coordinateSystems": [ + { + "type": "coordinate_system", + "id": "000002", + "name": "physical", + "axes": [...] + } + ], + "coordinateTransformations": [ + { + "type": "scale", + "scale": [0.9, 0.45, 0.45], + "input": "000001", + "output": "000002" + } + ] + } } ``` ### A collection with a multiscale and a nested collection + ```jsonc { "ome": { "version": "0.x", "type": "collection", + "id": "000001", "name": "jrc_hela-1", "nodes": [ { "name": "raw", "type": "multiscale", + "id": "000002", "path": { "type": "zarr", - "path": "./raw", // a relative or absolute path + "format": "relative", + "href": "./raw", }, - "attributes": { - "example-viewer:settings": { + "traits": [ + { + "type": "example-viewer.org/ngff/settings", "isDisabled": true }, ... // arbitrary user-defined metadata - }, + } + ] }, { "name": "nested_collection", "type": "collection", + "id": "000003", "path": { "type": "json", - "path": "./nested_collection.json" + "format": "relative", + "href": "./nested_collection.json" } }, ... - ], - "attributes": { - ... - } + ] } } ``` ### A collection with an inlined multiscale + ```jsonc { "ome": { "version": "0.x", "type": "collection", + "id": "000001", "name": "example", "nodes": [ { "name": "raw", - "id": "raw", + "id": "000002", "type": "multiscale", - "nodes": [ + "data": [ { - "id": "raw_0", "name": "raw_0", - "type": "singlescale", + "type": "array", "path": { "type": "zarr", - "path": "./raw/0" + "format": "relative", + "href": "./raw/0" } } ], - "attributes": { - "coordinateTransformations": [ - { - "type": "scale", - "scale": [1, 1, 1], - "input": {"id": "raw_0"}, - "output": {"id": "physical"} - } - ], - "coordinateSystems": [ - { - "id": "physical", - "axes": [...] - } - ] - } + "coordinateTransformations": [ + { + "type": "scale", + "scale": [1, 1, 1], + "input": "000002", + "output": "000003" + } + ], + "coordinateSystems": [ + { + "type": "coordinate_system", + "id": "000003", + "name": "physical", + "axes": [...] + } + ] } ] } @@ -1609,12 +1785,12 @@ It is the responsibility of implementations to ensure consistency where required For reading, implementations SHOULD parse the metadata as available to the implementation from the user-supplied entry point in the OME-Zarr hierarchy. -### New Multiscale/Singlescale metadata +### New Multiscale/Array metadata -In an effort to unify the existing and new collection types of OME-Zarr, the Multiscale metadata has been changed to mirror the Collection metadata. -Still, it is a specialized node type because of its prevalence and semantic requirements with regards to its Singlescale children nodes. -The Singlescale metadata has been elevated to a first-class node type. -This also allows specifying images that only contain a single resolution level. +In an effort to unify the existing and new collection types of OME-Zarr, the Multiscale metadata has been changed to use the same Node interface as collections. +Still, it is a specialized node type because of its prevalence and its semantic requirements with regards to the `Array` objects in its `data` field. +Unlike a `collection`, a `multiscale` node is a leaf node: its `data` field contains `Array` objects, which are not nodes themselves. +A node type for images that only contain a single resolution level is deferred to a sub-RFC. These changes are breaking changes to the core of the OME-Zarr specification. @@ -1690,7 +1866,42 @@ To keep complexity manageable, we would need to heavily restrict which parts of This creates a lose-lose situation: JSON-LD experts may be confused by the deviations from standard JSON-LD, while users unfamiliar with JSON-LD would still need to learn both JSON-LD concepts and the OME-NGFF-specific extensions. The learning curve would be higher than with a purpose-built format, without corresponding benefits in return. -For these reasons, the RFC adopts a simpler custom format with a prefix-based naming scheme instead of JSON-LD. +For these reasons, the RFC adopts a simpler custom format and a custom type system which, while somewhat reminiscent of JSON-LD on some aspects (the `extension_manifest` is partially akin to a JSON-LD `@context`), is distinct enough not to mislead users into believing that OME-Zarr JSON files are actually JSON-LD files. + +### Custom types identified by prefixed keywords + +An initial version of this RFC proposed that third parties could extend the specification by (1) registering an extension prefix into a registry maintained by the community and (2) prepend the registered prefix to any type name they wish to create. + +This was abandoned in favour of (1) mandating that custom types be identified by an identifier that is derived from an _extension_ identifier, where the extension is itself declared in the _extension manifest_; and (2) recommending that extension identifiers (and therefore custom type identifiers) be URI-based. This better meets the [desired characteristics](#desired-characteristics-for-ome-zarrs-extensibility-mechanism) for OME-Zarr extensibility, as set forth in the June 2026 Heidelberg hackathon. + +### Prefixed attribute keys + +An initial version of this RFC proposed that third parties could append custom metadata to any node by adding prefixed keys to an `attributes` dictionary carried by every node, where the prefix has been previously registered into a registry maintained by the community (as for custom types, see previous section). + +This was abandoned in favour of the [trait](#traits) concept. + +### Subtyped node types + +An alternative to traits was to specialize nodes through subtypes, e.g. a `PlateCollection`, `WellCollection` or `SceneCollection` that extends `collection` and carries the additional fields directly on the node. +This has the appeal that the node type alone states what a node is, and that mutually exclusive specializations such as plate and well are exclusive by construction. + +However, real data often combines independent aspects, e.g. a well whose fields of view form a scene, or a segmentation derived from a remote image. +With subtypes, every such combination needs its own named type, and the number of types grows combinatorially with each new aspect. +Multiple inheritance could avoid naming every combination up front. +But it puts the fields of all parents into one namespace and needs rules for resolving conflicts between parents. +It also still requires a named type per combination, so done properly it ends up close to traits. +A single-inheritance hierarchy, on the other hand, forces arbitrary decisions, such as whether a well is a kind of scene or the other way round, that are hard to change later. + +Subtypes also degrade poorly. +A reader that does not know an extension subtype cannot interpret the node at all. +With traits, the node type stays a known core type, so the data can still be traversed and displayed while unknown traits are ignored. +Traits further allow partial support and modular validation: an implementation can support a subset of traits, and each trait is validated against its own schema. +Finally, previous versions of the specification already compose metadata on one group (`multiscales`, `labels`, `omero`), and traits keep that model. + +This was abandoned in favour of the [trait](#traits) concept, which is inspired by traits in Rust and comparable to interfaces in Java and extensions in STAC. +Node types describe structure (how a node is traversed) and traits describe meaning. +Exclusivity between traits has to be stated explicitly in the trait specifications. +Extensions may still define new node types for structures that the core node types do not cover.