From d7c0556029ab514fadedda40086f4d1de64efe42 Mon Sep 17 00:00:00 2001 From: jmoore Date: Thu, 7 Apr 2022 16:00:26 +0200 Subject: [PATCH 01/30] First draft of bioformats2raw.layout --- latest/index.bs | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/latest/index.bs b/latest/index.bs index 53723745..f52ca74a 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -100,6 +100,14 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +

+Transitional metadata is added to the specification with the +intention of removing it in the future. Implementations may be expected (MUST) or +encouraged (SHOULD) support the reading of the data, but writing will usually +be optional (MAY). Examples of transitional metadata include custom additions by +implementations that are later submitted as a formal specification. (See [[#bf2raw]]) +

+ Some of the JSON examples in this document include commments. However, these are only for clarity purposes and comments MUST NOT be included in JSON objects. @@ -241,9 +249,28 @@ keys as specified below for discovering certain types of data, especially images If part of [[#multiscale-md]], the length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data. +"bioformats2raw.layout" (transitional) {#bf2raw} +------------------------------------------------ + +[=Transitional=] "bioformats2raw.layout" metadata identifies a group which implicitly describes a series of images. +The need for the collection stems from the common "multi-image file" scenario in microscopy. Parsers like Bio-Formats +define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools. +In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping +layer. An upcoming NGFF specification will replace this layout with explicit metadata. + +Conforming groups: +- MUST have the value "3" for the "bioformats2raw.layout" key at the top of the hierarchy. +- MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...). +- MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml". + +Conforming readers: +- SHOULD parse all images. +- MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates. +- MAY ignore other groups or arrays under the root of the hierarchy. + "coordinateTransformations" metadata {#trafo-md} -------------------------------------- +------------------------------------------------ "coordinateTransformations" describe a series of transformations that map between two coordinate spaces (defined by "axes"). For example, to map a discrete data space of an array to the corresponding physical space. From 8ee02d1e60e216496ccd0ffb30f80892057269e7 Mon Sep 17 00:00:00 2001 From: jmoore Date: Fri, 8 Apr 2022 12:11:20 +0200 Subject: [PATCH 02/30] Add layout example --- .../examples/valid_strict/bioformats2raw_layout.json | 3 +++ latest/index.bs | 10 ++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 latest/examples/valid_strict/bioformats2raw_layout.json diff --git a/latest/examples/valid_strict/bioformats2raw_layout.json b/latest/examples/valid_strict/bioformats2raw_layout.json new file mode 100644 index 00000000..c5eadb8a --- /dev/null +++ b/latest/examples/valid_strict/bioformats2raw_layout.json @@ -0,0 +1,3 @@ +{ + "bioformats2raw.layout" : 3 +} \ No newline at end of file diff --git a/latest/index.bs b/latest/index.bs index f52ca74a..d48c9ea1 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -258,8 +258,14 @@ define a strict, stable ordering of the images in a single container that can be In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping layer. An upcoming NGFF specification will replace this layout with explicit metadata. -Conforming groups: -- MUST have the value "3" for the "bioformats2raw.layout" key at the top of the hierarchy. +Conforming groups MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy: + +
+path: examples/valid_strict/bioformats2raw_layout.json
+highlight: json
+
+ +Additionally: - MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...). - MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml". From ee1545552bac2758e55574f6c55cedbda2d15624 Mon Sep 17 00:00:00 2001 From: jmoore Date: Wed, 20 Apr 2022 08:24:41 +0200 Subject: [PATCH 03/30] Improve wording of "SHOULD parse multiple images", thanks to Ilan see: https://github.com/ome/ngff/issues/104#issuecomment-1092706651 --- latest/index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index d48c9ea1..d7031960 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -270,8 +270,8 @@ Additionally: - MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml". Conforming readers: -- SHOULD parse all images. -- MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates. +- SHOULD detect the presence of more than one image and make users aware of the fact; +- MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates; - MAY ignore other groups or arrays under the root of the hierarchy. From c8e98e4c390d1a2d12f33377e2a21e37a4567247 Mon Sep 17 00:00:00 2001 From: jmoore Date: Wed, 20 Apr 2022 08:26:06 +0200 Subject: [PATCH 04/30] Clarify contents of METADATA.ome.xml, thanks to Melissa --- latest/index.bs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index d7031960..b38b3c86 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -266,8 +266,9 @@ highlight: json Additionally: -- MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...). -- MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml". +- MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...); +- MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml"; +- if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. Conforming readers: - SHOULD detect the presence of more than one image and make users aware of the fact; From 6403d883aa1ca559cc0b37368b5f78a84245e22f Mon Sep 17 00:00:00 2001 From: jmoore Date: Thu, 21 Apr 2022 12:12:11 +0200 Subject: [PATCH 05/30] Add schema & test for bf2raw metadata --- .../bioformats2raw_layout.json | 0 latest/index.bs | 2 +- latest/tests/test_validation.py | 15 +++++++++++++++ 3 files changed, 16 insertions(+), 1 deletion(-) rename latest/examples/{valid_strict => bf2raw}/bioformats2raw_layout.json (100%) diff --git a/latest/examples/valid_strict/bioformats2raw_layout.json b/latest/examples/bf2raw/bioformats2raw_layout.json similarity index 100% rename from latest/examples/valid_strict/bioformats2raw_layout.json rename to latest/examples/bf2raw/bioformats2raw_layout.json diff --git a/latest/index.bs b/latest/index.bs index b38b3c86..b9fd8765 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -261,7 +261,7 @@ layer. An upcoming NGFF specification will replace this layout with explicit met Conforming groups MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy: 
-path: examples/valid_strict/bioformats2raw_layout.json
+path: examples/bf2raw/bioformats2raw_layout.json
 highlight: json
diff --git a/latest/tests/test_validation.py b/latest/tests/test_validation.py index 3a6a5761..51ff7b05 100644 --- a/latest/tests/test_validation.py +++ b/latest/tests/test_validation.py @@ -7,11 +7,15 @@ from jsonschema.exceptions import ValidationError +with open('schemas/bf2raw.schema') as f: + bf2raw_schema = json.load(f) with open('schemas/image.schema') as f: image_schema = json.load(f) with open('schemas/strict_image.schema') as f: strict_image_schema = json.load(f) + schema_store = { + bf2raw_schema['$id']: bf2raw_schema, image_schema['$id']: image_schema, strict_image_schema['$id']: strict_image_schema, } @@ -19,7 +23,9 @@ resolver = RefResolver.from_schema(image_schema, store=schema_store) validator = Draft202012Validator(image_schema, resolver=resolver) strict_validator = Draft202012Validator(strict_image_schema, resolver=resolver) +bf2raw_validator = Draft202012Validator(bf2raw_schema, resolver=resolver) +bf2raw_files = list(glob.glob("examples/bf2raw/*.json")) valid_strict_files = list(glob.glob("examples/valid_strict/*.json")) valid_files = list(glob.glob("examples/valid/*.json")) invalid_files = list(glob.glob("examples/invalid/*.json")) @@ -31,6 +37,15 @@ def ids(files): return [str(x).split("/")[-1][0:-5] for x in files] +@pytest.mark.parametrize( + "testfile", bf2raw_files, ids=ids(bf2raw_files)) +def test_bf2raw(testfile): + with open(testfile) as f: + data = ''.join(line for line in f if not line.lstrip().startswith('//')) + jsondata = json.loads(data) + bf2raw_validator.validate(jsondata) + + @pytest.mark.parametrize( "testfile", valid_strict_files, ids=ids(valid_strict_files)) def test_valid_strict(testfile): From 890e8a281daac0bf00ed3e32a864f24d1fc72168 Mon Sep 17 00:00:00 2001 From: jmoore Date: Thu, 21 Apr 2022 15:45:31 +0200 Subject: [PATCH 06/30] Add missing schema file --- latest/schemas/bf2raw.schema | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 latest/schemas/bf2raw.schema diff --git a/latest/schemas/bf2raw.schema b/latest/schemas/bf2raw.schema new file mode 100644 index 00000000..834aee24 --- /dev/null +++ b/latest/schemas/bf2raw.schema @@ -0,0 +1,14 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://ngff.openmicroscopy.org/latest/schemas/bf2raw.schema", + "title": "NGFF container produced by bioformats2raw", + "description": "JSON from OME-NGFF .zattrs", + "type": "object", + "properties": { + "bioformats2raw.layout": { + "description": "The top-level identifier metadata added by bioformats2raw", + "type": "number", + "enum": [3] + } + } +} From 2b67a36515b8eaeab643f217167e6cb8ad4d9bcc Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Wed, 11 May 2022 12:41:08 +0200 Subject: [PATCH 07/30] Add applicable versions statement --- latest/index.bs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index ca2104f7..41128c55 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -256,17 +256,18 @@ If part of [[#multiscale-md]], the length of "axes" MUST be equal to the number [=Transitional=] "bioformats2raw.layout" metadata identifies a group which implicitly describes a series of images. The need for the collection stems from the common "multi-image file" scenario in microscopy. Parsers like Bio-Formats define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools. -In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping -layer. An upcoming NGFF specification will replace this layout with explicit metadata. -Conforming groups MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy: +In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping layer. +The bioformats2raw layout can be found in NGFF versions v0.2, v0.3, and v0.4. An upcoming NGFF specification will replace +this layout with explicit metadata. 
 path: examples/bf2raw/bioformats2raw_layout.json
 highlight: json
-Additionally: +Conforming groups: +- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy: - MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...); - MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml"; - if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. From 31d34c3faf9a520d7fa46e32a6973906a42ac3f9 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:32:05 +0200 Subject: [PATCH 08/30] Update text with suggestions --- latest/index.bs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 41128c55..d21d9586 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -267,11 +267,15 @@ highlight: json Conforming groups: -- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy: +- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy; - MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...); -- MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml"; +- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which + MUST adhere to the specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html; - if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. +Please note that the "plate" key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not +possible to mix collections of images with plates at present. + Conforming readers: - SHOULD detect the presence of more than one image and make users aware of the fact; - MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates; From d44a0668bd530ffedf612f8c8a90d7d9d143a4a2 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:35:03 +0200 Subject: [PATCH 09/30] Add bf2raw examples config --- latest/examples/bf2raw/.config.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 latest/examples/bf2raw/.config.json diff --git a/latest/examples/bf2raw/.config.json b/latest/examples/bf2raw/.config.json new file mode 100644 index 00000000..2525328c --- /dev/null +++ b/latest/examples/bf2raw/.config.json @@ -0,0 +1,3 @@ +{ + "schema": "schemas/bf2raw.schema" +} From 7574d228377b2e554421704a8d8a4aa56a7ac17d Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:46:04 +0200 Subject: [PATCH 10/30] Add test to find missing configs --- latest/tests/test_validation.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/latest/tests/test_validation.py b/latest/tests/test_validation.py index 9e441fad..8c13b113 100644 --- a/latest/tests/test_validation.py +++ b/latest/tests/test_validation.py @@ -89,3 +89,17 @@ def test_run(suite): resolver = RefResolver.from_schema(suite.schema, store=schema_store) validator = Validator(suite.schema, resolver=resolver) suite.validate(validator) + + +def test_example_configs(): + """ + Test that all example folders have a config file + """ + missing = [] + for subdir in os.walk("examples"): + has_examples = glob.glob(f"{subdir[0]}/*.json") + has_config = glob.glob(f"{subdir[0]}/.config.json") + if has_examples and not has_config: + missing.append(subdir[0]) + if missing: + raise Exception(f"Directories missing configs: {missing}") From ff5d7ec16f84933678a31829dfd26930694e4c75 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:57:09 +0200 Subject: [PATCH 11/30] Split subitems to pass linting --- latest/index.bs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 4cbc2662..d5dc002c 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -269,8 +269,9 @@ highlight: json Conforming groups: - MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy; - MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...); -- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which - MUST adhere to the specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html; +- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which: + - MUST adhere to the OME-XML specification but + - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html; - if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. Please note that the "plate" key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not From e2119e5ccd9c97da8717c53b889f377c39d121a9 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:57:16 +0200 Subject: [PATCH 12/30] Add graphical layout representation --- latest/index.bs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/latest/index.bs b/latest/index.bs index d5dc002c..d7500d49 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -274,6 +274,17 @@ Conforming groups: - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html; - if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. +
+series.ome.zarr           # One converted fileset from bioformats2raw
+    ├── .zgroup
+    ├── .zattrs               # Contains "bioformats2raw.layout" metadata
+    ├── OME                   # Special group for containing OME metadata
+    │   └── METADATA.ome.xml  # OME-XML file stored within the Zarr fileset
+    ├── 0                     # First image in the collection
+    ├── 1                     # Second image in the collection
+    └── ...
+
+ Please note that the "plate" key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not possible to mix collections of images with plates at present. From 4fcc045e12caa18f1cd51aa27b4aa6da8c168550 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Mon, 30 May 2022 12:59:12 +0200 Subject: [PATCH 13/30] Fix missing whitespace --- latest/index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/latest/index.bs b/latest/index.bs index d7500d49..5a2727e9 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -275,7 +275,7 @@ Conforming groups: - if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers. 
-series.ome.zarr           # One converted fileset from bioformats2raw
+series.ome.zarr               # One converted fileset from bioformats2raw
     ├── .zgroup
     ├── .zattrs               # Contains "bioformats2raw.layout" metadata
     ├── OME                   # Special group for containing OME metadata

From 57acc23fc67f367ea6d0d3bb65a3cb7769f400ba Mon Sep 17 00:00:00 2001
From: Melissa Linkert 
Date: Tue, 5 Jul 2022 15:54:25 -0500
Subject: [PATCH 14/30] Add "series" attribute in "OME" group under
 bioformats2raw.layout

Documents the current state of https://github.com/glencoesoftware/bioformats2raw/pull/157
---
 latest/examples/bf2raw/ome.json |  3 +++
 latest/index.bs                 | 13 ++++++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 latest/examples/bf2raw/ome.json

diff --git a/latest/examples/bf2raw/ome.json b/latest/examples/bf2raw/ome.json
new file mode 100644
index 00000000..be7e9ed6
--- /dev/null
+++ b/latest/examples/bf2raw/ome.json
@@ -0,0 +1,3 @@
+{
+  "series" : [ "0", "1" ]
+}
diff --git a/latest/index.bs b/latest/index.bs
index 5a2727e9..ba0fc50d 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -272,13 +272,23 @@ Conforming groups:
 - SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
   - MUST adhere to the OME-XML specification but
   - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html;
-- if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers.
+- if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers;
+- if "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+  - MUST contain a "series" attribute. "series" MUST be a list of string objects, each of which is a path to an image group.
+    The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
+
+
+path: examples/bf2raw/ome.json
+highlight: json
+

 
 
 series.ome.zarr               # One converted fileset from bioformats2raw
     ├── .zgroup
     ├── .zattrs               # Contains "bioformats2raw.layout" metadata
     ├── OME                   # Special group for containing OME metadata
+    │   ├── .zgroup
+    │   ├── .zattrs           # Contains "series" metadata
     │   └── METADATA.ome.xml  # OME-XML file stored within the Zarr fileset
     ├── 0                     # First image in the collection
     ├── 1                     # Second image in the collection
@@ -290,6 +300,7 @@ possible to mix collections of images with plates at present.
 
 Conforming readers:
 - SHOULD detect the presence of more than one image and make users aware of the fact;
+- MAY use the "series" attribute in the "OME" group to determine a list of valid groups;
 - MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates;
 - MAY ignore other groups or arrays under the root of the hierarchy.
 

From 5eca16930bdb8f8fff34ffd52df796f4906db5bc Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Mon, 18 Jul 2022 13:17:16 -0500
Subject: [PATCH 15/30] Update the MUST/SHOULD semantics

---
 latest/index.bs | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index ba0fc50d..d5d6b2b9 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -268,14 +268,18 @@ highlight: json
 
 Conforming groups:
 - MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
-- MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...);
 - SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
   - MUST adhere to the OME-XML specification but
