Add some more clarifications

0.5/index.bs

@@ -158,11 +158,11 @@ 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
+hierarchy. In this file, the metadata MUST be 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.
+The version of the OME-Zarr Metadata MUST be denoted using a string in the `version` attribute within the `ome` namespace.
 
-The OME-Zarr Metadata version MUST be consistent within a hierarchy.
+The OME-Zarr Metadata version MUST be identical within all OME-Zarr metadata files hierarchy.
 
 ```json
 {
@@ -182,7 +182,7 @@ The OME-Zarr Metadata version MUST be consistent within a hierarchy.
 "axes" describes the dimensions of a physical coordinate space. It MUST be a list of dictionaries, where each dictionary describes a dimension (axis) and:
 - MUST contain the field "name" that gives the name for this dimension. The values MUST be unique across all "name" fields.
 - SHOULD contain the field "type". It SHOULD be one of "space", "time" or "channel", but MAY take other string values for custom axis types that are not part of this specification yet.
-- SHOULD contain the field "unit" to specify the physical unit of this dimension. The value SHOULD be one of the following strings, which are valid units according to UDUNITS-2.
+- SHOULD contain the field "unit" to specify the physical unit of this dimension. The value MAY be an arbitrary object, but SHOULD be one of the following strings, which are valid units according to UDUNITS-2.
     - Units for "space" axes: 'angstrom', 'attometer', 'centimeter', 'decimeter', 'exameter', 'femtometer', 'foot', 'gigameter', 'hectometer', 'inch', 'kilometer', 'megameter', 'meter', 'micrometer', 'mile', 'millimeter', 'nanometer', 'parsec', 'petameter', 'picometer', 'terameter', 'yard', 'yoctometer', 'yottameter', 'zeptometer', 'zettameter'
     - Units for "time" axes: 'attosecond', 'centisecond', 'day', 'decisecond', 'exasecond', 'femtosecond', 'gigasecond', 'hectosecond', 'hour', 'kilosecond', 'megasecond', 'microsecond', 'millisecond', 'minute', 'nanosecond', 'petasecond', 'picosecond', 'second', 'terasecond', 'yoctosecond', 'yottasecond', 'zeptosecond', 'zettasecond'
 
@@ -219,22 +219,22 @@ series.ome.zarr               # One converted fileset from bioformats2raw
 
 <h4 id="bf2raw-attributes" class="no-toc">Attributes</h4>
 
-The OME-Zarr Metadata in the top-level `zarr.json` file must contain the `bioformats2raw.layout` key:
+The OME-Zarr Metadata in the top-level `zarr.json` file MUST contain the `bioformats2raw.layout` key:
 <pre class=include-code>
 path: examples/bf2raw/image.json
 highlight: json
 </pre>
 
 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.
+the "plate" key MUST also be present, takes precedence and parsing of such datasets should follow [[#plate-md]].
+`bioformats2raw` datasets that represent a plate MUST NOT contain any other images.
 
 <pre class=include-code>
 path: examples/bf2raw/plate.json
 highlight: json
 </pre>
 
-The OME-Zarr Metadata in the `zarr.json` file within the OME group may contain the "series" key:
+The OME-Zarr Metadata in the `zarr.json` file within the OME group MAY contain the "series" key:
 
 <pre class=include-code>
 path: examples/ome/series-2.json
@@ -301,19 +301,23 @@ It is stored in a multiple resolution representation.
 
 Each "multiscales" dictionary MUST contain the field "axes", see [[#axes-md]].
 The length of "axes" must be between 2 and 5 and MUST be equal to the dimensionality of the zarr arrays storing the image data (see "datasets:path").
-The "axes" MUST contain 2 or 3 entries of "type:space" and MAY contain one additional entry of "type:time" and MAY contain one additional entry of "type:channel" or a null / custom type.
-The order of the entries MUST correspond to the order of dimensions of the zarr arrays. In addition, the entries MUST be ordered by "type" where the "time" axis must come first (if present), followed by the  "channel" or custom axis (if present) and the axes of type "space".
+"axes" MUST contain 2 or 3 entries of "type:space" and MAY contain one additional entry of "type:time" and MAY contain one additional entry of "type:channel" or a null / custom type.
+The order of the entries MUST correspond to the order of dimensions of the zarr arrays.
+In addition, the entries MUST be ordered by "type" where the "time" axis must come first (if present), followed by the  "channel" or custom axis (if present) and the axes of type "space".
 If there are three spatial axes where two correspond to the image plane ("yx") and images are stacked along the other (anisotropic) axis ("z"), the spatial axes SHOULD be ordered as "zyx".
 
 Each "multiscales" dictionary MUST contain the field "datasets", which is a list of dictionaries describing the arrays storing the individual resolution levels.
 Each dictionary in "datasets" MUST contain the field "path", whose value contains the path to the array for this resolution relative
 to the current zarr group. The "path"s MUST be ordered from largest (i.e. highest resolution) to smallest.
 
-Each "datasets" dictionary MUST have the same number of dimensions and MUST NOT have more than 5 dimensions. The number of dimensions and order MUST correspond to number and order of "axes".
+Each "datasets" dictionary MUST have the same number of dimensions and MUST NOT have more than 5 dimensions.
+The number of dimensions and order MUST correspond to number and order of "axes".
 Each dictionary in "datasets" MUST contain the field "coordinateTransformations", which contains a list of transformations that map the data coordinates to the physical coordinates (as specified by "axes") for this resolution level.
 The transformations are defined according to [[#trafo-md]]. The transformation MUST only be of type `translation` or `scale`.
-They MUST contain exactly one `scale` transformation that specifies the pixel size in physical units or time duration. If scaling information is not available or applicable for one of the axes, the value MUST express the scaling factor between the current resolution and the first resolution for the given axis, defaulting to 1.0 if there is no downsampling along the axis.
-It MAY contain exactly one `translation` that specifies the offset from the origin in physical units. If `translation` is given it MUST be listed after `scale` to ensure that it is given in physical coordinates.
+They MUST contain exactly one `scale` transformation that specifies the pixel size in physical units or time duration.
+If scaling information is not available or applicable for one of the axes, the value MUST express the scaling factor between the current resolution and the first resolution for the given axis, defaulting to 1.0 if there is no downsampling along the axis.
+It MAY contain exactly one `translation` that specifies the offset from the origin in physical units.
+If `translation` is given it MUST be listed after `scale` to ensure that it is given in physical coordinates.
 The length of the `scale` and `translation` array MUST be the same as the length of "axes".
 The requirements (only `scale` and `translation`, restrictions on order) are in place to provide a simple mapping from data coordinates to physical coordinates while being compatible with the general transformation spec.
 
@@ -571,6 +575,15 @@ Changelog
 0.6
 ---
 - Clarified that "axes" MUST be a list of dictionaries in section 2.1.
+- Clarified that OME-Zarr Metadata MUST be stored under the "ome" key in the
+  zarr attributes JSON in section 2.
+- Clarified that OME-Zarr version MUST be denoted using a string under the `version` attribute
+  in section 2.
+- Stipluate that the OME-Zarr metadata version must be "identical" (changed from "consistent")
+  within all OME-Zarr metadata files in a single hierarchy (section 2).
+- Clarified that units can be arbitrary objects (section 2.1)
+- Clarified that `bioformats2raw` datasets that represent a plate
+  must not contain other images (section 2.2).
 
 Implementations {#implementations}
 ==================================