proposal: stable codes for spec rules, in a shared registry?

Open
  • Is something wrong?
#646 12 comments 9 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Domain
documentation

Research direction

Start by comparing the linked ngff-zarr rule-reference table with yaozarrs’ prototype rules.toml and its cited test_rules.py check. The issue leaves the registry’s home, format, and governance open; done would mean agreeing on those choices and a small pilot area, with clear guidance for adding and retiring stable codes.

Written by the indexing model from the issue text.

Description

enhancement

hey folks, I've been working on something in yaozarrs that seems like it could be useful more broadly, so I wanted to float it (I mentioned this briefly on the pre-hackathon zoom 2 days ago).

I'd like to propose a shared set of stable codes for the normative statements in the spec and schemas .. that any implementation or test case could use. (I wasn't able to find any prior discussion of this, so apologies if I missed it)

My goal in yaozarrs was to raise a ValidationError for each normative statement or rule in the spec or schema, with a code that links to a URL on my documentation page, which in turn links to the exact line in the spec or schema that mandates it... kinda like a linter would. I think it would immediately help clarify confusion about where/why a given thing is invalid or not.

In [1]: v06.WellDef.model_validate({"images": [{"path": "0"}, {"path": "0", "acquisition": 1}]})
ValidationError: 1 validation error for WellDef
  Field of view paths must be unique. Duplicates: ['0']
  See https://imaging-formats.github.io/yaozarrs/rules/NGFF-WL-002/ [type=NGFF-WL-002, ...]

(those docs pages aren't published yet, it's still on a branch)

It seems like other projects are running into similar issues. German-BioImaging/oztest#46 is asking for descriptions of why a test case is invalid, and on German-BioImaging/oztest#50 it wasn't clear which rule a couple of cases were meant to test. ngff-zarr has something similar too... @thewtex has a table of 15 structural rules with stable identifiers like axis-count, shared between the python and typescript ports. So we're already starting to grow separate vocabularies for the same statements, and it seems like a good moment to see if we can share one.

I have a working prototype on this branch with 170 rules (164 from the spec and schemas for v0.4 to v0.6, plus 6 that are yaozarrs-specific), and I'm happy with it. A rule looks like this:

[rules.NGFF-WL-002]
slug = 'field-path-unique'
level = 'MUST'
summary = 'Field of view `path`s must be unique within a well.'
introduced = '0.4'

[[rules.NGFF-WL-002.sources]]
quote = 'MUST NOT be a duplicate of any other `path` in the `images` list.'
# where that quote appears in each spec version: [first line, last line]
lines = { "0.4" = [605, 606], "0.5" = [540, 541], "0.6" = [1680, 1680] }

A code stays the same across spec versions for as long as the requirement does. If the requirement changes, the old code gets retired and a new one gets added (e.g. v0.6 relaxed the allowed characters in a field of view path, so NGFF-WL-001 became NGFF-WL-010). Spec files are pinned to a commit and vendored, and a test checks that each quote is still at those lines.

I think the rules themselves could live in a structured file (toml, json, whatever) somewhere outside of yaozarrs... possibly here, or in ngff-spec, or in oztest (German-BioImaging/oztest#28 makes me think those may end up close together anyway). Implementations could then share the codes, and oztest cases could say which rule they test. There would be clear and simple guides about how a rule gets added, when a code has to change, permanence, etc. (what I have so far is a Claude skill, and I could imagine agentic skills like that helping with this too... e.g. proposing rule updates when a new spec version comes out)

Each rule on my branch also has a minimal failing example, but we could leave those out of a shared file and have each rule point at the oztest cases that exercise it instead.

My rules file only covers what yaozarrs checks so far. For a shared file, I think we'd want every normative statement that can be violated, even if nothing checks it yet (with stuff about reader/writer behavior marked as such). A test could flag any line with a keyword that isn't cited by a rule or explicitly skipped. None of this has merged, so the names and numbering are all up for grabs.

Thoughts? Where do you think this sort of thing would/should live? (here or related seems most natural) The upcoming Zurich hackathon seems like a good place to work on this together, and I'm happy to put together a PR for one small area beforehand if that makes it easier to look at.

cc @clbarnes @joshmoore @jo-mueller @kevinyamauchi @DragaDoncila

Dominant language
Python
Stars
180
Forks
81
Avg merge
5d 7h
Merged PRs (30d)
9

Getting set up

  • No Dockerfile or Docker Compose file
  • No pull request template
  • Read the contributing guide

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.

More from ome/ngff

All issues in ome/ngff

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.