+  - MUST use `` elements and
   - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html;
-- if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers;
-- if "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
-  - MUST contain a "series" attribute. "series" MUST be a list of string objects, each of which is a path to an image group.
+
+Additionally:
+- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+  - MAY contain a "series" attribute. "series" MUST be a list of string objects, each of which is a path to an image group.
     The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
+- If if "OME/METADATA.ome.xml" or the "series" attribute do not exist:
+  - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
+- Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 
 
 path: examples/bf2raw/ome.json

From cf4e04c16cc7dda695ce511cacf4f895e20e4d50 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Wed, 14 Sep 2022 11:42:03 +0200
Subject: [PATCH 16/30] Fix doubly indented bullets

---
 latest/index.bs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index d5d6b2b9..00eb87ba 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -267,18 +267,21 @@ highlight: json
 

 
 Conforming groups:
+
 - MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
 - SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
-  - MUST adhere to the OME-XML specification but
-  - MUST use `` elements and
-  - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html;
+    - MUST adhere to the OME-XML specification but
+    - MUST use `` elements and
+    - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html;
 
 Additionally:
+
 - If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
-  - MAY contain a "series" attribute. "series" MUST be a list of string objects, each of which is a path to an image group.
-    The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
+    - MAY contain a "series" attribute.
+    - "series" MUST be a list of string objects, each of which is a path to an image group.
+    - The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
 - If if "OME/METADATA.ome.xml" or the "series" attribute do not exist:
