ome / ome/ngff

Clarification of whether top-level fields in spec are optional or required

Open
#183 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement question
Dominant language
Python
Stars
171
Forks
75
Avg merge
2d 3h
Merged PRs (30d)
20

Description

In reading the spec, it is helpful to know

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in RFC 2119.

However these keywords seem to only be used for the inner fields and seem to be missing for the top-level fields. It was not very clear to me whether (or which of) multiscales, axes, or coordinateTransformations are REQUIRED at the top-level for the root .zattrs of an OME-NGFF (Image) in v0.4.

The following text appears in the spec but does not use the keywords:

├── .zattrs               # Group level attributes are stored in the .zattrs file and include
│                         # "multiscales" and "omero" (see below).

Metadata about an image can be found under the "multiscales" key in the group-level metadata.

"multiscales" contains a list of dictionaries where each entry describes a multiscale image.

I guess the statement "can be found" means "can always be found" but using the keywords here would eliminate this guessing. It also seems that the answer differs based on whether the Zarr store conforms to the Image vs Plate schema.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the v0.4 Image schema text around the group-level .zattrs, multiscales, axes, and coordinateTransformations fields, then compare it with the Plate schema. Update the specification so top-level requirements are explicit using RFC 2119 keywords, and ensure the Image-versus-Plate distinction is clear.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.