From 5c6487298d697de2444b4c9bec27975beecb91df Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Wed, 20 Aug 2025 21:28:53 +0200 Subject: [PATCH 1/6] sync spec text with json examples --- index.bs | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index ffc7cf57..cd11288a 100644 --- a/index.bs +++ b/index.bs @@ -158,11 +158,12 @@ The "OME-Zarr Metadata" contains metadata keys as specified below for discovering certain types of data, especially images. The OME-Zarr Metadata is stored in the various `zarr.json` files throughout the above array -hierarchy. In this file, the metadata is stored under the namespaced key -`ome` in `attributes`. -The version of the OME-Zarr Metadata is denoted as a string in the `version` attribute within the `ome` namespace. +hierarchy. The OME-Zarr Metadata version MUST be consistent within a hierarchy. The top-level `ome` +group MUST contain a `version` key whose value MUST be a string specifying the version of the +metadata specification. -The OME-Zarr Metadata version MUST be consistent within a hierarchy. +In this file, the metadata is stored under the namespaced key +`ome` in `attributes`. ```json { @@ -423,9 +424,8 @@ associated with the `datasets` key MUST have the same number of entries (scale l In addition to the `multiscales` key, the OME-Zarr Metadata in this image-level `zarr.json` file SHOULD contain another key, `image-label`, whose value is also a JSON object. The `image-label` object stores information about the display colors, source image, and optionally, -further arbitrary properties of the label image. That `image-label` object SHOULD contain the following keys: first, a `colors` key, -whose value MUST be a JSON array describing color information for the unique label values. Second, a `version` key, whose value MUST be a -string specifying the version of the OME-Zarr `image-label` schema. +further arbitrary properties of the label image. That `image-label` object SHOULD contain a `colors` key, whose value MUST be a JSON array +describing color information for the unique label values. Conforming readers SHOULD display labels using the colors specified by the `colors` JSON array, as follows. This array contains one JSON object for each unique custom label. Each of these objects MUST contain the `label-value` key, whose value MUST be the integer @@ -486,9 +486,6 @@ case-insensitive filesystems (e.g. avoid using both `Aa` and `aA`). The `plate` dictionary SHOULD contain a `field_count` key whose value MUST be a positive integer defining the maximum number of fields per view across all wells. -The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the -name of the plate. - The `plate` dictionary MUST contain a `rows` key whose value MUST be a list of JSON objects defining the rows of the plate. Each row object defines the properties of the row at the index of the object in the list. Each row in the physical plate @@ -542,9 +539,6 @@ of any other `path` in the `images` list. If multiple acquisitions were performe it MUST contain an `acquisition` key whose value MUST be an integer identifying the acquisition which MUST match one of the acquisition JSON objects defined in the plate metadata (see #plate-md). -The `well` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the -version of the well specification. - For example the following JSON object defines a well with four fields of view. The first two fields of view were part of the first acquisition while the last two fields of view were part of the second acquisition. From 4be384eca123e213219057ed18fe4b39609aedc1 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Thu, 21 Aug 2025 12:18:52 +0200 Subject: [PATCH 2/6] sharpen description of top-level ome key requirements --- index.bs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index cd11288a..51a0f220 100644 --- a/index.bs +++ b/index.bs @@ -158,12 +158,13 @@ The "OME-Zarr Metadata" contains metadata keys as specified below for discovering certain types of data, especially images. The OME-Zarr Metadata is stored in the various `zarr.json` files throughout the above array -hierarchy. The OME-Zarr Metadata version MUST be consistent within a hierarchy. The top-level `ome` -group MUST contain a `version` key whose value MUST be a string specifying the version of the -metadata specification. +hierarchy. The OME-Zarr Metadata version MUST be consistent within a hierarchy. + +The group `attributes` MUST contain a key `ome`. The value of the `ome` key MUST be a JSON +object that MUST contain a `version` key, the value of which MUST be a string. In this file, the metadata is stored under the namespaced key -`ome` in `attributes`. +`ome` in `attributes`: ```json { From 7b7b77d39b99d1ac991adce11a833d90a4e6797d Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Mon, 25 Aug 2025 09:57:15 +0200 Subject: [PATCH 3/6] add permissive statement regarding extra keys Co-Authored-By: Davis Bennett --- index.bs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/index.bs b/index.bs index 51a0f220..aabd61c0 100644 --- a/index.bs +++ b/index.bs @@ -62,6 +62,20 @@ is represented here as it would appear locally but could equally be stored on a web server to be accessed via HTTP or in object storage like S3 or GCS. +Extra keys in JSON objects {#extra-keys} +---------------------------------------- + +Unless otherwise stated, a JSON object defined in this document MAY contain additional keys +beyond those enumerated in its definition. OME-Zarr Implementations MUST allow extra keys in +such JSON objects. This means that, when reading OME-Zarr data, the presence of an extra key +in such a JSON object MUST NOT be treated as an error. + +Whether an implementation ignores the extra keys or propagates them is up to that particular +implementation. It is recommended that implementations clearly declare how they handle extra +keys, with a particular emphasis on informing users in the context of irreversible operations. +For example, an implementation that resaves OME-Zarr data and ignores extra keys could implement +a routine that warns users when they attempt to resave OME-Zarr data with extra keys. + Images {#image-layout} ---------------------- From 70903c97eecd3804137fd8a67da940d751b3bdac Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Mon, 25 Aug 2025 10:02:55 +0200 Subject: [PATCH 4/6] moved statement up to document conventions --- index.bs | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/index.bs b/index.bs index aabd61c0..f0feb174 100644 --- a/index.bs +++ b/index.bs @@ -47,6 +47,21 @@ implementations that are later submitted as a formal specification. (See [[#bf2r Some of the JSON examples in this document include comments. However, these are only for clarity purposes and comments MUST NOT be included in JSON objects. +Extra keys in JSON objects +-------------------------- + +Unless otherwise stated, a JSON object defined in this document MAY contain additional keys +beyond those enumerated in its definition. OME-Zarr Implementations MUST allow extra keys in +such JSON objects. This means that, when reading OME-Zarr data, the presence of an extra key +in such a JSON object MUST NOT be treated as an error. + +Whether an implementation ignores the extra keys or propagates them is up to that particular +implementation. It is recommended that implementations clearly declare how they handle extra +keys, with a particular emphasis on informing users in the context of irreversible operations. +For example, an implementation that resaves OME-Zarr data and ignores extra keys could implement +a routine that warns users when they attempt to resave OME-Zarr data with extra keys. + + Storage format {#storage-format} ================================ @@ -62,20 +77,6 @@ is represented here as it would appear locally but could equally be stored on a web server to be accessed via HTTP or in object storage like S3 or GCS. -Extra keys in JSON objects {#extra-keys} ----------------------------------------- - -Unless otherwise stated, a JSON object defined in this document MAY contain additional keys -beyond those enumerated in its definition. OME-Zarr Implementations MUST allow extra keys in -such JSON objects. This means that, when reading OME-Zarr data, the presence of an extra key -in such a JSON object MUST NOT be treated as an error. - -Whether an implementation ignores the extra keys or propagates them is up to that particular -implementation. It is recommended that implementations clearly declare how they handle extra -keys, with a particular emphasis on informing users in the context of irreversible operations. -For example, an implementation that resaves OME-Zarr data and ignores extra keys could implement -a routine that warns users when they attempt to resave OME-Zarr data with extra keys. - Images {#image-layout} ---------------------- From 251fca92f95e4b621a6e01e4d50d9ecd7b48d0fc Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Mon, 25 Aug 2025 12:06:07 +0200 Subject: [PATCH 5/6] Make additional keys-hint more concise Co-Authored-By: David Stansby --- index.bs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index f0feb174..bb996b22 100644 --- a/index.bs +++ b/index.bs @@ -51,9 +51,8 @@ Extra keys in JSON objects -------------------------- Unless otherwise stated, a JSON object defined in this document MAY contain additional keys -beyond those enumerated in its definition. OME-Zarr Implementations MUST allow extra keys in -such JSON objects. This means that, when reading OME-Zarr data, the presence of an extra key -in such a JSON object MUST NOT be treated as an error. +beyond those enumerated in its definition. The presence of an additional key in such a JSON +object MUST NOT be treated as an error by implementations. Whether an implementation ignores the extra keys or propagates them is up to that particular implementation. It is recommended that implementations clearly declare how they handle extra From 75a7d9aeb5f5b3e500bb80a6b0d994019300500b Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Thu, 28 Aug 2025 15:28:15 +0200 Subject: [PATCH 6/6] remove statement about extra keys --- index.bs | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/index.bs b/index.bs index bb996b22..51a0f220 100644 --- a/index.bs +++ b/index.bs @@ -47,20 +47,6 @@ implementations that are later submitted as a formal specification. (See [[#bf2r Some of the JSON examples in this document include comments. However, these are only for clarity purposes and comments MUST NOT be included in JSON objects. -Extra keys in JSON objects --------------------------- - -Unless otherwise stated, a JSON object defined in this document MAY contain additional keys -beyond those enumerated in its definition. The presence of an additional key in such a JSON -object MUST NOT be treated as an error by implementations. - -Whether an implementation ignores the extra keys or propagates them is up to that particular -implementation. It is recommended that implementations clearly declare how they handle extra -keys, with a particular emphasis on informing users in the context of irreversible operations. -For example, an implementation that resaves OME-Zarr data and ignores extra keys could implement -a routine that warns users when they attempt to resave OME-Zarr data with extra keys. - - Storage format {#storage-format} ================================