-  - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
+    - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 
 

From 89c322d5fef37a84d557d6539e69eb7a0988836b Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Wed, 14 Sep 2022 11:46:40 +0200
Subject: [PATCH 17/30] Make minimum spec a link

---
 latest/index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 00eb87ba..0c7949be 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -271,8 +271,8 @@ Conforming groups:
 - MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
 - SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
     - MUST adhere to the OME-XML specification but
-    - MUST use `` elements and
-    - MAY make use of the minimum specification available at https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html;
+    - MUST use `` elements as opposed to ``, `` or ``;
+    - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
 
 Additionally:
 

From 369143776f8dbd6451f25b96d17b8ee2de2c0dc0 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Wed, 14 Sep 2022 11:59:23 +0200
Subject: [PATCH 18/30] Add no-toc sections

---
 latest/index.bs | 43 +++++++++++++++++++++++++------------------
 1 file changed, 25 insertions(+), 18 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 0c7949be..51d4b529 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -261,34 +261,21 @@ In order to capture that information within an OME-NGFF dataset, `bioformats2raw
 The bioformats2raw layout can be found in NGFF versions v0.2, v0.3, and v0.4. An upcoming NGFF specification will replace
 this layout with explicit metadata.
 
+
+
Attributes

+
 
 path: examples/bf2raw/bioformats2raw_layout.json
 highlight: json
 

 
-Conforming groups:
-
-- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
-- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
-    - MUST adhere to the OME-XML specification but
-    - MUST use `` elements as opposed to ``, `` or ``;
-    - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
-
-Additionally:
-
-- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
-    - MAY contain a "series" attribute.
-    - "series" MUST be a list of string objects, each of which is a path to an image group.
-    - The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
-- If if "OME/METADATA.ome.xml" or the "series" attribute do not exist:
-    - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
-- Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
-
 
 path: examples/bf2raw/ome.json
 highlight: json
 

 
+
Layout

+
 
 series.ome.zarr               # One converted fileset from bioformats2raw
     ├── .zgroup
@@ -302,6 +289,26 @@ series.ome.zarr               # One converted fileset from bioformats2raw
     └── ...
 

 
+
Details

+
+Conforming groups:
+
+- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
+- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
+    - MUST adhere to the OME-XML specification but
+    - MUST use `` elements as opposed to ``, `` or ``;
+    - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
+
+Additionally:
+
+- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+    - MAY contain a "series" attribute.
+    - "series" MUST be a list of string objects, each of which is a path to an image group.
+    - The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
+- If if "OME/METADATA.ome.xml" or the "series" attribute do not exist:
+    - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
+- Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
+
 Please note that the "plate" key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
 possible to mix collections of images with plates at present.
 

From 499caeeebc3f645dccb30851a160722ac8c5784e Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Wed, 14 Sep 2022 12:24:47 +0200
Subject: [PATCH 19/30] Re-arrange and add more text

---
 latest/index.bs | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 51d4b529..732150cf 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -261,21 +261,10 @@ In order to capture that information within an OME-NGFF dataset, `bioformats2raw
 The bioformats2raw layout can be found in NGFF versions v0.2, v0.3, and v0.4. An upcoming NGFF specification will replace
 this layout with explicit metadata.
 
-
-
Attributes

-
-
-path: examples/bf2raw/bioformats2raw_layout.json
-highlight: json
-

-
-
-path: examples/bf2raw/ome.json
-highlight: json
-

-
 
Layout

 
+Typical Zarr layout produced by running `bioformats2raw` on a fileset that contains more than image (series > 1):
+
 
 series.ome.zarr               # One converted fileset from bioformats2raw
     ├── .zgroup
@@ -289,6 +278,21 @@ series.ome.zarr               # One converted fileset from bioformats2raw
     └── ...
 

 
+
Attributes

+
+The top-level `.zattrs` file must contain the `bioformats2raw.layout` key:
+
+path: examples/bf2raw/bioformats2raw_layout.json
+highlight: json
+

+
+The `.zattrs` file within the OME group may contain the "series" key:
+
+
+path: examples/bf2raw/ome.json
+highlight: json
+

+
 
Details

 
 Conforming groups:

From c7582e558ef775ad22cde4864fbe2f50fe151537 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 15 Sep 2022 11:24:54 +0200
Subject: [PATCH 20/30] Make changes based on feedback from Will

---
 latest/index.bs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 732150cf..335dc6e3 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -308,8 +308,8 @@ Additionally:
 - If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
     - MAY contain a "series" attribute.
     - "series" MUST be a list of string objects, each of which is a path to an image group.
-    - The order of the paths MUST match the order of both the "multiscales" metadata and the "Image" elements in "OME/METADATA.ome.xml".
-- If if "OME/METADATA.ome.xml" or the "series" attribute do not exist:
+    - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
+- If "OME/METADATA.ome.xml" or the "series" attribute do not exist:
     - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 
@@ -317,8 +317,8 @@ Please note that the "plate" key takes precedence and parsing of such datasets s
 possible to mix collections of images with plates at present.
 
 Conforming readers:
-- SHOULD detect the presence of more than one image and make users aware of the fact;
-- MAY use the "series" attribute in the "OME" group to determine a list of valid groups;
+- SHOULD make users aware of the presence of more than one image (i.e. SHOULD NOT default to only opening the first image);
+- MAY use the "series" attribute in the "OME" group to determine a list of valid groups to display;
 - MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates;
 - MAY ignore other groups or arrays under the root of the hierarchy.
 

From 399b70b4e0709e16be6fc79e365b0cbb74d9d670 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 15 Sep 2022 11:33:35 +0200
Subject: [PATCH 21/30] Add bf2raw plate example

---
 ...{bioformats2raw_layout.json => image.json} |  0
 latest/examples/bf2raw/plate.json             | 21 +++++++++++++++++++
 latest/index.bs                               | 14 +++++++++----
 3 files changed, 31 insertions(+), 4 deletions(-)
 rename latest/examples/bf2raw/{bioformats2raw_layout.json => image.json} (100%)
 create mode 100644 latest/examples/bf2raw/plate.json

diff --git a/latest/examples/bf2raw/bioformats2raw_layout.json b/latest/examples/bf2raw/image.json
similarity index 100%
rename from latest/examples/bf2raw/bioformats2raw_layout.json
rename to latest/examples/bf2raw/image.json
diff --git a/latest/examples/bf2raw/plate.json b/latest/examples/bf2raw/plate.json
new file mode 100644
index 00000000..af80bbad
--- /dev/null
+++ b/latest/examples/bf2raw/plate.json
@@ -0,0 +1,21 @@
+{
+  "bioformats2raw.layout" : 3,
+  "plate" : {
+    "columns" : [ {
+      "name" : "1"
+    } ],
+    "name" : "Plate Name 0",
+    "wells" : [ {
+      "path" : "A/1",
+      "rowIndex" : 0,
+      "columnIndex" : 0
+    } ],
+    "field_count" : 1,
+    "rows" : [ {
+      "name" : "A"
+    } ],
+    "acquisitions" : [ {
+      "id" : 0
+    } ],
+    "version" : "0.4"
+  }
\ No newline at end of file
diff --git a/latest/index.bs b/latest/index.bs
index 335dc6e3..e3940d3a 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -282,7 +282,16 @@ series.ome.zarr               # One converted fileset from bioformats2raw
 
 The top-level `.zattrs` file must contain the `bioformats2raw.layout` key:
 
-path: examples/bf2raw/bioformats2raw_layout.json
+path: examples/bf2raw/image.json
+highlight: json
+

+
+If the top-level group represents a plate, the `bioformats2raw.layout` metadata will be present but
+the "plate" key key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
+possible to mix collections of images with plates at present.
+
+
+path: examples/bf2raw/plate.json
 highlight: json
 

 
@@ -313,9 +322,6 @@ Additionally:
     - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 
-Please note that the "plate" key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
-possible to mix collections of images with plates at present.
-
 Conforming readers:
 - SHOULD make users aware of the presence of more than one image (i.e. SHOULD NOT default to only opening the first image);
 - MAY use the "series" attribute in the "OME" group to determine a list of valid groups to display;

From 740a11b814f55574772995a85373b8ab9802c62d Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 15 Sep 2022 14:18:48 +0200
Subject: [PATCH 22/30] Add schema for ome series

---
 latest/examples/bf2raw/plate.json               |  3 ++-
 latest/examples/ome/.config.json                |  3 +++
 .../{bf2raw/ome.json => ome/series-2.json}      |  0
 latest/index.bs                                 |  2 +-
 latest/schemas/ome.schema                       | 17 +++++++++++++++++
 5 files changed, 23 insertions(+), 2 deletions(-)
 create mode 100644 latest/examples/ome/.config.json
 rename latest/examples/{bf2raw/ome.json => ome/series-2.json} (100%)
 create mode 100644 latest/schemas/ome.schema

diff --git a/latest/examples/bf2raw/plate.json b/latest/examples/bf2raw/plate.json
index af80bbad..bd98a16e 100644
--- a/latest/examples/bf2raw/plate.json
+++ b/latest/examples/bf2raw/plate.json
@@ -18,4 +18,5 @@
       "id" : 0
     } ],
     "version" : "0.4"
-  }
\ No newline at end of file
+  }
+}
diff --git a/latest/examples/ome/.config.json b/latest/examples/ome/.config.json
new file mode 100644
index 00000000..8a611ccf
--- /dev/null
+++ b/latest/examples/ome/.config.json
@@ -0,0 +1,3 @@
+{
+    "schema": "schemas/ome.schema"
+}
diff --git a/latest/examples/bf2raw/ome.json b/latest/examples/ome/series-2.json
similarity index 100%
rename from latest/examples/bf2raw/ome.json
rename to latest/examples/ome/series-2.json
diff --git a/latest/index.bs b/latest/index.bs
index e3940d3a..c1e0275b 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -298,7 +298,7 @@ highlight: json
 The `.zattrs` file within the OME group may contain the "series" key:
 
 
-path: examples/bf2raw/ome.json
+path: examples/ome/series-2.json
 highlight: json
 

 
diff --git a/latest/schemas/ome.schema b/latest/schemas/ome.schema
new file mode 100644
index 00000000..bd600a2a
--- /dev/null
+++ b/latest/schemas/ome.schema
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ngff.openmicroscopy.org/latest/schemas/ome.schema",
+  "title": "NGFF group produced by bioformats2raw to contain OME metadata",
+  "description": "JSON from OME-NGFF OME/.zattrs linked to an OME-XML file",
+  "type": "object",
+  "properties": {
+    "series": {
+      "description": "An array of the same length and the same order as the images defined in the OME-XML",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minContains": 1
+    }
+  }
+}

From 1f91482de0b9571be641292e73931e55ed0b1f19 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Mon, 19 Sep 2022 19:03:32 +0200
Subject: [PATCH 23/30] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Melissa Linkert 
Co-authored-by: Sébastien Besson 
---
 latest/index.bs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index c1e0275b..b991e82e 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -104,7 +104,7 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
 

 Transitional metadata is added to the specification with the
 intention of removing it in the future. Implementations may be expected (MUST) or
-encouraged (SHOULD) support the reading of the data, but writing will usually
+encouraged (SHOULD) to support the reading of the data, but writing will usually
 be optional (MAY). Examples of transitional metadata include custom additions by
 implementations that are later submitted as a formal specification. (See [[#bf2raw]])
 

@@ -263,7 +263,7 @@ this layout with explicit metadata.
 
 
Layout

 
-Typical Zarr layout produced by running `bioformats2raw` on a fileset that contains more than image (series > 1):
+Typical Zarr layout produced by running `bioformats2raw` on a fileset that contains more than one image (series > 1):
 
 
 series.ome.zarr               # One converted fileset from bioformats2raw
@@ -278,7 +278,7 @@ series.ome.zarr               # One converted fileset from bioformats2raw
     └── ...
 

 
-
Attributes

+
Attributes

 
 The top-level `.zattrs` file must contain the `bioformats2raw.layout` key:
 
@@ -287,7 +287,7 @@ highlight: json
 

 
 If the top-level group represents a plate, the `bioformats2raw.layout` metadata will be present but
-the "plate" key key takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
+the "plate" key MUST also be present, takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
 possible to mix collections of images with plates at present.
 
 

From 861227b38b02183f1d9a438ee5e84746d6930ec9 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 22 Sep 2022 08:24:10 +0200
Subject: [PATCH 24/30] Apply to v0.4 only

---
 latest/index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index b991e82e..78052cd1 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -258,8 +258,8 @@ The need for the collection stems from the common "multi-image file" scenario in
 define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools.
 
 In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping layer.
-The bioformats2raw layout can be found in NGFF versions v0.2, v0.3, and v0.4. An upcoming NGFF specification will replace
-this layout with explicit metadata.
+The bioformats2raw layout has been added to v0.4 as a transitional specification to specify filesets that already exist
+in the wild. An upcoming NGFF specification will replace this layout with explicit metadata.
 
 
Layout

 

From 8e612ef97449e1572a9389f3e38bfa81589876d3 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 22 Sep 2022 08:28:58 +0200
Subject: [PATCH 25/30] Re-iterate plate precedence without
 OME/METADATA.ome.xml

---
 latest/index.bs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 78052cd1..4fe84c52 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -315,10 +315,11 @@ Conforming groups:
 Additionally:
 
 - If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
-    - MAY contain a "series" attribute.
-    - "series" MUST be a list of string objects, each of which is a path to an image group.
-    - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
+    - MAY contain a "series" attribute. If so:
+        - "series" MUST be a list of string objects, each of which is a path to an image group.
+        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
 - If "OME/METADATA.ome.xml" or the "series" attribute do not exist:
+    - existing "plate" metadata will take precedence if it exists, or
     - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 

From a0919beb2840ca3f7cbee369d2cd38a008c978a2 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 22 Sep 2022 08:35:48 +0200
Subject: [PATCH 26/30] Backport latest/bf2raw to 0.4

---
 0.4/examples/bf2raw/.config.json |  3 ++
 0.4/examples/bf2raw/image.json   |  3 ++
 0.4/examples/bf2raw/plate.json   | 22 ++++++++
 0.4/examples/ome/.config.json    |  3 ++
 0.4/examples/ome/series-2.json   |  3 ++
 0.4/index.bs                     | 86 ++++++++++++++++++++++++++++++++
 0.4/schemas/bf2raw.schema        | 14 ++++++
 0.4/schemas/ome.schema           | 17 +++++++
 8 files changed, 151 insertions(+)
 create mode 100644 0.4/examples/bf2raw/.config.json
 create mode 100644 0.4/examples/bf2raw/image.json
 create mode 100644 0.4/examples/bf2raw/plate.json
 create mode 100644 0.4/examples/ome/.config.json
 create mode 100644 0.4/examples/ome/series-2.json
 create mode 100644 0.4/schemas/bf2raw.schema
 create mode 100644 0.4/schemas/ome.schema

diff --git a/0.4/examples/bf2raw/.config.json b/0.4/examples/bf2raw/.config.json
new file mode 100644
index 00000000..2525328c
--- /dev/null
+++ b/0.4/examples/bf2raw/.config.json
@@ -0,0 +1,3 @@
+{
+    "schema": "schemas/bf2raw.schema"
+}
diff --git a/0.4/examples/bf2raw/image.json b/0.4/examples/bf2raw/image.json
new file mode 100644
index 00000000..c5eadb8a
--- /dev/null
+++ b/0.4/examples/bf2raw/image.json
@@ -0,0 +1,3 @@
+{
+  "bioformats2raw.layout" : 3
+}
\ No newline at end of file
diff --git a/0.4/examples/bf2raw/plate.json b/0.4/examples/bf2raw/plate.json
new file mode 100644
index 00000000..bd98a16e
--- /dev/null
+++ b/0.4/examples/bf2raw/plate.json
@@ -0,0 +1,22 @@
+{
+  "bioformats2raw.layout" : 3,
+  "plate" : {
+    "columns" : [ {
+      "name" : "1"
+    } ],
+    "name" : "Plate Name 0",
+    "wells" : [ {
+      "path" : "A/1",
+      "rowIndex" : 0,
+      "columnIndex" : 0
+    } ],
+    "field_count" : 1,
+    "rows" : [ {
+      "name" : "A"
+    } ],
+    "acquisitions" : [ {
+      "id" : 0
+    } ],
+    "version" : "0.4"
+  }
+}
diff --git a/0.4/examples/ome/.config.json b/0.4/examples/ome/.config.json
new file mode 100644
index 00000000..8a611ccf
--- /dev/null
+++ b/0.4/examples/ome/.config.json
@@ -0,0 +1,3 @@
+{
+    "schema": "schemas/ome.schema"
+}
diff --git a/0.4/examples/ome/series-2.json b/0.4/examples/ome/series-2.json
new file mode 100644
index 00000000..be7e9ed6
--- /dev/null
+++ b/0.4/examples/ome/series-2.json
@@ -0,0 +1,3 @@
+{
+  "series" : [ "0", "1" ]
+}
diff --git a/0.4/index.bs b/0.4/index.bs
index a0c3f83d..34de5cc3 100644
--- a/0.4/index.bs
+++ b/0.4/index.bs
@@ -99,6 +99,14 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
 “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in
 [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
+

+Transitional metadata is added to the specification with the
+intention of removing it in the future. Implementations may be expected (MUST) or
+encouraged (SHOULD) to support the reading of the data, but writing will usually
+be optional (MAY). Examples of transitional metadata include custom additions by
+implementations that are later submitted as a formal specification. (See [[#bf2raw]])
+

+
 Some of the JSON examples in this document include commments. However, these are only for
 clarity purposes and comments MUST NOT be included in JSON objects.
 
@@ -240,6 +248,84 @@ keys as specified below for discovering certain types of data, especially images
 
 If part of [[#multiscale-md]], the length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data.
 
+"bioformats2raw.layout" (transitional) {#bf2raw}
+------------------------------------------------
+
+[=Transitional=] "bioformats2raw.layout" metadata identifies a group which implicitly describes a series of images.
+The need for the collection stems from the common "multi-image file" scenario in microscopy. Parsers like Bio-Formats
+define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools.
+
+In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping layer.
+The bioformats2raw layout has been added to v0.4 as a transitional specification to specify filesets that already exist
+in the wild. An upcoming NGFF specification will replace this layout with explicit metadata.
+
+
Layout

+
+Typical Zarr layout produced by running `bioformats2raw` on a fileset that contains more than one image (series > 1):
+
+
+series.ome.zarr               # One converted fileset from bioformats2raw
+    ├── .zgroup
+    ├── .zattrs               # Contains "bioformats2raw.layout" metadata
+    ├── OME                   # Special group for containing OME metadata
+    │   ├── .zgroup
+    │   ├── .zattrs           # Contains "series" metadata
+    │   └── METADATA.ome.xml  # OME-XML file stored within the Zarr fileset
+    ├── 0                     # First image in the collection
+    ├── 1                     # Second image in the collection
+    └── ...
+

+
+
Attributes

+
+The top-level `.zattrs` file must contain the `bioformats2raw.layout` key:
+
+path: examples/bf2raw/image.json
+highlight: json
+

+
+If the top-level group represents a plate, the `bioformats2raw.layout` metadata will be present but
+the "plate" key MUST also be present, takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
+possible to mix collections of images with plates at present.
+
+
+path: examples/bf2raw/plate.json
+highlight: json
+

+
+The `.zattrs` file within the OME group may contain the "series" key:
+
+
+path: examples/ome/series-2.json
+highlight: json
+

+
+
Details

+
+Conforming groups:
+
+- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
+- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
+    - MUST adhere to the OME-XML specification but
+    - MUST use `` elements as opposed to ``, `` or ``;
+    - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
+
+Additionally:
+
+- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+    - MAY contain a "series" attribute. If so:
+        - "series" MUST be a list of string objects, each of which is a path to an image group.
+        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
+- If "OME/METADATA.ome.xml" or the "series" attribute do not exist:
+    - existing "plate" metadata will take precedence if it exists, or
+    - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
+- Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
+
+Conforming readers:
+- SHOULD make users aware of the presence of more than one image (i.e. SHOULD NOT default to only opening the first image);
+- MAY use the "series" attribute in the "OME" group to determine a list of valid groups to display;
+- MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates;
+- MAY ignore other groups or arrays under the root of the hierarchy.
 
 "coordinateTransformations" metadata {#trafo-md}
 -------------------------------------
diff --git a/0.4/schemas/bf2raw.schema b/0.4/schemas/bf2raw.schema
new file mode 100644
index 00000000..834aee24
--- /dev/null
+++ b/0.4/schemas/bf2raw.schema
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ngff.openmicroscopy.org/latest/schemas/bf2raw.schema",
+  "title": "NGFF container produced by bioformats2raw",
+  "description": "JSON from OME-NGFF .zattrs",
+  "type": "object",
+  "properties": {
+    "bioformats2raw.layout": {
+      "description": "The top-level identifier metadata added by bioformats2raw",
+      "type": "number",
+      "enum": [3]
+    }
+  }
+}
diff --git a/0.4/schemas/ome.schema b/0.4/schemas/ome.schema
new file mode 100644
index 00000000..bd600a2a
--- /dev/null
+++ b/0.4/schemas/ome.schema
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ngff.openmicroscopy.org/latest/schemas/ome.schema",
+  "title": "NGFF group produced by bioformats2raw to contain OME metadata",
+  "description": "JSON from OME-NGFF OME/.zattrs linked to an OME-XML file",
+  "type": "object",
+  "properties": {
+    "series": {
+      "description": "An array of the same length and the same order as the images defined in the OME-XML",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minContains": 1
+    }
+  }
+}

From 59719273573446facb1a639a4242a501186bbd32 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 22 Sep 2022 19:41:15 +0200
Subject: [PATCH 27/30] Re-word the 'series' section

---
 0.4/index.bs    | 11 ++++++-----
 latest/index.bs | 11 ++++++-----
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/0.4/index.bs b/0.4/index.bs
index 34de5cc3..2df0d380 100644
--- a/0.4/index.bs
+++ b/0.4/index.bs
@@ -310,14 +310,15 @@ Conforming groups:
     - MUST use `` elements as opposed to ``, `` or ``;
     - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
 
-Additionally:
+Additionally, the logic for finding the Zarr group for each image follows the following logic:
 
-- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+- If "plate" metadata is present, images MUST be located at the defined location.
+    - Matching "series" metadata as described next MAY be provided for tools that are unaware of the "plate" specification.
+- If the "OME" Zarr group exists, it:
     - MAY contain a "series" attribute. If so:
         - "series" MUST be a list of string objects, each of which is a path to an image group.
-        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
-- If "OME/METADATA.ome.xml" or the "series" attribute do not exist:
-    - existing "plate" metadata will take precedence if it exists, or
+        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml" if provided.
+- If the "series" attribute does not exist and no "plate" is present:
     - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 
diff --git a/latest/index.bs b/latest/index.bs
index 4fe84c52..631f6d88 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -312,14 +312,15 @@ Conforming groups:
     - MUST use `` elements as opposed to ``, `` or ``;
     - MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
 
-Additionally:
+Additionally, the logic for finding the Zarr group for each image follows the following logic:
 
-- If "OME/METADATA.ome.xml" is present, "OME" MUST be a Zarr group which:
+- If "plate" metadata is present, images MUST be located at the defined location.
+    - Matching "series" metadata as described next MAY be provided for tools that are unaware of the "plate" specification.
+- If the "OME" Zarr group exists, it:
     - MAY contain a "series" attribute. If so:
         - "series" MUST be a list of string objects, each of which is a path to an image group.
-        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml".
-- If "OME/METADATA.ome.xml" or the "series" attribute do not exist:
-    - existing "plate" metadata will take precedence if it exists, or
+        - The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml" if provided.
+- If the "series" attribute does not exist and no "plate" is present:
     - separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
 - Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
 

From 88fd0420e62c71223d1b306e3e81e170a8318d90 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Thu, 22 Sep 2022 21:21:08 +0200
Subject: [PATCH 28/30] Make plate/series link a "SHOULD"

---
 0.4/index.bs    | 2 +-
 latest/index.bs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/0.4/index.bs b/0.4/index.bs
index 2df0d380..5a7b196f 100644
--- a/0.4/index.bs
+++ b/0.4/index.bs
@@ -313,7 +313,7 @@ Conforming groups:
 Additionally, the logic for finding the Zarr group for each image follows the following logic:
 
 - If "plate" metadata is present, images MUST be located at the defined location.
-    - Matching "series" metadata as described next MAY be provided for tools that are unaware of the "plate" specification.
+    - Matching "series" metadata (as described next) SHOULD be provided for tools that are unaware of the "plate" specification.
 - If the "OME" Zarr group exists, it:
     - MAY contain a "series" attribute. If so:
         - "series" MUST be a list of string objects, each of which is a path to an image group.
diff --git a/latest/index.bs b/latest/index.bs
index 631f6d88..c57809a6 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -315,7 +315,7 @@ Conforming groups:
 Additionally, the logic for finding the Zarr group for each image follows the following logic:
 
 - If "plate" metadata is present, images MUST be located at the defined location.
-    - Matching "series" metadata as described next MAY be provided for tools that are unaware of the "plate" specification.
+    - Matching "series" metadata (as described next) SHOULD be provided for tools that are unaware of the "plate" specification.
 - If the "OME" Zarr group exists, it:
     - MAY contain a "series" attribute. If so:
         - "series" MUST be a list of string objects, each of which is a path to an image group.

From 7b7c43f3016e9731246be8f549ce6b49e17a4c69 Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Mon, 26 Sep 2022 15:16:41 +0200
Subject: [PATCH 29/30] Add 'transitional' to 'omero' spec

---
 0.4/index.bs    | 6 +++---
 latest/index.bs | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/0.4/index.bs b/0.4/index.bs
index 5a7b196f..69e418ff 100644
--- a/0.4/index.bs
+++ b/0.4/index.bs
@@ -402,10 +402,10 @@ if not datasets:
     datasets = [x["path"] for x in multiscales[0]["datasets"]]
 ```
 
-"omero" metadata {#omero-md}
-----------------------------
+"omero" metadata (transitional) {#omero-md}
+-------------------------------------------
 
-Information specific to the channels of an image and how to render it
+[=Transitional=] information specific to the channels of an image and how to render it
 can be found under the "omero" key in the group-level metadata:
 
 ```json
diff --git a/latest/index.bs b/latest/index.bs
index c57809a6..f19c0d94 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -405,10 +405,10 @@ if not datasets:
     datasets = [x["path"] for x in multiscales[0]["datasets"]]
 ```
 
-"omero" metadata {#omero-md}
-----------------------------
+"omero" metadata (transitional) {#omero-md}
+-------------------------------------------
 
-Information specific to the channels of an image and how to render it
+[=Transitional=] information specific to the channels of an image and how to render it
 can be found under the "omero" key in the group-level metadata:
 
 ```json

From 106c3010dcb4079eb0a69868a11cc5943f942fdf Mon Sep 17 00:00:00 2001
From: Josh Moore 
Date: Mon, 26 Sep 2022 15:16:48 +0200
Subject: [PATCH 30/30] Add 0.4.1 changelog

---
 0.4/index.bs    | 5 +++++
 latest/index.bs | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/0.4/index.bs b/0.4/index.bs
index 69e418ff..e441720b 100644
--- a/0.4/index.bs
+++ b/0.4/index.bs
@@ -694,6 +694,11 @@ Version History {#history}
       Description
     
   
+  
+    0.4.1
+    2022-09-26
+    transitional metadata for image collections ("bioformats2raw.layout")
+  
   
     0.4.0
     2022-02-08
diff --git a/latest/index.bs b/latest/index.bs
index f19c0d94..2dff9985 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -697,6 +697,11 @@ Version History {#history}
       Description
     
   
+  
+    0.4.1
+    2022-09-26
+    transitional metadata for image collections ("bioformats2raw.layout")
+  
   
     0.4.0
     2022-02-08