diff --git a/.github/workflows/rfc-front-matter.yml b/.github/workflows/rfc-front-matter.yml new file mode 100644 index 000000000..b9ea49eca --- /dev/null +++ b/.github/workflows/rfc-front-matter.yml @@ -0,0 +1,33 @@ +name: "Validate RFC front matter" + +on: + workflow_dispatch: + push: + branches: ["main"] + pull_request: + branches: ["main"] + paths: + - "rfc/**" + - ".github/workflows/rfc-front-matter.yml" + +concurrency: + group: rfc-front-matter-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Install dependencies + run: pip install linkml pyyaml + + - name: Validate against rfc/schema/front_matter.yaml + run: python rfc/schema/validate.py diff --git a/_ext/document_authors.py b/_ext/document_authors.py new file mode 100644 index 000000000..daf4ae685 --- /dev/null +++ b/_ext/document_authors.py @@ -0,0 +1,92 @@ +import yaml +from docutils import nodes +from docutils.parsers.rst import Directive + +ORCID_ICON = "https://orcid.org/assets/vectors/orcid.logo.icon.svg" +GITHUB_ICON = "https://github.githubassets.com/favicons/favicon.svg" +EMAIL_ICON = "https://raw.githubusercontent.com/twbs/icons/main/icons/envelope-fill.svg" + + +def _icon_link(uri, src, alt): + """A hyperlink wrapping a small inline image.""" + ref = nodes.reference("", "", refuri=uri) + img = nodes.image( + uri=src, + alt=alt, + classes=["rfc-author-icon"], + ) + ref += img + return ref + + +class DocumentAuthors(Directive): + def run(self): + env = self.state.document.settings.env + src = env.doc2path(env.docname) + with open(src, encoding="utf-8") as f: + text = f.read() + + parts = text.split("---", 2) + if len(parts) < 3: + raise self.error("rfc-authors: no YAML front matter found") + meta = yaml.safe_load(parts[1]) or {} + + authors = meta.get("authors", []) + if not authors: + raise self.error("rfc-authors: no 'authors' in front matter") + + # Number unique affiliations in first-seen order + affils, order = {}, [] + for a in authors: + aff = a.get("affiliation") + if aff and aff not in affils: + order.append(aff) + affils[aff] = len(order) + + para = nodes.paragraph(classes=["rfc-authors"]) + for i, a in enumerate(authors): + if i: + para += nodes.Text(" and " if i == len(authors) - 1 else ", ") + + para += nodes.Text(a["name"]) + + aff = a.get("affiliation") + if aff: + para += nodes.superscript(text=str(affils[aff])) + + orcid = a.get("orcid") + if orcid: + uri = ( + orcid + if str(orcid).startswith("http") + else f"https://orcid.org/{orcid}" + ) + para += nodes.Text(" ") + para += _icon_link(uri, ORCID_ICON, "ORCID") + + gh = a.get("github") + if gh: + uri = gh if str(gh).startswith("http") else f"https://github.com/{gh}" + para += nodes.Text(" ") + para += _icon_link(uri, GITHUB_ICON, "GitHub") + + email = a.get("email") + if email: + uri = email if str(email).startswith("mailto:") else f"mailto:{email}" + para += nodes.Text(" ") + para += _icon_link(uri, EMAIL_ICON, "Email") + + result = [para] + + for aff in order: + p = nodes.paragraph(classes=["rfc-affiliation"]) + p += nodes.superscript(text=str(affils[aff])) + p += nodes.Text(" " + aff) + result.append(p) + + return result + + +def setup(app): + app.add_directive("document-authors", DocumentAuthors) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/_ext/rfc_status.py b/_ext/rfc_status.py new file mode 100644 index 000000000..a914ea0af --- /dev/null +++ b/_ext/rfc_status.py @@ -0,0 +1,395 @@ +import os +import posixpath +import yaml +from docutils import nodes +from docutils.parsers.rst import Directive +from sphinx import addnodes + +# Display-only labels for the state codes of the (non-normative) table under +# resources/rfc-status-codes. The code in an RFC's front matter stays the source +# of truth; this only spells it out for readers. +STATE_LABELS = { + "D1": "Initial idea", + "D2": "Initial idea", + "D3": "PR open", + "D4": "PR open", + "D5": "Editor decision", + "D6": "Closed", + "R1": "Under review", + "R2": "Under review", + "R3": "Replying to reviews", + "R4": "Replying to reviews", + "R5": "Under review", + "R6": "Under review", + "R7": "Under review", + "R8": "Replying to reviews", + "R9": "Withdrawn", + "S0": "Accepted; SPEC updates", + "S1": "Accepted; SPEC updates", + "S2": "Clarification", + "S3": "Implementation", + "S4": "Adopted", +} + +STATE_CODES_DOC = "/resources/rfc-status-codes/index" + + +def _read_front_matter(path): + try: + with open(path, encoding="utf-8") as f: + text = f.read() + except OSError: + return {} + parts = text.split("---", 2) + if len(parts) < 3: + return {} + try: + return yaml.safe_load(parts[1]) or {} + except yaml.YAMLError: + return {} + + +def _numbered_subdirs(base): + if not os.path.isdir(base): + return + for e in os.listdir(base): + p = os.path.join(base, e) + if os.path.isdir(p) and e != "index": + yield e, p + + +def _folder_sort_key(label): + """'1' -> (1, ''), '1b' -> (1, 'b'), so rounds sort after their round 1.""" + num = "".join(c for c in label if c.isdigit()) + suffix = "".join(c for c in label if not c.isdigit()) + return (int(num) if num else 0, suffix) + + +def _thread_stem(label): + """'1b' -> '1', '12c' -> '12'. Used to count threads, not documents.""" + i = len(label) + while i > 0 and label[i - 1].isalpha(): + i -= 1 + return label[:i] or label + + +def _collect_section(rfc_dir, section): + """Return list of (label, meta), sorted by folder key (round-aware).""" + base = os.path.join(rfc_dir, section) + rows = [] + for label, subdir in _numbered_subdirs(base): + index_path = os.path.join(subdir, "index.md") + if not os.path.isfile(index_path): + continue + rows.append((label, _read_front_matter(index_path))) + rows.sort(key=lambda r: _folder_sort_key(r[0])) + return rows + + +def _thread_count(rows): + return len({_thread_stem(label) for label, _ in rows}) + + +def _count_versions(rfc_dir): + base = os.path.join(rfc_dir, "versions") + return sum(1 for _ in _numbered_subdirs(base)) if os.path.isdir(base) else 0 + + +def _status_nodes(meta): + """The status line of an RFC, e.g. "S4 – Adopted (update implementations)". + + Everything comes from the RFC's front matter: `manual_status` holds the state + code, `status_note` an optional fragment explaining it. Editors set the code + by hand when they move an RFC along; it is never guessed here from the + reviews or responses that happen to be on disk. The code links to the table + of status codes; a code that is not in STATE_LABELS (say "N/A" for the + historical RFC-0) is shown without a label. + """ + code = str(meta.get("manual_status", "")).strip() + if not code: + return [] + result = [_doc_reference(code, STATE_CODES_DOC)] + label = STATE_LABELS.get(code.upper()) + if label: + result.append(nodes.Text(f" \u2013 {label}")) + note = str(meta.get("status_note", "")).strip() + if note: + result.append(nodes.Text(f" ({note})")) + return result + + +def _state_text(meta): + """The state as plain text, e.g. "S4 (Adopted)", for the RFC listing.""" + code = str(meta.get("manual_status", "")).strip() + if not code: + return "" + label = STATE_LABELS.get(code.upper()) + return f"{code} ({label})" if label else code + + +def _doc_reference(text, docname): + """Link to another page, resolved by the builder so the URL is always right.""" + return addnodes.pending_xref( + "", + nodes.inline("", text), + refdomain="std", + reftype="doc", + reftarget=docname, + refexplicit=True, + refwarn=True, + ) + + +class RFCStatus(Directive): + SECTION_LABELS = { + "reviews": ("Reviewer", "Review"), + "comments": ("Commenter", "Comment"), + "responses": ("Author", "Response"), + } + + def run(self): + env = self.state.document.settings.env + src = env.doc2path(env.docname) + rfc_dir = os.path.dirname(src) + central = _read_front_matter(src) + + reviews = _collect_section(rfc_dir, "reviews") + comments = _collect_section(rfc_dir, "comments") + responses = _collect_section(rfc_dir, "responses") + + all_dates = [ + str(m.get("date", "")) + for _, m in (reviews + comments + responses) + if m.get("date") + ] + last_update = max(all_dates) if all_dates else str(central.get("date", "")) + + result = [] + + status = _status_nodes(central) + if status: + line = nodes.paragraph(classes=["rfc-status-state"]) + line += nodes.strong("", nodes.Text("Status: ")) + line.extend(status) + result.append(line) + + reference_pr = str(central.get("reference_pr", "")).strip() + if reference_pr: + number = reference_pr.rstrip("/").rsplit("/", 1)[-1] + label = f"#{number}" if number.isdigit() else reference_pr + pr = nodes.paragraph(classes=["rfc-status-reference-pr"]) + pr += nodes.Text("Reference PR: ") + pr += nodes.reference("", label, refuri=reference_pr) + result.append(pr) + + summary = nodes.paragraph(classes=["rfc-status-summary"]) + summary += nodes.Text( + f"As of the last update, {last_update}: " + f"{_thread_count(comments)} comments, " + f"{_thread_count(reviews)} reviews, " + f"{_thread_count(responses)} responses, " + ) + result.append(summary) + result.append(nodes.title(text="Authors, editors, and endorsers")) + result.append(self._people_table(central)) + if reviews or comments or responses: + result.append(nodes.title(text="Reviews, comments, and responses")) + result.append( + self._activity_table( + reviews, comments, responses, posixpath.dirname(env.docname) + ) + ) + return result + + # ---- Table 1: Authors + Editors + Endorsers---- + + def _people_table(self, central): + cols = ["Role", "Name", "GitHub", "Institution", "Date", "Status"] + table, tbody = self._new_table(cols, (10, 22, 20, 22, 10, 16)) + for person in central.get("authors", []): + tbody += self._person_row(person, "Author") + for person in central.get("editors", []): + tbody += self._person_row(person, "Editor") + for person in central.get("endorsers", []): + tbody += self._person_row(person, "Endorser") + return table + + def _person_row(self, person, role): + row = nodes.row() + row += self._text_entry(role, "bold") + row += self._text_entry(person.get("name", "")) + gh = person.get("github") + row += self._github_entry([gh] if gh else []) + row += self._affiliation_entry( + [(person.get("affiliation", ""), person.get("affiliation_url"))] + ) + row += self._text_entry(str(person.get("date", ""))) + # Endorsers always read "endorse", linked to the endorsement document when + # a reference is given; everyone else shows their role as text. + if role == "Endorser": + reference = person.get("reference", "") + if reference: + row += self._linked_entry("endorse", reference) + else: + row += self._text_entry(person.get("role") or "endorse") + else: + row += self._text_entry(person.get("role", "")) + + return row + + # ---- Table 2: Reviews + Comments + Responses (one row per round) ---- + + def _activity_table(self, reviews, comments, responses, rfc_docdir): + cols = ["Link", "Name", "GitHub", "Institution", "Date", "Rec."] + table, tbody = self._new_table(cols, (12, 22, 18, 20, 12, 16)) + for section, rows in ( + ("reviews", reviews), + ("comments", comments), + ("responses", responses), + ): + _, link_label = self.SECTION_LABELS[section] + for label, meta in rows: + tbody += self._activity_row( + meta, + f"{link_label}\u00a0{label}", # non-breaking space + f"{rfc_docdir}/{section}/{label}/index", + ) + return table + + def _activity_row(self, meta, link_text, link_docname): + authors = meta.get("authors", []) + names = ", ".join(a.get("name", "") for a in authors if a.get("name")) + handles = [a["github"] for a in authors if a.get("github")] + affils = [] + for a in authors: + aff = a.get("affiliation") + if aff and aff not in [x for x, _ in affils]: + affils.append((aff, a.get("affiliation_url"))) + recommendation = str(meta.get("recommendation") or "").replace("_", " ") + + row = nodes.row() + row += self._doc_entry(link_text, link_docname) + row += self._text_entry(names) + row += self._github_entry(handles) + row += self._affiliation_entry(affils) + row += self._text_entry(str(meta.get("date", ""))) + row += self._text_entry(recommendation) + return row + + # ---- shared builders ---- + + def _new_table(self, cols, widths): + table = nodes.table() + tgroup = nodes.tgroup(cols=len(cols)) + table += tgroup + for w in widths: + tgroup += nodes.colspec(colwidth=w) + thead = nodes.thead() + tgroup += thead + hrow = nodes.row() + for c in cols: + hrow += self._text_entry(c) + thead += hrow + tbody = nodes.tbody() + tgroup += tbody + return table, tbody + + def _text_entry(self, text, style=None): + entry = nodes.entry() + para = nodes.paragraph() + if style == "bold": + para += nodes.strong("", nodes.Text(text or "")) + elif style == "italic": + para += nodes.emphasis("", nodes.Text(text or "")) + else: + para += nodes.Text(text or "") + entry += para + return entry + + def _doc_entry(self, text, docname): + """Cell linking to another document.""" + entry = nodes.entry() + para = nodes.paragraph() + para += _doc_reference(text, "/" + docname) + entry += para + return entry + + def _affiliation_entry(self, affiliations): + """Comma-separated institutions, linked when an `affiliation_url` is given.""" + entry = nodes.entry() + para = nodes.paragraph() + for i, (name, uri) in enumerate(a for a in affiliations if a[0]): + if i: + para += nodes.Text(", ") + if uri: + para += nodes.reference("", name, refuri=uri) + else: + para += nodes.Text(name) + entry += para + return entry + + def _github_entry(self, handles): + entry = nodes.entry() + para = nodes.paragraph() + for i, gh in enumerate(handles): + if i: + para += nodes.Text(", ") + para += nodes.reference("", gh, refuri=f"https://github.com/{gh}") + entry += para + return entry + + def _linked_entry(self, text, target, style=None): + entry = nodes.entry() + para = nodes.paragraph() + if target: + para += nodes.reference("", text, refuri=target) + else: + if style == "bold": + para += nodes.strong("", nodes.Text(text or "")) + elif style == "italic": + para += nodes.emphasis("", nodes.Text(text or "")) + else: + para += nodes.Text(text or "") + entry += para + return entry + + +class RFCListing(RFCStatus): + """The table of all RFCs, built from each RFC's own front matter. + + Subclasses RFCStatus only to reuse its table builders; it renders the + overview table for rfc/index.md rather than a single RFC's record. + """ + + def run(self): + env = self.state.document.settings.env + base = os.path.dirname(env.doc2path(env.docname)) + docdir = posixpath.dirname(env.docname) + + rfcs = [] + for name, subdir in _numbered_subdirs(base): + index_path = os.path.join(subdir, "index.md") + if name.isdigit() and os.path.isfile(index_path): + rfcs.append((int(name), _read_front_matter(index_path))) + rfcs.sort() + + cols = ["RFC", "Description", "Date", "Status", "Note", "OME-Zarr Version"] + table, tbody = self._new_table(cols, (8, 26, 8, 20, 26, 12)) + table.insert(0, nodes.title(text="RFC Listing")) + for number, meta in rfcs: + date = str(meta.get("date", "")) + row = nodes.row() + row += self._doc_entry(f"RFC-{number}", f"{docdir}/{number}/index") + row += self._text_entry(meta.get("description", "")) + row += self._text_entry(date[:4] if date else "TBD") + row += self._text_entry(_state_text(meta) or "TBD") + row += self._text_entry(str(meta.get("status_note", ""))) + row += self._text_entry(str(meta.get("ome_zarr_version", ""))) + tbody += row + return [table] + + +def setup(app): + app.add_directive("rfc-status", RFCStatus) + app.add_directive("rfc-listing", RFCListing) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/_static/document_authors.css b/_static/document_authors.css new file mode 100644 index 000000000..72aae27ad --- /dev/null +++ b/_static/document_authors.css @@ -0,0 +1,17 @@ +.rfc-author-icon { + height: 1em; + width: 1em; + vertical-align: -0.15em; + margin: 0 0.05em; + display: inline; +} + +.rfc-authors { + font-size: 1.05em; +} + +.rfc-affiliation { + font-size: 0.85em; + color: var(--pst-color-text-muted, #666); + margin: 0.1em 0; +} diff --git a/conf.py b/conf.py index 156a7529d..d8745eee8 100644 --- a/conf.py +++ b/conf.py @@ -6,6 +6,8 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os + project = "NGFF" copyright = "2020-2025, NGFF Community" author = "NGFF Community" @@ -13,17 +15,25 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +# Needed for custom document_authors extension to be found in _ext +import os +import sys + +sys.path.insert(0, os.path.abspath("_ext")) + extensions = [ "myst_parser", "sphinx_reredirects", "sphinx_design", "sphinxcontrib.bibtex", + "document_authors", + "rfc_status", ] bibtex_bibfiles = ["references.bib"] source_suffix = [".rst", ".md"] myst_heading_anchors = 5 -myst_enable_extensions = ["deflist", "strikethrough", "colon_fence"] - +myst_enable_extensions = ["deflist", "strikethrough", "colon_fence", "substitution"] templates_path = ["_templates"] exclude_patterns = [ "_build", @@ -81,7 +91,8 @@ html_css_files = [ "https://cdn.datatables.net/v/dt/dt-1.11.5/datatables.min.css", - "custom.css" + "document_authors.css", + "custom.css", ] html_js_files = [ @@ -95,6 +106,7 @@ html_show_sourcelink = False + def build_served_html(): import glob import subprocess diff --git a/contributing/website/index.md b/contributing/website/index.md index d752b9323..dc5873f61 100644 --- a/contributing/website/index.md +++ b/contributing/website/index.md @@ -43,7 +43,17 @@ sphinx-autobuild . _build/html ``` The website will then be served at http://127.0.0.1:8000. +## Checking RFC front matter + +The RFC documents have some information rendered from the YAML front matter at the top of each document. +The front matter is validated against a LinkML schema. To check it locally: + +```bash +pip install linkml +python rfc/schema/validate.py # or pass the files you changed +``` + ## PR previews Each PR receives a unique preview URL of the format `https://ngff--.org.readthedocs.build/` where `` is the PR number. This link is also posted to each PR by the Github actions bot in an "Automated Review URLs" comment as the "Readthedocs" link. -Please check that your changes render correctly at this URL. New commits will automatically be live at the PR url after a few minutes. \ No newline at end of file +Please check that your changes render correctly at this URL. New commits will automatically be live at the PR url after a few minutes. diff --git a/requirements.txt b/requirements.txt index fef63a539..743590fa3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,4 +6,5 @@ testresources sphinx-reredirects sphinxcontrib-bibtex sphinx-design -sphinx-autobuild \ No newline at end of file +pyyaml +sphinx-autobuild diff --git a/rfc/0/index.md b/rfc/0/index.md index cbe48ffb9..0147b390d 100644 --- a/rfc/0/index.md +++ b/rfc/0/index.md @@ -1,3 +1,18 @@ +--- +authors: + - name: Josh Moore + github: joshmoore + affiliation: German BioImaging, e.V. + affiliation_url: https://ror.org/05tpnw772 + role: Author + date: "2024-08-30" +manual_status: N/A +status_note: historical RFC, outdated by RFC-1 +description: Original consensus model for decision making +ome_zarr_version: "N/A" +date: 2024-08-30 +--- + # RFC-0: Consensus model Original NGFF consensus process @@ -7,23 +22,11 @@ Original NGFF consensus process This is a historical RFC, drafted after the fact, and has been outdated by [RFC-1][1]. -```{list-table} Record -:widths: 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Name - - GitHub Handle - - Institution - - Date - - Status -* - Josh Moore - - [joshmoore](https://github.com/joshmoore) - - [German BioImaging, e.V.](https://ror.org/05tpnw772) - - 2022-07-11 ([issue-132](https://github.com/ome/ngff/issues/132)) / 2024-08-30 (RFC-0) - - Author +```{rfc-status} ``` +This RFC was first captured as [issue-132](https://github.com/ome/ngff/issues/132) on 2022-07-11 and written up as RFC-0 on 2024-08-30. + ## Overview Versions of the NGFF specification up to and including v0.4 followed a diff --git a/rfc/1/comments/1/index.md b/rfc/1/comments/1/index.md index 336343cfd..727c13cfc 100644 --- a/rfc/1/comments/1/index.md +++ b/rfc/1/comments/1/index.md @@ -1,9 +1,18 @@ +--- +authors: + - name: Wouter-Michiel Vierdag + affiliation: EMBL + github: melonora + - name: Luca Marconato + affiliation: EMBL + github: LucaMarconato +date: 2024-01-13 +--- # RFC-1: Comment 1 -| Name | GitHub Handle | Institution | -|------------------------|---------------|----------------------| -| Wouter-Michiel Vierdag | melonora | EMBL | -| Luca Marconato | LucaMarconato | EMBL | +```{document-authors} + +``` ## Comments on implementations diff --git a/rfc/1/comments/2/index.md b/rfc/1/comments/2/index.md index 37944c924..9afb11080 100644 --- a/rfc/1/comments/2/index.md +++ b/rfc/1/comments/2/index.md @@ -1,8 +1,15 @@ +--- +authors: + - name: Matt McCormick + affiliation: ITK + github: thewtex +date: 2024-01-09 +--- + # RFC-1: Comment 2 -| Name | GitHub Handle | Institution | -|------------------------|---------------|----------------------| -| Matt McCormick | thewtex | ITK | +```{document-authors} +``` ## Comments from the original issue diff --git a/rfc/1/index.md b/rfc/1/index.md index a4a931b61..91da41558 100644 --- a/rfc/1/index.md +++ b/rfc/1/index.md @@ -1,5 +1,50 @@ -RFC-1: RFC Process -================== +--- +authors: + - name: Josh Moore + github: joshmoore + affiliation: German BioImaging, e.V. + affiliation_url: https://ror.org/05tpnw772 + role: Author + date: "2023-12-23" +endorsers: + - name: Jean-Marie Burel + github: jburel + affiliation: University of Dundee + date: "2024-09-09" + reference: https://github.com/ome/ngff/pull/258 + - name: Will Moore + github: will-moore + affiliation: University of Dundee + date: "2024-09-09" + reference: https://github.com/ome/ngff/pull/258 + - name: Juan Nunez-Iglesias + github: jni + affiliation: Monash University + date: "2024-09-09" + reference: https://github.com/ome/ngff/pull/258 + - name: Norman Rzepka + github: normanrz + affiliation: scalable minds GmbH + date: "2024-09-09" + reference: https://github.com/ome/ngff/pull/258 + - name: Jan Eglinger + github: imagejan + affiliation: FMI Basel + date: "2024-09-09" + reference: https://github.com/ome/ngff/pull/258 + - name: Joel Lüthi + github: jluethi + affiliation: BioVisionCenter, University of Zurich + date: "2024-09-10" + reference: https://github.com/ome/ngff/pull/258 +reference_pr: https://github.com/ome/ngff/pull/222 +manual_status: S4 +description: RFC Process +ome_zarr_version: "N/A" +date: 2023-12-23 +--- + +# RFC-1: RFC Process (rfcs:rfc1)= @@ -17,115 +62,7 @@ versions/index ## Status -This RFC has been adopted (S4). - -```{list-table} Record -:widths: 8, 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Role - - Name - - GitHub Handle - - Institution - - Date - - Status -* - Author - - Josh Moore - - [joshmoore](https://github.com/joshmoore) - - [German BioImaging, e.V.](https://ror.org/05tpnw772) - - 2023-12-23 - - Author ([PR](https://github.com/ome/ngff/pull/222)) -* - Reviewer - - Davis Bennett, John Bogovic, Michael Innerberger, Mark Kittisopikul, Virginia Scarlett, Yurii Zubov - - [d-v-b](https://github.com/d-v-b), [bogovicj](https://github.com/bogovicj), [minnerbe](https://github.com/minnerbe), [mkitti](https://github.com/mkitti), [virginiascarlett](https://github.com/virginiascarlett), [yuriyzubov](https://github.com/yuriyzubov) - - Janelia - - 2024-02-26 - - [Review](./reviews/2/index) -* - Reviewer - - Kevin Yamauchi, Virginie Uhlmann - - [kevinyamauchi](https://github.com/kevinyamauchi), [vuhlmann](https://github.com/vuhlmann) - - ETH, BiovisionCenter - - 2024-03-05 - - [Review](./reviews/1/index) -* - Reviewer - - Matthew Hartley - - [mrmh2](https://github.com/mrmh2) - - EMBL-EBI - - 2024-03-05 - - [Review](./reviews/3/index) -* - Author - - Josh Moore - - [joshmoore](https://github.com/joshmoore) - - German BioImaging - - 2024-08-29 - - [Response](./responses/1/index) -* - Endorser - - Jean-Marie Burel - - [jburel](https://github.com/jburel) - - University of Dundee - - 2024-09-09 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Endorser - - Will Moore - - [will-moore](https://github.com/will-moore) - - University of Dundee - - 2024-09-09 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Endorser - - Juan Nunez-Iglesias - - [jni](https://github.com/jni) - - Monash University - - 2024-09-09 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Endorser - - Norman Rzepka - - [normanrz](https://github.com/normanrz) - - scalable minds GmbH - - 2024-09-09 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Endorser - - Jan Eglinger - - [imagejan](https://github.com/imagejan) - - FMI Basel - - 2024-09-09 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Endorser - - Joel Lüthi - - [jluethi](https://github.com/jluethi) - - BioVisionCenter, University of Zurich - - 2024-09-10 - - [Endorse](https://github.com/ome/ngff/pull/258) -* - Reviewer - - Kevin Yamauchi, Joel Lüthi, Virginie Uhlmann - - [kevinyamauchi](https://github.com/kevinyamauchi), [jluethi](https://github.com/jluethi), [vuhlmann](https://github.com/vuhlmann) - - ETH, BiovisionCenter - - 2024-10-03 - - [Accept](./reviews/1b/index) -* - Reviewer - - Matthew Hartley - - [mrmh2](https://github.com/mrmh2) - - EMBL-EBI - - 2024-10-08 - - Accept (email) -* - Reviewer - - John Bogovic, Michael Innerberger, Virginia Scarlett - - [bogovicj](https://github.com/bogovicj), [minnerbe](https://github.com/minnerbe), [virginiascarlett](https://github.com/virginiascarlett) - - Janelia - - 2024-10-11 - - [Accept](./reviews/2b/index) -* - Commenter - - Wouter-Michiel Vierdag, Luca Marconato - - [melonora](https://github.com/melonora), [LucaMarconato](https://github.com/LucaMarconato) - - EMBL - - 2024-01-13 - - [Comment](./comments/1/index) -* - Commenter - - Matt McCormick - - [thewtex](https://github.com/thewtex) - - ITK - - 2024-01-09 - - [Comment](./comments/2/index) +```{rfc-status} ``` ## Overview @@ -156,16 +93,16 @@ which originated in the Internet Engineering Task Force (IETF), for use in the NGFF community as has been done in a number of other communities ([Rust](https://github.com/rust-lang/rfcs/blob/master/0000-template.md), [Hashicorp](https://works.hashicorp.com/articles/rfc-template), [Tensorflow](https://github.com/tensorflow/community/blob/master/rfcs/yyyymmdd-rfc-template.md), etc.) More information can be found under: -- [https://en.wikipedia.org/wiki/Internet\_Standard#Standardization\_process](https://en.wikipedia.org/wiki/Internet_Standard#Standardization_process) -- [https://en.wikipedia.org/wiki/Request\_for\_Comments](https://en.wikipedia.org/wiki/Request_for_Comments) +- [https://en.wikipedia.org/wiki/Internet_Standard#Standardization_process](https://en.wikipedia.org/wiki/Internet_Standard#Standardization_process) +- [https://en.wikipedia.org/wiki/Request_for_Comments](https://en.wikipedia.org/wiki/Request_for_Comments) ## Proposal -Requests for Comment (RFCs) are intended to structure high-level discussions on changes within the NGFF community and record outcomes including key opinions, actions, and decisions. The overall goal of the process is timely and transparent decision-making for a stable and trusted community specification. It should be clear after reading the RFC which stakeholder (**Author**, **Reviewer**, **Editor**, etc.) is responsible for each step of the process, what options are available to the decision makers, and how much time the community can expect that decision to take. +Requests for Comment (RFCs) are intended to structure high-level discussions on changes within the NGFF community and record outcomes including key opinions, actions, and decisions. The overall goal of the process is timely and transparent decision-making for a stable and trusted community specification. It should be clear after reading the RFC which stakeholder (**Author**, **Reviewer**, **Editor**, etc.) is responsible for each step of the process, what options are available to the decision makers, and how much time the community can expect that decision to take. ![Simplified drawing of the RFC process](./drawing.png) -**Figure 1. Simplified drawing of the RFC process** An RFC draft (1) is +**Figure 1. Simplified drawing of the RFC process** An RFC draft (1) is proposed by **Authors** who would like to see some change in the NGFF community. There is a period of gathering _[endorsements](#def-endorsement)_ (2) which will be listed in the RFC itself. This gives future readers and @@ -180,7 +117,7 @@ with the RFC changes (5). After a minimum number of implementations have been achieved, the RFC is considered _adopted_ (6). The RFC process functions by encouraging submissions from the -community that are recorded for posterity *even if not adopted*. +community that are recorded for posterity _even if not adopted_. Descriptive and complete comments from both **Authors** and **Reviewers** are critical to have a clear understanding of what decisions have been made. Goals of this process include maintaining a public record of @@ -216,14 +153,14 @@ draft has reached a stage where it is ready for review, **Editors** will merge it as a record of the fact that the suggestion has been made, and it will then become available on https://ngff.openmicroscopy.org. -**Endorsers** are non-**Author** supporters of an RFC, listed in a table within the RFC. -**Reviewers** who have given an "Accept" recommendation and **Implementers** are also considered **Endorsers**. +**Endorsers** are non-**Author** supporters of an RFC, listed in a table within the RFC. +**Reviewers** who have given an "Accept" recommendation and **Implementers** are also considered **Endorsers**. **Editors** are responsible for facilitating all parts of the RFC process. They identify whether a PR should or should not follow the RFC process, and choose when a draft is ready to become an RFC. They also choose appropriate **Reviewers** for an RFC and manage the communication between -**Authors** and **Reviewers**. +**Authors** and **Reviewers**. **Implementers** are responsible for an implementation of the NGFF specification in one or more programming languages. It is critical that specification RFCs have been evaluated by **Implementers** which is often best done in the implementation rather than a review. Therefore, statements that an RFC is “planned”, “begun”, or “complete” for an implementation will be given similar weight to an endorsement or positive review. @@ -241,6 +178,7 @@ right direction. **Reviewers** should strive to provide feedback which informs * **Commenters** are other members of the community who, though not contacted as **Reviewers**, have provided feedback that they would like added to the official record of the RFC. (rfc1-implementation)= + ## Implementation The RFC process can be represented as a state diagram with the various stakeholders responsible for forward motion. @@ -255,8 +193,8 @@ Identifiers such as "D1", "R2", "S3", refer to individual steps. Notes regarding specific requirements are called out throughout the text with the following symbols: -> * 🕑 The clock symbol specifies definitive wait times within the process. -> * 📂 The folder symbol specifies requirements on additions to the repository, +> - 🕑 The clock symbol specifies definitive wait times within the process. +> - 📂 The folder symbol specifies requirements on additions to the repository, > for example an implementation or failing test. ### Phases @@ -325,39 +263,40 @@ to the **Editors**, either via a public PR adding the review in markdown to the RFC's subdirectory or by emailing the **Editors** directly. (This latter course should only be used when necessary.) -(rfc-recommendations)= +(rfc-recommendations)= Possible recommendations from **Reviewers** in ascending order of support are: -* “Reject” suggests that a **Reviewer** considers there to be no merit to an +- “Reject” suggests that a **Reviewer** considers there to be no merit to an RFC. This should be a last recourse. Instead, suggestions in a “Major changes” recommendation might include attempting an Extension rather than an RFC so that not all implementations need concern themselves with the matter. -* “Major changes” suggests that a **Reviewer** sees the potential value of an +- “Major changes” suggests that a **Reviewer** sees the potential value of an RFC but will require significant changes before being convinced. Suggestions SHOULD be provided on how to concretely improve the proposal in order to make it acceptable and change the **Reviewer**’s recommendation. -* “Minor changes” suggests that if the described changes are made, that +- “Minor changes” suggests that if the described changes are made, that **Editors** can move forward with an RFC without a further review. -* “Accept” is a positive vote and no text review is strictly necessary, though +- “Accept” is a positive vote and no text review is strictly necessary, though may be provided to add context to the written record. A **Reviewer** who accepts an RFC is joining the list of endorsements. Three additional versions of the "Accept" recommendation are available for **Reviewers** who additionally maintain an implementation of the NGFF specification to express further support: -* “Plan to implement” with an estimated timeline -* “Implementation begun” with an estimated timeline -* “Implementation complete” with a link to the available code + +- “Plan to implement” with an estimated timeline +- “Implementation begun” with an estimated timeline +- “Implementation complete” with a link to the available code Where a review is required, **Reviewers** are free to structure the text in the most useful way. A [template markdown file](templates/review_template) is available but not mandatory. Useful sections include: -* Summary -* Conflicts of interest (if they exist) -* Significant comments and questions -* Minor comments and questions -* Recommendation +- Summary +- Conflicts of interest (if they exist) +- Significant comments and questions +- Minor comments and questions +- Recommendation The tone of a review should be cordial and professional. The goal is to communicate to the **Authors** what it would take to make the RFC acceptable. @@ -371,12 +310,11 @@ contact **Reviewers** to see if their recommendations have changed. > 🕑 Authors responses to Reviewers should be returned to the Editors in less than two weeks. -(anchor-rebuttal-r6)= -This brings a critical, and possibly iterative, decision point (R6). If all **Reviewers** `approve` and there are no further changes needed, the RFC can progress to S1 as soon as there are two in-progress implementations. If the **Reviewers** do _not_ approve, then the **Editors** will make one of three decisions (R7): +(anchor-rebuttal-r6)= This brings a critical, and possibly iterative, decision point (R6). If all **Reviewers** `approve` and there are no further changes needed, the RFC can progress to S1 as soon as there are two in-progress implementations. If the **Reviewers** do _not_ approve, then the **Editors** will make one of three decisions (R7): -* The **Editors** MAY provide **Authors** a list of necessary changes. These will be based on the **Reviewers** suggestions but possibly modified, e.g., to remove contradictions. -* The **Editors** MAY decide that the RFC is to be closed (R9). This is the decision that SHOULD be chosen if there is a unanimous `Reject` recommendation. The **Authors** MAY then decide to re-draft a new RFC (D2). -* Finally, the **Editors** MAY decide that no further changes are necessary (S0). +- The **Editors** MAY provide **Authors** a list of necessary changes. These will be based on the **Reviewers** suggestions but possibly modified, e.g., to remove contradictions. +- The **Editors** MAY decide that the RFC is to be closed (R9). This is the decision that SHOULD be chosen if there is a unanimous `Reject` recommendation. The **Authors** MAY then decide to re-draft a new RFC (D2). +- Finally, the **Editors** MAY decide that no further changes are necessary (S0). If the **Editors** decide to override the recommendations of the **Reviewers** (R7) the **Editors** MUST include a response (S0). This may occur, for example, if consent between the reviewers cannot be reached. In the case of a unanimous `Reject`, the **Editors** SHOULD attempt to find at least one additional, approving **Reviewer** . @@ -424,7 +362,7 @@ listed, the specification will be considered "adopted". The adopted specification will be slotted into a release version by the **Editors** and the **Authors** are encouraged to be involved in that release. -> 📂 Two released implementations required for being adopted. +> 📂 Two released implementations required for being adopted. ## Policies @@ -434,8 +372,9 @@ This section defines several concrete aspects of the RFC process not directly re Unless otherwise specified in the text, the following considerations are taken into account when making decisions regarding RFCs: - - **prefer working examples**: whether an implementation of an RFC or a failing test which exposes an issue in a proposal, working examples will tend to carry more weight in decision making. - - **technical expertise**: all other considerations being equal, feedback from stakeholders with more technical expertise in a matter under consideration will tend to carry more weight in decision making. + +- **prefer working examples**: whether an implementation of an RFC or a failing test which exposes an issue in a proposal, working examples will tend to carry more weight in decision making. +- **technical expertise**: all other considerations being equal, feedback from stakeholders with more technical expertise in a matter under consideration will tend to carry more weight in decision making. - **newcomer advantage**: care will be taken not to let existing implementations overly dictate the future strategic direction of NGFF in order to avoid premature calcification. ### RFC Prioritization @@ -451,7 +390,7 @@ the community. Which cross-sections are chosen MAY depend on a given RFC but might include geographic distributions, the variety of imaging modalities, and/or programming languages of the expected implementations. An attempt MUST also be made to select both supporting and dissenting voices from the community. -*Editors* and *Reviewers* should proactively disclose any potential conflicts +_Editors_ and _Reviewers_ should proactively disclose any potential conflicts of interest to ensure a transparent review process. ### Deadline enforcement @@ -459,10 +398,11 @@ of interest to ensure a transparent review process. In the absence of concrete mechanisms for deadline enforcement (penalties, etc), all members of the NGFF community and especially the **Editors** SHOULD strive to prevent the specification process from becoming blocked. The **Editors**, however will endeavor to: -* keep a record of all communications to identify bottlenecks and improve the RFC process; -* frequently contact **Authors** and **Reviewers** regarding approaching deadlines; -* find new **Reviewers** when it becomes clear that the current slate is overextended; -* and proactively mark RFCs as inactive if it becomes clear that progress has stalled. + +- keep a record of all communications to identify bottlenecks and improve the RFC process; +- frequently contact **Authors** and **Reviewers** regarding approaching deadlines; +- find new **Reviewers** when it becomes clear that the current slate is overextended; +- and proactively mark RFCs as inactive if it becomes clear that progress has stalled. **Authors** and **Reviewers** are encouraged to be open and honest, both with themselves and the other members of the process, on available time. A short message stating that an edit or a review will not occur on deadline or even at all is preferable to silence. @@ -472,7 +412,7 @@ The process description describes “sufficient endorsement” in two locations, Under RFC-0, three implementation languages — Javascript, Python, and Java — were considered “reference”, or “required”, for a specification to be complete. This proved a difficult barrier since the implementation teams were not directly funded for work on NGFF. -RFC-1 has chosen to start with a simpler requirement: **two** separate implementations MUST be _begun_ to enter the SPEC phase and **two** separate implementations (they need not be the same ones) MUST be _released_ to be considered adopted. In both cases, at least **one** of those implementations MUST come from an **Implementer** who is not among the **Authors**. Additionally, data written by both implementations MUST be readable (and therefore validatable) by at least **one** of the implementations. +RFC-1 has chosen to start with a simpler requirement: **two** separate implementations MUST be _begun_ to enter the SPEC phase and **two** separate implementations (they need not be the same ones) MUST be _released_ to be considered adopted. In both cases, at least **one** of those implementations MUST come from an **Implementer** who is not among the **Authors**. Additionally, data written by both implementations MUST be readable (and therefore validatable) by at least **one** of the implementations. It is also strongly encouraged that for each specification change, the [ome-ngff-validator](https://github.com/ome/ome-ngff-validator) additionally be updated. The validator will not fully test the readability of a dataset since it has limited IO capabilities, but it is the most complete tool for validating the metadata associated with a dataset. @@ -485,6 +425,7 @@ This policy does not yet specify whether parts of an RFC may be considered _opti The IETF RFC process disallows edits to published RFCs. (In the extreme case, a single word change has resulted in a new RFC number.) Though this ensures a unique interpretation of any RFC number, it would also lead to significant duplication of content and _churn_ in the NGFF community. Though this decision may be reviewed in the future, RFCs MAY be edited, but **Editors** SHOULD limit modifications to _adopted_ RFCs only for: + - clarification: additional text and examples which simplify the implementation of specifications are welcome; - deprecation: where sections are no longer accurate and especially when they have been replaced by a new RFC, the existing text can be marked and a link to the updated information provided; - and extension: references to new RFCs can be added throughout an existing RFC to provide simpler reading for **Implementers**. @@ -492,10 +433,11 @@ Though this decision may be reviewed in the future, RFCs MAY be edited, but **Ed In writing RFCs, **Authors** SHOULD attempt to clearly identify sections which may be deprecated or extended in the future. Before an RFC is _adopted_ there are a number of versions of an RFC which are produced during the editing and revision process. This RFC does not try to specify how those versions are managed. The **Editors** are encouraged to layout a best practice as described under “Workflow” that simplifies the review process. Possible solutions include: -* using commit numbers version -* making hard-copies of versions under review -* creating a separate repository per RFC -* opening a long-lived “review PR” with a dedicated URL + +- using commit numbers version +- making hard-copies of versions under review +- creating a separate repository per RFC +- opening a long-lived “review PR” with a dedicated URL ### Specification Versions @@ -520,7 +462,7 @@ an expedited process. A similar model is in use within the IETF community. If th ### Handling Disagreements -The OME community is open to everybody and built upon mutual respect. Nevertheless, disagreements do occur. +The OME community is open to everybody and built upon mutual respect. Nevertheless, disagreements do occur. All activities within the NGFF community are conducted under the OME [Code of Conduct](https://github.com/ome/.github/blob/master/CODE_OF_CONDUCT.md#when-something-happens). If you feel that your objections are not being considered, please follow the steps outlined under “When Something Happens”. @@ -556,7 +498,7 @@ on GitHub does not provide the editorial functions that one would want, such as deferring and collecting comments, nor do the conversations provide a consistent whole when revisited after the work on a specification. Additionally, **Authors** have complained of the burden of managing responses. -So there's a need for *something*, but does this proposal go too far in the +So there's a need for _something_, but does this proposal go too far in the other direction? It is certainly true that the formality of the responses asked of the @@ -606,7 +548,7 @@ using adaptions of the RFC process which will not be re-listed here. However, there are also other enhancement processes which are closely related to the NGFF RFC. Most closely, is the Zarr Enhancement Proposals (ZEP) process within the Zarr community. Based originally on a combination of the PEP, NEP, and STAC -processes, the ZEP process uses a council of the implementations (ZIC) +processes, the ZEP process uses a council of the implementations (ZIC) ## Future possibilities @@ -632,12 +574,12 @@ Definitions for terms used throughout this RFC have been collected below. (def-accepted)= **Accepted** : Specifies that an RFC has passed review and all implementers should begin - implementation if they have not done so already. +implementation if they have not done so already. (def-adopted)= **Adopted** : An RFC that has been sufficiently implemented to be considered - as active within the community. +as active within the community. (def-author)= **Author** @@ -646,8 +588,8 @@ Definitions for terms used throughout this RFC have been collected below. (def-comment)= **Comment** : Documents that are included with the RFC discussing the pros and - cons of the proposal in a structured way. Comments from reviewers are - additionally referred to as "reviews". +cons of the proposal in a structured way. Comments from reviewers are +additionally referred to as "reviews". (def-draft)= **Draft** @@ -664,8 +606,8 @@ Definitions for terms used throughout this RFC have been collected below. (def-rfc)= **RFC** ("Request for Comment") : A formal proposal following a standardized - template that is made to the NGFF repository. The proposal need not be - accepted to be published online. +template that is made to the NGFF repository. The proposal need not be +accepted to be published online. (def-pr)= **PR** diff --git a/rfc/1/responses/1/index.md b/rfc/1/responses/1/index.md index b8816b9ca..947ed6b4b 100644 --- a/rfc/1/responses/1/index.md +++ b/rfc/1/responses/1/index.md @@ -1,5 +1,16 @@ +--- +authors: + - name: Josh Moore + affiliation: German BioImaging + github: joshmoore +date: 2024-08-29 +--- + # RFC-1: Response 1 (2024-04-24 version) +```{document-authors} +``` + Many thanks to all of the reviewers of this first RFC. Creating a process like this in isolation is difficult and having your feedback is invaluable. In this response, I’ll begin with overall thoughts covering the entire process. Then per review, I’ll break the review texts into parts, respond to each in turn and point to the changes made to the final text to address raised issues. ## Overall diff --git a/rfc/1/reviews/1/index.md b/rfc/1/reviews/1/index.md index 154273ebd..b2469a867 100644 --- a/rfc/1/reviews/1/index.md +++ b/rfc/1/reviews/1/index.md @@ -1,10 +1,23 @@ +--- +authors: + - name: Joel Lüthi + affiliation: BioVisionCenter + github: jluethi + - name: Virginie Uhlmann + affiliation: BiovisionCenter + github: vuhlmann + - name: Kevin Yamauchi + affiliation: ETH + github: kevinyamauchi +recommendation: major_changes +date: 2024-03-05 +--- # RFC-1: Review 1 ## Review authors -This review was written by: -- Joel Lüthi -- Virginie Uhlmann -- Kevin Yamauchi + +```{document-authors} +``` ## Summary RFC1 proposes a process by which changes to the NGFF project can be proposed, reviewed, and implemented. These changes include both modifications to the NGFF specification and to the governance of the NGFF project. This process has three phases: DRAFT, RFC, and SPEC. In the draft phase, community members can propose changes. If these changes receive sufficient community support via endorsements and Editor approval, they transition to the RFC phase. In the RFC phase, the proposal is reviewed by Reviewers chosen by an Editor. With Reviewer and Editor approval, the proposal transitions to the SPEC stage in which implementation will begin. diff --git a/rfc/1/reviews/1b/index.md b/rfc/1/reviews/1b/index.md index c5fc4e44a..bf791501b 100644 --- a/rfc/1/reviews/1b/index.md +++ b/rfc/1/reviews/1b/index.md @@ -1,10 +1,23 @@ +--- +authors: + - name: Joel Lüthi + affiliation: BioVisionCenter + github: jluethi + - name: Virginie Uhlmann + affiliation: BioVisionCenter + github: vuhlmann + - name: Kevin Yamauchi + affiliation: ETH + github: kevinyamauchi +recommendation: accept +date: 2024-10-03 +--- # RFC-1: Review 1 Round 2 ## Review authors -This review was written by: -- Joel Lüthi -- Virginie Uhlmann -- Kevin Yamauchi + +```{document-authors} +``` ## Summary diff --git a/rfc/1/reviews/2/index.md b/rfc/1/reviews/2/index.md index 738475abd..73d1d81fa 100644 --- a/rfc/1/reviews/2/index.md +++ b/rfc/1/reviews/2/index.md @@ -1,3 +1,26 @@ +--- +authors: + - name: Davis Bennett + affiliation: HHMI Janelia + github: d-v-b + - name: John Bogovic + affiliation: HHMI Janelia + github: bogovicj + - name: Michael Innerberger + affiliation: HHMI Janelia + github: minnerbe + - name: Mark Kittisopikul + affiliation: HHMI Janelia + github: mkitti + - name: Virginia Scarlett + affiliation: HHMI Janelia + github: virginiascarlett + - name: Yurii Zubov + affiliation: HHMI Janelia + github: yuriyzubov +recommendation: major_changes +date: 2024-02-26 +--- # RFC-1: Review 2 ## Contributors diff --git a/rfc/1/reviews/2b/index.md b/rfc/1/reviews/2b/index.md index 91d57e710..60ab908d7 100644 --- a/rfc/1/reviews/2b/index.md +++ b/rfc/1/reviews/2b/index.md @@ -1,3 +1,17 @@ +--- +authors: + - name: John Bogovic + affiliation: HHMI Janelia + github: bogovicj + - name: Michael Innerberger + affiliation: HHMI Janelia + github: minnerbe + - name: Virginia Scarlett + affiliation: HHMI Janelia + github: virginiascarlett +recommendation: accept +date: 2024-10-11 +--- # RFC-1: Review 2b ## Contributors diff --git a/rfc/1/reviews/3/index.md b/rfc/1/reviews/3/index.md index 902ffe5f1..76348f635 100644 --- a/rfc/1/reviews/3/index.md +++ b/rfc/1/reviews/3/index.md @@ -1,5 +1,19 @@ +--- +authors: + - name: Matthew Hartley + affiliation: BioImage Archive, EMBL-EBI + github: matthewh-ebi +recommendation: accept +date: 2024-03-05 +--- + # RFC-1: Review 3 +```{document-authors} + +``` + + This review submitted by Matthew Hartley, on behalf on EMBL-EBI's imaging data resources (BioImage Archive, EMPIAR and EMDB). ## Summary diff --git a/rfc/1/reviews/3b/index.md b/rfc/1/reviews/3b/index.md new file mode 100644 index 000000000..a32100552 --- /dev/null +++ b/rfc/1/reviews/3b/index.md @@ -0,0 +1,21 @@ +--- +authors: + - name: Matthew Hartley + affiliation: BioImage Archive, EMBL-EBI + github: matthewh-ebi +recommendation: accept +date: 2024-10-08 +--- + +# RFC-1: Review 3 + +```{document-authors} + +``` + + +This review was submitted via email. + +## Recommendation + +**accept** diff --git a/rfc/1/templates/review_template.md b/rfc/1/templates/review_template.md index f1d37f7c3..e68890729 100644 --- a/rfc/1/templates/review_template.md +++ b/rfc/1/templates/review_template.md @@ -1,9 +1,46 @@ +--- +authors: + - name: Author 1 + affiliation: Affiliation X + orcid: 0000-0000-0000-0000 + github: author1 + - name: Author 2 + affiliation: Affiliation Y + orcid: 0000-0000-0000-0000 + github: author2 +date: YYYY-MM-DD +recommendation: accept +--- + +# RFC-X: Review X + +or + +# RFC-X: Comment X + +(rfcs:rfcX:reviewX)= + +(rfcs:rfcX:commentX)= + (rfc1-review-template)= -# Review Template -Replace the title above of this file with “RFC-NUM: Review NUM” +Replace the title above of this file with “RFC-NUM: Review NUM”. Update the tag to `(rfcs:rfcNUM:reviewNUM)` and remove the `(rfc1-review-template)` tag. Add your names and affiliations to the **authors** section above (and optionally ORCID and GitHub username) as well as the date of submission and your recommendation (`accept`, `major_changes`, `minor_changes`, `reject`). -## Review authors +For a Comment, the `recommendation` field may be left blank. Please also change the mentions of "review" to "comment" where appropriate, including the MyST target anchor, and the title of the file. + +The document-authors directive will automatically pull the information from the YAML front matter and display it in a table. + +The fields are described by the LinkML schema in +[`rfc/schema/front_matter.yaml`](https://github.com/ome/ngff/blob/main/rfc/schema/front_matter.yaml), +which is what CI checks every review, comment and response against. To check yours +yourself, run `pip install linkml` and then `python rfc/schema/validate.py` from the +root of the repository. + +## Authors + +```{document-authors} + +``` ## Conflicts of interest (optional) @@ -15,7 +52,7 @@ This section should be included if authors feel that there is any background inf ### Subheadings -Structure any subheadings as necessary. +Structure any subheadings as necessary. ## Minor comments and questions @@ -26,4 +63,3 @@ Similarly, add any subheadings necessary Adopt, major changes, minor changes, reject (as last resort) See [the list of recommendations under “RFC” in RFC-1](../index.md#rfc-recommendations). - diff --git a/rfc/1/templates/rfc_template.md b/rfc/1/templates/rfc_template.md index a4dfda4c0..7a570fe8c 100644 --- a/rfc/1/templates/rfc_template.md +++ b/rfc/1/templates/rfc_template.md @@ -1,5 +1,80 @@ -@: template -# RFC Template +--- +authors: + - name: Author 1 + github: author1 + orcid: 0000-0000-0000-0000 + affiliation: Affiliation X + affiliation_url: https://ror.org/XXXXXXXXX + role: Corresponding Author + date: "YYYY-MM-DD" + - name: Author 2 + github: author2 + orcid: 0000-0000-0000-0000 + affiliation: Affiliation Y + role: Co-author + date: "YYYY-MM-DD" + - name: Author 3 + orcid: 0000-0000-0000-0000 + github: author3 + affiliation: Affiliation Z + role: Co-author + date: "YYYY-MM-DD" +endorsers: + - name: Endorser 1 + github: endorser1 + orcid: 0000-0000-0000-0000 + affiliation: Affiliation A + role: Endorser + date: "YYYY-MM-DD" + reference: https://example.com +editors: + - name: Josh Moore + github: joshmoore + orcid: 0000-0000-0000-0000 + affiliation: German BioImaging e.V. + role: Editor + date: "YYYY-MM-DD" +reference_pr: https://github.com/ome/ngff/pull/XXX +manual_status: D3 +status_note: authors open PR +description: A few words naming what the RFC changes, for the RFC listing +date: YYYY-MM-DD +--- + +(rfc-template)= + +# How to use it + +Add the authors and editors to the YAML front matter above. ORCID and GitHub IDs are optional but recommended, as is an `affiliation_url` (e.g. a ROR or homepage) which turns the institution into a link. Add also a date per author and editor, **quoted**, as new authors and editors may be added through the process. + +After opening a PR for the RFC, add the reference PR to the `reference_pr` field in the YAML front matter above. + +The `manual_status` field holds the [status code](/resources/rfc-status-codes/index) the RFC is currently in, and is updated by hand as the RFC moves through the process; `status_note` is an optional fragment explaining it, e.g. `superseded by RFC-8`. Together with `description` and `date` they also fill in this RFC's row of the [RFC listing](/rfc/index). Add `ome_zarr_version` once an RFC lands in a released version of the specification. + +The full list of fields is described by the LinkML schema in +[`rfc/schema/front_matter.yaml`](https://github.com/ome/ngff/blob/main/rfc/schema/front_matter.yaml), +which is what CI checks every RFC against. To check a draft yourself, run +`pip install linkml` and then `python rfc/schema/validate.py` from the root of the repository. + +There MUST be at least one "Corresponding Author", and at least one "Editor". + +There MAY be multiple "Co-author" and "Co-editor". + +There MAY be multiple explicit "endorsers", but that is not required. An external link may be provided in the `reference` field for each endorser. + +Add also a reference date before merging the RFC, to indicate when the RFC was moved from DRAFT to RFC status. Ideally it should be the date of the reference PR merge, but it can be an approximation. + +A MyST target anchor should be added to the rfc, in the form + +`(rfcs:rfcX:versionY)=`, to indicate a particular version + +or + +`(rfcs:rfcX)=`, to indicate the main document + +# RFC X: The RFC Title + +(rfcs:rfcX)= Summary: Sentence fragment summary @@ -7,16 +82,11 @@ Summary: Sentence fragment summary Brief description of status, including the state identifier, e.g. `R4` -| Name | GitHub Handle | Institution | Date | Status | -| --------- | ------------- | ----------- | ---------- | ------------------------------------- | -| Author | N/A | N/A | xxxx-xx-xx | Author | -| Author | N/A | N/A | xxxx-xx-xx | Author; Implemented (link to release) | -| Commenter | N/A | N/A | xxxx-xx-xx | Endorse (link to comment) | -| Commenter | N/A | N/A | xxxx-xx-xx | Not yet (link to comment) | -| Endorser | N/A | N/A | xxxx-xx-xx | Endorse (no link needed) | -| Endorser | N/A | N/A | xxxx-xx-xx | Implementing (link to branch/PR) | -| Reviewer | N/A | N/A | xxxx-xx-xx | Endorse (link to comment) | -| Reviewer | N/A | N/A | xxxx-xx-xx | Requested by editor | +Then, this magic that will pull information from the YAML front matters and display it in a table: + +```{rfc-status} + +``` ## Overview @@ -32,7 +102,7 @@ The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole page in some cases. The \*\*guiding goal of the background section\*\* is: as a newcomer to this project (new employee, team transfer), can I read the background section and follow any links to get the -full context of why this change is necessary? +full context of why this change is necessary? If you can't show a random engineer the background section and have them acquire nearly full context on the necessity for the RFC, then the background @@ -72,18 +142,18 @@ interpreted as described in [IETF RFC 2119](https://tools.ietf.org/html/rfc2119) Who has a stake in whether this RFC is accepted? -* Facilitator: The person appointed to shepherd this RFC through the RFC +- Facilitator: The person appointed to shepherd this RFC through the RFC process. -* Reviewers: List people whose vote (+1 or -1) will be taken into consideration +- Reviewers: List people whose vote (+1 or -1) will be taken into consideration by the editor when deciding whether this RFC is accepted or rejected. Where applicable, also list the area they are expected to focus on. In some cases this section may be initially left blank and stakeholder discovery completed after an initial round of socialization. Care should be taken to keep the number of reviewers manageable, although the exact number will depend on the scope of the RFC in question. -* Consulted: List people who should review the RFC, but whose approval is not +- Consulted: List people who should review the RFC, but whose approval is not required. -* Socialization: This section may be used to describe how the design was +- Socialization: This section may be used to describe how the design was socialized before advancing to the "Iterate" stage of the RFC process. For example: "This RFC was discussed at a working group meetings from 20xx-20yy" @@ -92,7 +162,7 @@ Who has a stake in whether this RFC is accepted? Many RFCs have an "implementation" section which details how the implementation will work. This section should explain the rough specification changes. The goal is to give an idea to reviewers about the subsystems that require change -and the surface area of those changes. +and the surface area of those changes. This knowledge can result in recommendations for alternate approaches that perhaps are idiomatic to the project or result in less packages touched. Or, it @@ -105,19 +175,19 @@ issues or unknown unknowns prior to writing any real code. ## Drawbacks, risks, alternatives, and unknowns (Recommended Header) -* What are the costs of implementing this proposal? -* What known risks exist? What factors may complicate your project? Include: +- What are the costs of implementing this proposal? +- What known risks exist? What factors may complicate your project? Include: security, complexity, compatibility, latency, service immaturity, lack of team expertise, etc. -* What other strategies might solve the same problem? -* What questions still need to be resolved, or details iterated upon, to accept +- What other strategies might solve the same problem? +- What questions still need to be resolved, or details iterated upon, to accept this proposal? Your answer to this is likely to evolve as the proposal evolves. -* What parts of the design do you expect to resolve through the RFC process +- What parts of the design do you expect to resolve through the RFC process before this gets merged? -* What parts of the design do you expect to resolve through the implementation +- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? -* What related issues do you consider out of scope for this RFC that could be +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? @@ -212,11 +282,13 @@ example, creating a conformance test suite for this purpose. It is strongly recommended to provide as many examples as possible of what both users and developers can expect if the RFC were to be accepted. Sample data should be shared publicly. If longer-term is not available, contact the **Editors** for assistance. (additional-considerations)= + ## Additional considerations (Optional Header) -Most RFCs will not need to consider all the following issues. They are included here as a checklist +Most RFCs will not need to consider all the following issues. They are included here as a checklist ### Security + What impact will this proposal have on security? Does the proposal require a security review? @@ -274,9 +346,9 @@ a RFC goes beyond "Heading 4," and rare itself that "Heading 4" is reached. When making lists, it is common to bold the first phrase/sentence/word to bring some category or point to attention. For example, a list of API considerations: -* *Format* should be widgets -* *Protocol* should be widgets-rpc -* *Backwards* compatibility should be considered. +- _Format_ should be widgets +- _Protocol_ should be widgets-rpc +- _Backwards_ compatibility should be considered. ### Spelling @@ -294,9 +366,8 @@ CLI output samples are similar to code samples but should be highlighted with the color they'll output if it is known so that the RFC could also cover formatting as part of the user experience. - func example() { - <-make(chan struct{}) - } - + func example() { + <-make(chan struct{}) + } Note: This template is based on the [RFC template from Hashicorp](https://works.hashicorp.com/articles/rfc-template) used with permission. diff --git a/rfc/10/index.md b/rfc/10/index.md index 1f4b9273f..6acc55d07 100644 --- a/rfc/10/index.md +++ b/rfc/10/index.md @@ -1,16 +1,28 @@ +--- +authors: + - name: Josh Moore + github: joshmoore + affiliation: German BioImaging e.V. + role: Co-author + date: "2026-07-03" + - name: Virginie Uhlmann + github: vuhlmann + affiliation: University of Zürich + role: Co-author + date: "2026-07-03" +manual_status: D4 +description: NGFF Governance and the Editorial Board +date: 2026-07-03 +--- + # RFC-10: NGFF Governance and the Editorial Board Define the composition and processes of NGFF governance bodies. ## Status -This RFC is currently in state `D3` (Authors open PR). - -| Role | Name | GitHub Handle | Institution | Date | Status | -| --------- | ---------------- | ----------------------------------------- | ---------------------------------------- | ---------- | ------- | -| Author | Josh Moore | [joshmoore](https://github.com/joshmoore) | German BioImaging e.V. | 2026-07-03 | Author | -| Author | Virginie Uhlmann | [vuhlmann](https://github.com/vuhlmann) | University of Zürich | 2026-07-03 | Author | - +```{rfc-status} +``` ```{toctree} :hidden: @@ -166,11 +178,11 @@ deciding vote. Within the Editorial Board, the Managing Editor shall: -* Schedule and chair recurring Editorial Board meetings. -* Maintain the agenda and track blocking RFCs. -* Determine when discussion has reached sufficient maturity to call a vote. -* Initiate formal votes when required. -* Ensure that votes and rationales are documented publicly. +* Schedule and chair recurring Editorial Board meetings. +* Maintain the agenda and track blocking RFCs. +* Determine when discussion has reached sufficient maturity to call a vote. +* Initiate formal votes when required. +* Ensure that votes and rationales are documented publicly. * Monitor timeline risks for delivery of NGFF versions. The ME is a voting member of the Editorial Board. The ME does not possess @@ -204,10 +216,10 @@ The EB as a whole: EB Members are expected to: -* Attend recurring Editorial Board meetings. -* Stay informed on the status of all RFCs. -* Participate in votes in a timely fashion. -* Engage constructively in consensus-building discussions. +* Attend recurring Editorial Board meetings. +* Stay informed on the status of all RFCs. +* Participate in votes in a timely fashion. +* Engage constructively in consensus-building discussions. * Prioritize the stability and interoperability goals of NGFF. Membership on the Editorial Board implies an active and ongoing commitment of @@ -230,7 +242,7 @@ reasonable opportunity for public review and community input. A formal vote may be called when: -* Consensus has not emerged after reasonable discussion; or +* Consensus has not emerged after reasonable discussion; or * Timeline constraints require resolution. The Managing Editor determines when voting is appropriate. Quorum is defined as @@ -240,14 +252,14 @@ quorum and abstentions do not count toward the majority calculation. In the event of a tied vote: -* A follow-up discussion period may be initiated; or -* If still tied, the Managing Editor may cast a deciding vote; or +* A follow-up discussion period may be initiated; or +* If still tied, the Managing Editor may cast a deciding vote; or * The matter may be escalated to the OMG (if procedural or structural). Board members who are primary authors of an RFC: -* May participate in discussion. -* May vote (unless voluntarily recused). +* May participate in discussion. +* May vote (unless voluntarily recused). * Must have authorship recorded in the decision log. The Board may adopt a norm encouraging voluntary abstention in cases of @@ -258,9 +270,9 @@ policy. The following shall be publicly documented: -* Meeting summaries. -* Votes and outcomes. -* Escalations, if any. +* Meeting summaries. +* Votes and outcomes. +* Escalations, if any. * Rationale for binary decisions in the form of a Board Review against the related RFC. The governance process shall remain consistent with NGFF’s existing public RFC model. @@ -272,17 +284,17 @@ effect until either the RFC is withdrawn or is replaced by a subsequent RFC. The OMG may periodically initiate a review of: -* Whether the Editorial Board should continue, -* Be reconstituted, +* Whether the Editorial Board should continue, +* Be reconstituted, * Or be dissolved. ## Stakeholders A clear and stable editorial process is essential for all participants in the NGFF ecosystem. In particular: -* **RFC authors** require predictable timelines and decision pathways to ensure that proposals can progress efficiently and reach resolution. -* **Reviewers** depend on a well-defined process to understand how their feedback will be incorporated and when decisions will be made. -* **Commenters** benefit from transparency and clarity in how discussions evolve into outcomes. +* **RFC authors** require predictable timelines and decision pathways to ensure that proposals can progress efficiently and reach resolution. +* **Reviewers** depend on a well-defined process to understand how their feedback will be incorporated and when decisions will be made. +* **Commenters** benefit from transparency and clarity in how discussions evolve into outcomes. * **NGFF implementers** rely on timely and unambiguous decisions to guide development, avoid fragmentation, and ensure interoperability across tools and platforms. Establishing a well-defined governance structure for NGFF 1.0 supports @@ -293,15 +305,15 @@ progress toward a stable and widely adoptable specification. Alternatives -* Continuing without a formal editorial board was considered but would risk delays in resolving critical blocking decisions. +* Continuing without a formal editorial board was considered but would risk delays in resolving critical blocking decisions. * Expanding the editorial board more widely was considered but deprioritized to - ensure that members reflect those with ongoing, investment-based involvement. + ensure that members reflect those with ongoing, investment-based involvement. * Having a single editor was never a design goal Risks: -* While learning how to function as an editorial board we postpone 1.0 (i.e. better to keep a sole-decision maker) -* Agreement was always an issue, but should make the spec stronger. +* While learning how to function as an editorial board we postpone 1.0 (i.e. better to keep a sole-decision maker) +* Agreement was always an issue, but should make the spec stronger. * Time commitments; mitigation: rotation, or further funding ## Prior art and references @@ -311,13 +323,13 @@ both open-source software and standards communities. Key references include: * **Apache Project Management Committees (PMCs)**: Clear delegation of authority, membership ratification, and escalation pathways serve as a model - for structured, accountable decision-making. + for structured, accountable decision-making. * **W3C Process and Charter Guidelines**: Formal charters and defined roles provide a framework for transparency, membership expectations, and procedural - clarity. + clarity. * **GitHub Minimal Viable Governance (MVG) Project**: Lightweight governance principles for small-to-medium communities inform approaches to - decision-making, rotation, and minimal bureaucracy. + decision-making, rotation, and minimal bureaucracy. * **Contemporary open-source specification projects**: Projects such as Zarr and RO-Crate illustrate practical governance solutions for evolving data standards, including Editorial Boards, RFC-style proposals, and iterative @@ -333,10 +345,10 @@ Looking beyond the finalization of NGFF 1.0, several governance refinements coul * **Time-limited bodies:** Editorial or decision-making boards could be established for specific milestones or releases, with automatic sunset or - re-evaluation periods to ensure flexibility and responsiveness. + re-evaluation periods to ensure flexibility and responsiveness. * **Rotating schedules:** Membership or leadership roles could rotate periodically to balance workload, incorporate fresh perspectives, and broaden - community engagement. + community engagement. * **Representatives from “member” bodies:** Where appropriate, members from contributing institutions or stakeholder groups could be formally represented on boards or committees, ensuring that diverse perspectives inform decisions diff --git a/rfc/2/index.md b/rfc/2/index.md index 948a54cb4..26504d024 100644 --- a/rfc/2/index.md +++ b/rfc/2/index.md @@ -1,3 +1,76 @@ +--- +authors: + - name: Norman Rzepka + github: normanrz + affiliation: scalable minds + affiliation_url: https://scalableminds.com + role: Author + date: "2024-02-14" +endorsers: + - name: Davis Bennett + github: d-v-b + date: "2024-02-14" + - name: Kevin Yamauchi + github: kevinyamauchi + affiliation: ETH Zürich + date: "2024-02-16" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1947942934 + - name: John Bogovic + github: bogovicj + affiliation: HHMI Janelia Research Campus + date: "2024-02-16" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1948547356 + - name: Matthew Hartley + github: matthewh-ebi + affiliation: EMBL-EBI + date: "2024-02-16" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1948912814 + - name: Christian Tischer + github: tischi + affiliation: EMBL + date: "2024-02-16" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1949058616 + - name: Joel Lüthi + github: jluethi + affiliation: BioVisionCenter, University of Zurich + date: "2024-02-16" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1949333769 + - name: Constantin Pape + github: constantinpape + affiliation: University Göttingen + date: "2024-02-18" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1951318754 + - name: Will Moore + github: will-moore + affiliation: OME, University of Dundee + date: "2024-02-19" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1952057704 + - name: Juan Nunez-Iglesias + github: jni + affiliation: Biomedicine Discovery Institute, Monash University + date: "2024-02-20" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1953922897 + - name: Eric Perlman + github: perlman + date: "2024-02-22" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1960272942 + - name: Ziwen Liu + github: ziw-liu + affiliation: Chan Zuckerberg Biohub + date: "2024-03-12" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1992588774 + - name: Lachlan Deakin + github: LDeakin + affiliation: Australian National University + date: "2024-03-14" + reference: https://github.com/ome/ngff/pull/227#issuecomment-1998594492 +reference_pr: https://github.com/ome/ngff/pull/227 +manual_status: S4 +description: Zarr V3 Support +ome_zarr_version: "0.5" +date: 2024-02-14 +--- + # RFC-2: Zarr v3 ```{toctree} @@ -13,133 +86,7 @@ Adopt the version 3 of Zarr for OME-Zarr. ## Status -This RFC is currently in SPEC state (S1). - -```{list-table} Record -:widths: 8, 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Role - - Name - - GitHub Handle - - Institution - - Date - - Status -* - Author - - Norman Rzepka - - [normanrz](https://github.com/normanrz) - - [scalable minds](https://scalableminds.com) - - 2024-02-14 - - -* - Endorser - - Davis Bennett - - [d-v-b](https://github.com/d-v-b) - - - - 2024-02-14 - - Endorse -* - Endorser - - Kevin Yamauchi - - [kevinyamauchi](https://github.com/kevinyamauchi) - - ETH Zürich - - 2024-02-16 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1947942934) -* - Endorser - - John Bogovic - - [bogovicj](https://github.com/bogovicj) - - HHMI Janelia Research Campus - - 2024-02-16 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1948547356) -* - Endorser - - Matthew Hartley - - [matthewh-ebi](https://github.com/matthewh-ebi) - - EMBL-EBI - - 2024-02-16 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1948912814) -* - Endorser - - Christian Tischer - - [tischi](https://github.com/tischi) - - EMBL - - 2024-02-16 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1949058616) -* - Endorser - - Joel Lüthi - - [jluethi](https://github.com/jluethi) - - BioVisionCenter, University of Zurich - - 2024-02-16 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1949333769) -* - Endorser - - Constantin Pape - - [constantinpape](https://github.com/constantinpape) - - University Göttingen - - 2024-02-18 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1951318754) -* - Endorser - - Will Moore - - [will-moore](https://github.com/will-moore) - - OME, University of Dundee - - 2024-02-19 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1952057704) -* - Endorser - - Juan Nunez-Iglesias - - [jni](https://github.com/jni) - - Biomedicine Discovery Institute, Monash University - - 2024-02-20 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1953922897) -* - Endorser - - Eric Perlman - - [perlman](https://github.com/perlman) - - - - 2024-02-22 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1960272942) -* - Endorser - - Ziwen Liu - - [ziw-liu](https://github.com/ziw-liu) - - Chan Zuckerberg Biohub - - 2024-03-12 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1992588774) -* - Endorser - - Lachlan Deakin - - [LDeakin](https://github.com/LDeakin) - - Australian National University - - 2024-03-14 - - [Endorse](https://github.com/ome/ngff/pull/227#issuecomment-1998594492) -* - Reviewer - - Melissa Linkert, Sébastien Besson, Chris Allan, Jason Swedlow - - [glencoesoftware](https://github.com/glencoesoftware) - - Glencoe Software - - 2024-05-23 - - [Review](./reviews/1/index) -* - Reviewer - - Yaroslav O. Halchenko - - [yarikoptic](https://github.com/yarikoptic) - - Dartmouth College, DANDI Project - - 2024-06-10 - - [Review](./reviews/2/index) -* - Reviewer - - Jeremy Maitin-Shepard - - [jbms](https://github.com/jbms) - - Google - - 2024-04-30 - - [Review](./reviews/3/index) -* - Reviewer - - Melissa Linkert, Sébastien Besson, Chris Allan, Jason Swedlow - - [glencoesoftware](https://github.com/glencoesoftware) - - Glencoe Software - - 2024-08-05 - - [Accept](./reviews/1b/index) -* - Reviewer - - Jeremy Maitin-Shepard - - [jbms](https://github.com/jbms) - - Google - - 2024-09-11 - - [Accept](./reviews/3b/index) -* - Reviewer - - Yaroslav O. Halchenko - - [yarikoptic](https://github.com/yarikoptic) - - Dartmouth College, DANDI Project - - 2024-09-11 - - [Accept](./reviews/2b/index) +```{rfc-status} ``` ## Overview @@ -282,7 +229,7 @@ Preliminary work of this RFC has been discussed in: ## Implementation -OME-Zarr implementations can rely on existing Zarr libraries to implement the adoption of Zarr v3. +OME-Zarr implementations can rely on existing Zarr libraries to implement the adoption of Zarr v3. See [Background](#background) for a list of v3-capable Zarr libraries. Support for the OME-Zarr 0.5 metadata is under development in [ome-zarr-py](https://github.com/ome/ome-zarr-py/pull/383/files) and other implementations. diff --git a/rfc/2/reviews/1/index.md b/rfc/2/reviews/1/index.md index 1c23db3b2..b04228708 100644 --- a/rfc/2/reviews/1/index.md +++ b/rfc/2/reviews/1/index.md @@ -1,13 +1,28 @@ +--- +authors: + - name: Sébastien Besson + affiliation: Glencoe Software + github: sbesson + - name: Chris Allan + affiliation: Glencoe Software + - name: Marc Bruce + affiliation: Glencoe Software + - name: Jason Swedlow + affiliation: Glencoe Software + github: jrswedlow + - name: Melissa Linkert + affiliation: Glencoe Software + github: melissalinkert +date: 2024-05-23 +recommendation: major_changes +--- + # Review 1 ## Review authors -This review was written by the following Glencoe Software team members: -- Sébastien Besson -- Chris Allan -- Marc Bruce -- Jason Swedlow -- Melissa Linkert +```{document-authors} +``` ## Summary diff --git a/rfc/2/reviews/1b/index.md b/rfc/2/reviews/1b/index.md index 54731de40..4cbed2f3a 100644 --- a/rfc/2/reviews/1b/index.md +++ b/rfc/2/reviews/1b/index.md @@ -1,10 +1,21 @@ +--- +authors: + - name: Sébastien Besson + affiliation: Glencoe Software + github: sbesson + - name: Melissa Linkert + affiliation: Glencoe Software + github: melissalinkert +date: 2024-08-05 +recommendation: accept +--- + # Review 1 (update) ## Review authors -This review was written by the following Glencoe Software team members: -- Sébastien Besson -- Melissa Linkert +```{document-authors} +``` ## Summary diff --git a/rfc/2/reviews/2/index.md b/rfc/2/reviews/2/index.md index 44615a930..17399ed1a 100644 --- a/rfc/2/reviews/2/index.md +++ b/rfc/2/reviews/2/index.md @@ -1,8 +1,18 @@ +--- +authors: + - name: Yaroslav O. Halchenko + affiliation: Dartmouth College, DANDI Project + github: yarikoptic +date: 2024-06-10 +recommendation: major_changes +--- + # Review 2 ## Review authors -This review was written by: -- Yaroslav O. Halchenko (Dartmouth College, DANDI Project) + +```{document-authors} +``` ## Summary diff --git a/rfc/2/reviews/2b/index.md b/rfc/2/reviews/2b/index.md index a30f411eb..f8768ff95 100644 --- a/rfc/2/reviews/2b/index.md +++ b/rfc/2/reviews/2b/index.md @@ -1,8 +1,18 @@ +--- +authors: + - name: Yaroslav O. Halchenko + affiliation: Dartmouth College, DANDI Project + github: yarikoptic +date: 2024-09-11 +recommendation: accept +--- + # Review 2 (update) ## Review authors -This review was written by: -- Yaroslav O. Halchenko (Dartmouth College, DANDI Project) + +```{document-authors} +``` ## Summary diff --git a/rfc/2/reviews/3/index.md b/rfc/2/reviews/3/index.md index b7c9ab318..ec7bd51e4 100644 --- a/rfc/2/reviews/3/index.md +++ b/rfc/2/reviews/3/index.md @@ -1,8 +1,20 @@ +--- +authors: + - name: Jeremy Maitin-Shepard + affiliation: Google + github: jbms +date: 2024-04-30 +recommendation: +--- + # Review 3 ## Review authors -This review was submitted by Jeremy Maitin-Shepard (Google) via email. +```{document-authors} +``` + +This review was submitted via email. ## Initial feedback diff --git a/rfc/2/reviews/3b/index.md b/rfc/2/reviews/3b/index.md index 096cf9643..84ca6b3ea 100644 --- a/rfc/2/reviews/3b/index.md +++ b/rfc/2/reviews/3b/index.md @@ -1,8 +1,20 @@ +--- +authors: + - name: Jeremy Maitin-Shepard + affiliation: Google + github: jbms +date: 2024-09-11 +recommendation: accept +--- + # Review 3 (update) ## Review authors -This review was submitted by Jeremy Maitin-Shepard (Google) via email. +```{document-authors} +``` + +This review was submitted via email. ## Recommendation diff --git a/rfc/3/comments/1/index.md b/rfc/3/comments/1/index.md index 17c3d9e0e..dff51e337 100644 --- a/rfc/3/comments/1/index.md +++ b/rfc/3/comments/1/index.md @@ -1,10 +1,21 @@ +--- +authors: + - name: Benedikt Best + github: btbest + orcid: 0000-0001-6965-1117 +date: "2026-02-02" +recommendation: accept +--- + # RFC-3: Comment 1 (rfcs:rfc3:comment1)= ## Comment authors -This comment was written by Benedikt Best (https://orcid.org/0000-0001-6965-1117) +```{document-authors} + +``` ## Conflicts of interest (optional) diff --git a/rfc/3/comments/2/index.md b/rfc/3/comments/2/index.md index 802f26a47..98923bb42 100644 --- a/rfc/3/comments/2/index.md +++ b/rfc/3/comments/2/index.md @@ -1,10 +1,22 @@ +--- +authors: + - name: Chris Barnes + email: chris.barnes@gerbi-gmb.de + github: clbarnes + affiliation: German BioImaging +date: "2026-02-05" +recommendation: accept +--- + # RFC-3: Comment 2 (rfcs:rfc3:comment2)= ## Comment authors -Chris Barnes +```{document-authors} + +``` ## Conflicts of interest diff --git a/rfc/3/comments/3/index.md b/rfc/3/comments/3/index.md index 02e3e4051..211a9f030 100644 --- a/rfc/3/comments/3/index.md +++ b/rfc/3/comments/3/index.md @@ -1,10 +1,21 @@ +--- +authors: + - name: Cornelia Wetzker + github: cwetzker + orcid: 0000-0002-8367-5163 + affiliation: Technische Universität Dresden +date: "2026-03-19" +--- + # RFC-3: Comment 3 (rfcs:rfc3:comment3)= -| **Role** | Name | GitHub Handle | Institution | -|----------|------|---------------|-------------| -| **Author** | [Cornelia Wetzker](https://orcid.org/0000-0002-8367-5163) | [cwetzker](https://github.com/cwetzker) | TU Dresden | +```{document-authors} + +``` + + I would like to contribute a further imaging modality to be considered in the current and future changes of the OME-Zarr format. Fluorescence lifetime imaging microscopy (FLIM) is an imaging setup that detects the fluorescence lifetime of fluorophores as an additional axis of data using specialized laser, detector and electronics setups. This lifetime is assessed by detection of photon arrival times relative to the latest pulse of a pulsed laser. This creates so called decay histograms for each pixel/voxel of a dataset that can be considered an additional dimension or axis of the dataset and allows the calculation of the specific lifetime(s) of fluorescence. @@ -16,4 +27,4 @@ The lifetime axis could be included using for example using the following axis m The unit for the lifetime axis is typically nanoseconds, or milliseconds for more rarely performed phosphorescence lifetime imaging (PLIM). Consequently, this would require the option of a second axis of 'type:time'. There are technical setups that are capable to and use cases that may benefit from the generation of datasets that have both time axes, e.g. in case FLIM is performed in time-series mode. Consequently, there may be scenarios that create 6 dimensional datasets with xyzctu dimensions that exceed the current limitation of 5 axes for OME-Zarr arrays. -Since FLIM data is partially stored in proprietary file formats, the availability and access to analysis workflows is limited to date. Thus, the possibility of storage of FLIM datasets in OME-Zarr format would increase the flexibility for data visualization and analysis options for imaging scientists and stimulate the development of analysis workflows that could be tailored to specific project needs if required. +Since FLIM data is partially stored in proprietary file formats, the availability and access to analysis workflows is limited to date. Thus, the possibility of storage of FLIM datasets in OME-Zarr format would increase the flexibility for data visualization and analysis options for imaging scientists and stimulate the development of analysis workflows that could be tailored to specific project needs if required. diff --git a/rfc/3/index.md b/rfc/3/index.md index 1dd2b4ff9..1c40bd53a 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -1,3 +1,61 @@ +--- +authors: + - name: Juan Nunez-Iglesias + github: jni + affiliation: Monash University + role: Corresponding Author + date: "2024-05-21" +endorsers: + - name: Talley Lambert + github: tlambert03 + affiliation: Harvard Medical School + date: "2024-05-21" + reference: https://github.com/ome/ngff/pull/239#issuecomment-2122795327 + - name: Norman Rzepka + github: normanrz + affiliation: Scalable Minds + date: "2024-05-21" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: Davis Bennett + github: d-v-b + date: "2024-05-21" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: Doug Shepherd + github: dpshepherd + affiliation: Arizona State University + date: "2024-05-22" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: John Bogovic + github: bogovicj + affiliation: HHMI Janelia Research Campus + date: "2024-05-22" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: Eric Perlman + github: perlman + date: "2024-05-22" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: Lachlan Deakin + github: LDeakin + affiliation: Australian National University + date: "2024-05-22" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 + - name: Sebastian Rhode + github: sebi06 + affiliation: Carl Zeiss Microscopy GmbH + date: "2024-06-05" + reference: https://github.com/ome/ngff/pull/239#issue-2308436425 +editors: + - name: Josh Moore + github: joshmoore + affiliation: German BioImaging e.V. + role: Editor + date: "2024-05-21" +reference_pr: https://github.com/ome/ngff/pull/239 +manual_status: R1 +description: Remove axis restrictions +date: "2024-05-21" +--- + # RFC-3: more dimensions for thee ```{toctree} @@ -14,104 +72,7 @@ stored in OME-Zarr arrays. ## Status -This RFC is currently in RFC state `R1` (send for review). - -```{list-table} Record -:widths: 8, 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Role - - Name - - GitHub Handle - - Institution - - Date - - Status -* - Author - - Juan Nunez-Iglesias - - [jni](https://github.com/jni) - - Monash University - - 2024-05-21 - - -* - Endorser - - Talley Lambert - - [tlambert03](https://github.com/tlambert03) - - Harvard Medical School - - 2024-05-21 - - [Endorse](https://github.com/ome/ngff/pull/239#issuecomment-2122795327) -* - Endorser - - Norman Rzepka - - [normanrz](https://github.com/normanrz) - - Scalable Minds - - 2024-05-21 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - Davis Bennett - - [d-v-b](https://github.com/d-v-b) - - - - 2024-05-21 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - Doug Shepherd - - [dpshepherd](https://github.com/dpshepherd) - - Arizona State University - - 2024-05-22 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - John Bogovic - - [bogovicj](https://github.com/bogovicj) - - HHMI Janelia Research Campus - - 2024-05-22 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - Eric Perlman - - [perlman](https://github.com/perlman) - - - - 2024-05-22 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - Lachlan Deakin - - [LDeakin](https://github.com/LDeakin) - - Australian National University - - 2024-05-22 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Endorser - - Sebastian Rhode - - [sebi06](https://github.com/sebi06) - - Carl Zeiss Microscopy GmbH - - 2024-06-05 - - [Endorse](https://github.com/ome/ngff/pull/239#issue-2308436425) -* - Commenter - - Benedikt Best - - [btbest](https://github.com/btbest) - - - - 2026-02-02 - - [Comment](./comments/1/index) -* - Commenter - - Chris Barnes - - [clbarnes](https://github.com/clbarnes) - - German BioImaging - - 2026-02-05 - - [Comment](./comments/2/index) -* - Commenter - - Cornelia Wetzker - - [cwetzker](https://github.com/cwetzker) - - Technische Universität Dresden - - 2026-03-19 - - [Comment](./comments/3/index) -* - Reviewer - - Melissa Linkert, Sébastien Besson - - [melissalinkert](https://github.com/melissalinkert), [sbesson](https://github.com/sbesson) - - [Glencoe Software](https://github.com/glencoesoftware) - - 2026-08-04 - - [Review](#rfcs:rfc3:review1) -* - Reviewer - - Matthew McCormick, Valentin Boussot - - [thewtex](https://github.com/thewtex), - [vboussot](https://github.com/vboussot) - - [Fideus Labs](https://github.com/fideus-labs) - - 2026-08-28 - - [Review](#rfcs:rfc3:review2) +```{rfc-status} ``` ## Overview diff --git a/rfc/3/reviews/1/index.md b/rfc/3/reviews/1/index.md index 61119e020..66c1a72f3 100644 --- a/rfc/3/reviews/1/index.md +++ b/rfc/3/reviews/1/index.md @@ -1,13 +1,26 @@ +--- +authors: + - name: Melissa Linkert + github: melissalinkert + affiliation: Glencoe Software + affiliation_url: https://github.com/glencoesoftware + - name: Sébastien Besson + github: sbesson + affiliation: Glencoe Software + affiliation_url: https://github.com/glencoesoftware +date: "2026-08-04" +recommendation: accept +--- + # RFC-3: Review 1 (rfcs:rfc3:review1)= ## Review authors -This review was written by the following members of the [Glencoe Software team](https://github.com/glencoesoftware): +```{document-authors} -- [Melissa Linkert](https://github.com/melissalinkert) -- [Sébastien Besson](https://github.com/sbesson) +``` ## Conflicts of interest diff --git a/rfc/3/reviews/2/index.md b/rfc/3/reviews/2/index.md index 1a7bafa86..a64cbff69 100644 --- a/rfc/3/reviews/2/index.md +++ b/rfc/3/reviews/2/index.md @@ -1,11 +1,25 @@ +--- +authors: + - name: Matthew McCormick + affiliation: Fideus Labs + affiliation_url: https://github.com/fideus-labs + github: thewtex + - name: Valentin Boussot + affiliation: Fideus Labs + affiliation_url: https://github.com/fideus-labs + github: vboussot +date: 2026-08-28 +recommendation: minor_changes +--- + # RFC-3: Review 2 (rfcs:rfc3:review2)= ## Review authors -- Matthew McCormick, Fideus Labs -- Valentin Boussot, Fideus Labs +```{document-authors} +``` ## Conflicts of interest (optional) diff --git a/rfc/4/comments/1/index.md b/rfc/4/comments/1/index.md index c5349a5cb..c701299fe 100644 --- a/rfc/4/comments/1/index.md +++ b/rfc/4/comments/1/index.md @@ -1,8 +1,19 @@ -# RFC-4 comment +--- +authors: + - name: David Stansby + github: dstansby +date: 2025-04-02 +--- + +# RFC-4 comment 1 + +(rfcs:rfc4:comment1)= ## Comment author -David Stansby +```{document-authors} + +``` ## Conflicts of interest (optional) diff --git a/rfc/4/comments/2/index.md b/rfc/4/comments/2/index.md index 4877f0e2d..65f00f171 100644 --- a/rfc/4/comments/2/index.md +++ b/rfc/4/comments/2/index.md @@ -1,10 +1,26 @@ -# RFC-4: Comment 2 +--- +authors: + - name: Chris Barnes + email: chris.barnes@gerbi-gmb.de + github: clbarnes + affiliation: German BioImaging +date: 2026-02-05 +recommendation: accept +--- + +# RFC-4 comment 2 (rfcs:rfc4:comment2)= -## Review authors +## Comment author + +```{document-authors} + +``` -Chris Barnes +# RFC-4: Comment 2 + +(rfcs:rfc4:comment2)= ## Conflicts of interest diff --git a/rfc/4/index.md b/rfc/4/index.md index fbe745887..cf60d4dd1 100644 --- a/rfc/4/index.md +++ b/rfc/4/index.md @@ -1,3 +1,25 @@ +--- +authors: + - name: David Feng + github: dyf + affiliation: Allen Institute for Neural Dynamics + role: Co-author + date: "2023-07-26" + - name: Matthew McCormick + github: thewtex + affiliation: Fideus Labs + role: Co-author + date: "2024-07-27" + - name: Wouter-Michiel Vierdag + github: melonora + affiliation: EMBL + role: Co-author + date: "2025-07-16" +manual_status: S1 +description: Axis Anatomical Orientation +date: 2023-07-26 +--- + # RFC-4: Axis Orientation ```{toctree} @@ -13,61 +35,7 @@ Summary: An optional, explicit field for specification of imaging axis orientati ## Status -This RFC is currently in RFC state `S1` (Accepted). - -```{list-table} Record -:widths: 8, 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Role - - Name - - GitHub Handle - - Institution - - Date - - Status -* - Author - - David Feng - - [dyf](https://github.com/dyf) - - Allen Institute for Neural Dynamics - - 2023-07-26 - - -* - Author - - Matthew McCormick - - [thewtex](https://github.com/thewtex) - - Fideus Labs - - 2024-07-27 - - -* - Author - - Wouter-Michiel Vierdag - - [melonora](https://github.com/melonora) - - EMBL - - 2025-07-16 - - -* - Commenter - - David Stansby - - [dstansby](https://github.com/dstansby) - - - - 2025-04-02 - - [Comment](./comments/1/index) -* - Reviewer - - Juan Nunez-Iglesias - - [jni](https://github.com/jni) - - Monash University - - 2025-08-05 - - [Review](./reviews/2/index) -* - Commenter - - Chris Barnes - - [clbarnes](https://github.com/clbarnes) - - German BioImaging - - 2026-02-05 - - [Comment](./comments/2/index) -* - Reviewer - - Dave Horsfall - - [davehorsfall](https://github.com/davehorsfall) - - Haniffa Lab - - 2026-02-27 - - [Review](./reviews/3/index) +```{rfc-status} ``` ## Overview diff --git a/rfc/4/responses/1/index.md b/rfc/4/responses/1/index.md index 06de96013..29621b3a5 100644 --- a/rfc/4/responses/1/index.md +++ b/rfc/4/responses/1/index.md @@ -1,3 +1,11 @@ +--- +authors: + - name: Matthew McCormick + github: thewtex + affiliation: Fideus Labs +date: 2024-07-27 +--- + # RFC-4: Response 1 ## Summary of Changes @@ -26,6 +34,7 @@ We have implemented all three significant recommendations from Juan's review: ``` This structure can support multiple orientation domains including: + - **Anatomical**: left-to-right, anterior-to-posterior, etc. - **Engineering/Microfluidics**: upstream/downstream - **Geographical**: north/south, east/west @@ -91,7 +100,7 @@ The RFC now includes concrete JSON examples showing the complete axis configurat "name": "x", "type": "space", "unit": "millimeter", - "orientation": {"type": "anatomical", "value": "left-to-right"} + "orientation": { "type": "anatomical", "value": "left-to-right" } } ] } @@ -105,4 +114,4 @@ We added clear guidance on how the structure can be extended for future orientat These changes transform RFC-4 from a narrowly-focused anatomical orientation specification into a general, extensible orientation framework while maintaining strong support for the anatomical use case. The comprehensive implementation examples and working package provide concrete guidance for adoption, and the removal of default values promotes explicit, unambiguous metadata specification. -The changes directly address all reviewer feedback while significantly improving the technical quality and future applicability of the specification. \ No newline at end of file +The changes directly address all reviewer feedback while significantly improving the technical quality and future applicability of the specification. diff --git a/rfc/4/reviews/2/index.md b/rfc/4/reviews/2/index.md index a145c167f..d1f937a6b 100644 --- a/rfc/4/reviews/2/index.md +++ b/rfc/4/reviews/2/index.md @@ -1,8 +1,20 @@ +--- +authors: + - name: Juan Nunez-Iglesias + email: jni@fastmail.com + github: jni + affiliation: Monash University +date: 2025-08-05 +recommendation: minor_changes +--- + # RFC-4: Review 2 ## Review authors -Juan Nunez-Iglesias +```{document-authors} + +``` ## Conflicts of interest @@ -57,9 +69,10 @@ The namespacing issue can be resolved in two ways: (The [JSON LD](https://www.w3.org/TR/json-ld/#typed-values) equivalent would use `"@type"` and `"@value"`.) -2. Use a *recommended* rather than a closed vocabulary. One could even "soft" - close it by saying, *if* the orientation maps directly to one of the - proposed terms, then orientation *must* be one of the controlled terms. This + +2. Use a _recommended_ rather than a closed vocabulary. One could even "soft" + close it by saying, _if_ the orientation maps directly to one of the + proposed terms, then orientation _must_ be one of the controlled terms. This would allow a controlled ecosystem with a mechanism for expansion of the vocabulary. @@ -70,13 +83,13 @@ preferred. I believe it is a mistake to allow a default interpretation of the orientation. Since NGFF is used for data other than anatomical data, there will be many -images that will not have anatomical orientation tags *and should not* be +images that will not have anatomical orientation tags _and should not_ be interpreted as having any default orientation. Additionally, having a default orientation would encourage data producers to produce data without orientation metadata, since everything would silently "Just Work", while being implicit. Explicit is better than implicit, so I think -in this case, there should be *no* default orientation. In the absence of +in this case, there should be _no_ default orientation. In the absence of orientation metadata, clients MAY assume this default orientation, but SHOULD warn users that orientation metadata is expected but missing. @@ -105,4 +118,3 @@ N/A users. - disallow a default - describe interaction with rfc-5 - diff --git a/rfc/4/reviews/2b/index.md b/rfc/4/reviews/2b/index.md index ebb30bc27..377b6c194 100644 --- a/rfc/4/reviews/2b/index.md +++ b/rfc/4/reviews/2b/index.md @@ -1,8 +1,20 @@ +--- +authors: + - name: Juan Nunez-Iglesias + email: jni@fastmail.com + github: jni + affiliation: Monash University +date: 2025-12-11 +recommendation: accept +--- + # RFC-4: Review 2b ## Review authors -Juan Nunez-Iglesias +```{document-authors} + +``` ## Conflicts of interest diff --git a/rfc/4/reviews/3/index.md b/rfc/4/reviews/3/index.md index 28fdfedef..c97a5e664 100644 --- a/rfc/4/reviews/3/index.md +++ b/rfc/4/reviews/3/index.md @@ -1,12 +1,26 @@ +--- +authors: + - name: Dave Horsfall + github: davehorsfall + affiliation: Haniffa Lab + date: "2026-02-27" +recommendation: minor_changes +date: 2026-02-27 +--- + # RFC-4: Review 3 (rfcs:rfc4:review3)= -* [https://github.com/ome/ngff/pull/253](https://github.com/ome/ngff/pull/253) -* [https://ngff.openmicroscopy.org/rfc/4/](https://ngff.openmicroscopy.org/rfc/4/) -* [https://ngff.openmicroscopy.org/rfc/1/templates/review\_template.html](https://ngff.openmicroscopy.org/rfc/1/templates/review_template.html) +- [https://github.com/ome/ngff/pull/253](https://github.com/ome/ngff/pull/253) +- [https://ngff.openmicroscopy.org/rfc/4/](https://ngff.openmicroscopy.org/rfc/4/) +- [https://ngff.openmicroscopy.org/rfc/1/templates/review_template.html](https://ngff.openmicroscopy.org/rfc/1/templates/review_template.html) + +## Review Authors + +```{document-authors} -**Review Authors**: Dave Horsfall +``` **Conflicts of Interest**: None declared @@ -14,7 +28,7 @@ This review was primarily generated through discussions during a Hannifa Lab mee ## Summary -The RFC proposes an optional ***orientation*** field for the OME-NGFF specification to explicitly define axis direction using a controlled vocabulary. We support this addition. In fields like spatial transcriptomics and high-resolution histology, biological symmetry often makes it impossible to determine orientation after acquisition. +The RFC proposes an optional **_orientation_** field for the OME-NGFF specification to explicitly define axis direction using a controlled vocabulary. We support this addition. In fields like spatial transcriptomics and high-resolution histology, biological symmetry often makes it impossible to determine orientation after acquisition. ## Significant Comments and Questions @@ -22,26 +36,26 @@ The RFC proposes an optional ***orientation*** field for the OME-NGFF specificat The current proposal seems primarily geared toward imaging where the subject is a whole patient. In spatial transcriptomics and pathology, our subject is frequently a tissue biopsy, or histology slide. -* **The Gap:** The RFC states this metadata "MUST only be used... where the subject is roughly aligned to the imaging axes." In our use cases, we may not know how the biopsy was aligned to the patient, but we do know the internal orientation of the tissue itself. -* **Recommendation:** Clarify that "subject" can refer to local tissue structures. For a skin biopsy, the z-axis is "Superficial-to-Deep" regardless of the sample's original global position on the donor. Supporting local orientation makes this RFC universally applicable to the tissue-profiling community without requiring full "Patient-to-Atlas" registration. +- **The Gap:** The RFC states this metadata "MUST only be used... where the subject is roughly aligned to the imaging axes." In our use cases, we may not know how the biopsy was aligned to the patient, but we do know the internal orientation of the tissue itself. +- **Recommendation:** Clarify that "subject" can refer to local tissue structures. For a skin biopsy, the z-axis is "Superficial-to-Deep" regardless of the sample's original global position on the donor. Supporting local orientation makes this RFC universally applicable to the tissue-profiling community without requiring full "Patient-to-Atlas" registration. ### **Controlled Vocabulary Expansion** The current vocabulary has a focus on biped/quadruped canonical directions. To support clinical and other research contexts (e.g., dermatology, cardiology, and oncology), we recommend adding terms that describe layered and polarized tissues to controlled vocabulary: -* ***superficial-to-deep*** / ***deep-to-superficial***: for layered tissues like skin, gut, or cortex. -* ***apical-to-basal*** / ***basal-to-apical***: for epithelial layers and polarized cell structures. -* ***apex-to-base*** / ***base-to-apex***: for specific organs like the heart or lungs. +- **_superficial-to-deep_** / **_deep-to-superficial_**: for layered tissues like skin, gut, or cortex. +- **_apical-to-basal_** / **_basal-to-apical_**: for epithelial layers and polarized cell structures. +- **_apex-to-base_** / **_base-to-apex_**: for specific organs like the heart or lungs. ### **Integration with RFC-5: A semantic bridge to Transformation?** We see RFC-4 is a critical prerequisite for the successful implementation of RFC-5 (Transformations). While RFC-5 provides the mathematical framework for coordinate transforms, RFC-4 provides the necessary biological context. -* **Semantic Labeling:** RFC-5 allows us to define a transformation to a Common Coordinate Framework. We envisage that through explicit labels provided by RFC-4, a registration tool might programmatically determine if it needs to apply a flip or rotation to align with an atlas, etc. -* This might be outside the scope of this RFC, but establishing the relationship between RFC-4 and RFC-5 is important and we would be happy to offer input and collaborate on this in the future. +- **Semantic Labeling:** RFC-5 allows us to define a transformation to a Common Coordinate Framework. We envisage that through explicit labels provided by RFC-4, a registration tool might programmatically determine if it needs to apply a flip or rotation to align with an atlas, etc. +- This might be outside the scope of this RFC, but establishing the relationship between RFC-4 and RFC-5 is important and we would be happy to offer input and collaborate on this in the future. ### **Recommendation** -* Accept, with minor changes +- Accept, with minor changes Explicitly support Subject-Local orientation and expand the vocabulary to include layered-tissue terms. diff --git a/rfc/4/reviews/3b/index.md b/rfc/4/reviews/3b/index.md index 042d31830..e967af67a 100644 --- a/rfc/4/reviews/3b/index.md +++ b/rfc/4/reviews/3b/index.md @@ -1,8 +1,21 @@ +--- +authors: + - name: Dave Horsfall + github: davehorsfall + affiliation: Haniffa Lab + date: "2026-09-09" +recommendation: accept +date: 2026-09-09 +--- + # RFC-4: Review 3b +(rfcs:rfc4:review3b)= + ## Review authors -Dave Horsfall +```{document-authors} +``` ## Conflicts of interest diff --git a/rfc/5/comments/1/index.md b/rfc/5/comments/1/index.md index bb0e5e77d..13eb6a138 100644 --- a/rfc/5/comments/1/index.md +++ b/rfc/5/comments/1/index.md @@ -1,8 +1,16 @@ +--- +authors: + - name: Ilan Gold + github: ilan-gold +date: 2025-02-20 +--- + # RFC-5: Comment 1 -## Comment author +## Comment authors -Ilan Gold +```{document-authors} +``` ## Conflicts of interest (optional) diff --git a/rfc/5/comments/2/index.md b/rfc/5/comments/2/index.md index 32e7b660c..f3093e5c8 100644 --- a/rfc/5/comments/2/index.md +++ b/rfc/5/comments/2/index.md @@ -1,8 +1,16 @@ +--- +authors: + - name: Jeremy Maitin-Shepard + github: jbms +date: 2025-02-20 +--- + # RFC-5: Comment 2 -## Comment author +## Comment authors -Jeremy Maitin-Shepard +```{document-authors} +``` ## Minor comments and questions diff --git a/rfc/5/comments/3/index.md b/rfc/5/comments/3/index.md index 949ab35f2..1d2e23b37 100644 --- a/rfc/5/comments/3/index.md +++ b/rfc/5/comments/3/index.md @@ -1,8 +1,17 @@ +--- +authors: + - name: David Stansby + affiliation: University College London + github: dstansby +date: 2025-10-10 +--- + # RFC-5: Comment 3 ## Comment authors -David Stansby +```{document-authors} +``` ## Summary diff --git a/rfc/5/comments/4/index.md b/rfc/5/comments/4/index.md index 0fc99df59..fda4afa50 100644 --- a/rfc/5/comments/4/index.md +++ b/rfc/5/comments/4/index.md @@ -1,10 +1,19 @@ +--- +authors: + - name: Benedikt Best + github: btbest + orcid: 0000-0001-6965-1117 +date: 2026-02-26 +--- + # RFC-5: Comment 4 (rfcs:rfc5:comment4)= ## Comment authors -Benedikt Best (https://orcid.org/0000-0001-6965-1117) +```{document-authors} +``` ## Summary diff --git a/rfc/5/index.md b/rfc/5/index.md index d6381a704..c4cf7af94 100644 --- a/rfc/5/index.md +++ b/rfc/5/index.md @@ -1,3 +1,54 @@ +--- +authors: + - name: John Bogovic + github: bogovicj + affiliation: HHMI Janelia + role: Corresponding Author; Implemented + date: "2024-07-30" + - name: Davis Bennett + github: d-v-b + role: Implemented validation + date: "2024-07-30" + - name: Luca Marconato + github: LucaMarconato + affiliation: EMBL + role: Implemented + date: "2024-07-30" + - name: Matt McCormick + github: thewtex + affiliation: ITK + role: Implemented + date: "2024-07-30" + - name: Stephan Saalfeld + github: axtimwalde + affiliation: HHMI Janelia + role: Implemented (with JB) + date: "2024-07-30" + - name: Johannes Soltwedel + github: jo-mueller + affiliation: German BioImaging e.V. + role: Corresponding Author; Implemented + date: "2025-10-07" +endorsers: + - name: Will Moore + github: will-moore + affiliation: University of Dundee + role: Implemented + date: "2025-10-23" + - name: David Stansby + github: dstansby + affiliation: University College London + role: Implemented + date: "2025-10-23" + - name: Norman Rzepka + github: normanrz + affiliation: Scalable Minds + date: "2024-08-22" +manual_status: S3 +description: Coordinate systems and transformations +date: 2024-07-30 +--- + # RFC-5: Coordinate Systems and Transformations (rfcs:rfc5:version3)= @@ -14,24 +65,8 @@ Add named coordinate systems and expand and clarify coordinate transformations. ## Status -This RFC is currently in RFC state `S3` (Update implementations). - -| **Role** | Name | GitHub Handle | Institution | Date | Status | -|----------|------|---------------|-------------|------|--------| -| **Author** | John Bogovic | [bogovicj](https://github.com/bogovicj) | HHMI Janelia | 2024-07-30 | (Corresponding Author) Implemented | -| **Author** | Davis Bennett | [d-v-b](https://github.com/d-v-b) | | 2024-07-30 | Implemented validation | -| **Author** | Luca Marconato | [LucaMarconato](https://github.com/LucaMarconato) | EMBL | 2024-07-30 | Implemented | -| **Author** | Matt McCormick | [thewtex](https://github.com/thewtex) | ITK | 2024-07-30 | Implemented | -| **Author** | Stephan Saalfeld | [axtimwalde](https://github.com/axtimwalde) | HHMI Janelia | 2024-07-30 | Implemented (with JB) | -| **Author** | Johannes Soltwedel | [jo-mueller](https://github.com/jo-mueller) | German Bioimaging e.V. | 2025-10-07 | (Corresponding Author) Implemented | -| **Endorser** | Will Moore | [will-moore](https://github.com/will-moore) | University of Dundee | 2025-10-23 | Implemented | -| **Endorser** | David Stansby | [dstansby](https://github.com/dstansby) | University College London | 2025-10-23 | Implemented | -| **Endorser** | Norman Rzepka | [normanrz](https://github.com/normanrz) | Scalable Minds | 2024-08-22 | | -| **Reviewer** | Dan Toloudis, David Feng, Forrest Collman, Nathalie Gaudreault, Gideon Dunster | [toloudis](https://github.com/toloudis), [dyf](https://github.com/dyf), [fcollman](https://github.com/fcollman) | Allen Institutes | 2024-11-28 | [Review](rfcs:rfc5:review1) | -| **Reviewer** | Will Moore, Jean-Marie Burel, Jason Swedlow | [will-moore](https://github.com/will-moore), [jburel](https://github.com/jburel), [jrswedlow](https://github.com/jrswedlow) | University of Dundee | 2025-01-22 | [Review](rfcs:rfc5:review2)| -| **Commenter** | Ilan Gold | [ilan-gold](https://github.com/ilan-gold) | | 2025-02-20 | [Comment](./comments/1/index) | -| **Commenter** | Jeremy Maitin-Shephard | [jbms](https://github.com/jbms) | | 2025-02-20 | [Comment](./comments/2/index) | -| **Commenter** | David Stansby | [dstansby](https://github.com/dstansby) | | 2025-10-10 | [Comment](./comments/3/index) | +```{rfc-status} +``` ## Overview @@ -49,7 +84,7 @@ for neuro and bio-imaging and broader scientific imaging practices to enable: transformations are applied consistently across different platforms and applications. This FAIR capability is a cornerstone of scientific research, and having standardized formats and tools facilitates verification of results by independent researchers. -2. Integration with Analysis Workflows: +2. Integration with Analysis Workflows: Having spatial transformations as a first-class citizen within file formats allows for seamless integration with various image analysis workflows. Registration transformations can be used in subsequent image analysis steps @@ -125,7 +160,7 @@ whereas microscopes scan the object of interest in a rasterized manner. Similarly, timelapse images or highly multiplexed data can be considered as a series of nd-tiled acquisition and thus allows on-the-fly OME-Zarr writing in such applications. - Multi-view acquisition: Some applications (large volumetric 3D microscopy) require the acquisition of multiple images of the same object from different angles to account for optical limitations of the microscope or the sample. Rotations, translations and affine transformations enable expression of these spatial relationships and low-cost fused view of large volumetric data using the existing OME-Zarr viewer ecosystem. - + ### Acquisition artefacts In some cases, the acquired imaging data requires the provision of a particular transformation in order to be viewed correctly. @@ -134,15 +169,15 @@ In some cases, the acquired imaging data requires the provision of a particular - Oblique plane microscopy deskewing: This class of high-speed lightsheet microscopes acquires volumetric data, where the individual image planes are acquired under a skewed angle. Consequently, a deskewing step (e.g., transformation with an affine shear matrix) is necessary to view the data in its correct spatial arrangement. - Drift correction: During timelapse images, live samples may move in space. - This can be corrected with a drift correction, + This can be corrected with a drift correction, which is represented by a per-timepoint linear transformation. Similarly, registration and alignment of timelapse images requires per-timepoint transformations. ### Annotation and analysis -Image analysis tasks involving coordinates and transformations are often not explicit about +Image analysis tasks involving coordinates and transformations are often not explicit about what coordinate system they correspond to. Some examples -* Is a coordinate that represents an annotation on an image in pixel or physical units? +* Is a coordinate that represents an annotation on an image in pixel or physical units? * Is a transformations inputs / outputs in pixel or physical units?; * Is a transformation obtained by image registration the "forward" or "inverse" transformation? @@ -195,7 +230,7 @@ Coordinate Systems metadata example The axes of a coordinate system (see below) give information about the types, units, and other properties of the coordinate system's dimensions. Axis names may contain semantically meaningful information, but can be arbitrary. -As a result, two coordinate systems that have identical axes in the same order +As a result, two coordinate systems that have identical axes in the same order may not be "the same" in the sense that measurements at the same point refer to different physical entities and therefore should not be analyzed jointly. Tasks that require images, annotations, regions of interest, etc., @@ -290,7 +325,7 @@ Then `dim_0` has length 4, `dim_1` has length 3, and `dim_2` has length 5. The axes and their order align with the shape of the corresponding Zarr array, and whose data depends on the byte order used to store chunks. As described in the [Zarr array metadata](https://Zarr.readthedocs.io/en/stable/spec/v3.html#arrays), -the last dimension of an array in "C" order are stored contiguously on disk or in-memory when directly loaded. +the last dimension of an array in "C" order are stored contiguously on disk or in-memory when directly loaded. The name and axes names MAY be customized by including a `arrayCoordinateSystem` field in the user-defined attributes of the array whose value is a coordinate system object. @@ -349,7 +384,7 @@ The following transformations are supported: | [`byDimension`](#bydimension) | `"transformations":List[Transformation]`,
`"input_axes": List[str]`,
`"output_axes": List[str]` | A high dimensional transformation using lower dimensional transformations on subsets of dimensions. | Implementations SHOULD prefer to store transformations as a sequence of less expressive transformations where possible -(e.g., sequence[translation, rotation], instead of affine transformation with translation/rotation). +(e.g., sequence[translation, rotation], instead of affine transformation with translation/rotation). ````{admonition} Example (example:coordinate_transformation_scale)= @@ -360,7 +395,7 @@ Implementations SHOULD prefer to store transformations as a sequence of less exp { "name": "in", "axes": [{"name": "j"}, {"name": "i"}] }, { "name": "out", "axes": [{"name": "y"}, {"name": "x"}] } ], - "coordinateTransformations": [ + "coordinateTransformations": [ { "type": "scale", "scale": [2, 3.12], @@ -390,7 +425,7 @@ Conforming readers: - SHOULD be able to apply transformations to images; Coordinate transformations can be stored in multiple places to reflect different use cases. - + - **Inside `multiscales > datasets`**: `coordinateTransformations` herein MUST be restricted to a single `scale`, `identity` or `sequence` of a scale followed by a translation transformation. For more information, see [multiscales section below](#multiscales-metadata). @@ -398,7 +433,7 @@ Coordinate transformations can be stored in multiple places to reflect different The `coordinateTransformations` field MUST contain an array of valid [transformations](#transformation-types). The input to every one of these transformations MUST be the intrinsic coordinate system. The output can be another coordinate system defined under `multiscales > coordinateSystems`. - + - **Inside `scene > coordinateTransformations`**: Transformations between two or more images MUST be stored in the attributes of a [`scene` dictionary](rfcs:rfc5:version3:scene) in a [scene Zarr group](rfcs:rfc5:version3:storage-format-scene). In this case, the `input` and `output` values are dictionaries @@ -429,9 +464,9 @@ where a coordinate is the location/value of that point along its corresponding a The indexes of axis dimensions correspond to indexes into transformation parameter arrays (see examples). **Image rendering**: When rendering transformed images and interpolating, -implementations may need the "inverse" transformation - from the fixed -image's to the source image's coordinate system. This transformation may -not explicitly exist, but might be the require computing the inverse +implementations may need the "inverse" transformation - from the fixed +image's to the source image's coordinate system. This transformation may +not explicitly exist, but might be the require computing the inverse (in closed form) of an explicitly specified forward transformation. Inverse transformations used for image rendering may be specified @@ -444,8 +479,8 @@ that the requested operation is unsupported. ````{admonition} Example -Implementations SHOULD be able to compute and apply the inverse of some coordinate -transformations when they are computable in closed-form (as the +Implementations SHOULD be able to compute and apply the inverse of some coordinate +transformations when they are computable in closed-form (as the [Transformation types](#transformation-types) section below indicates). Implementations should be able to render the moving image into the fixed image by computing the inverse of this transformation. @@ -458,10 +493,10 @@ image by computing the inverse of this transformation. } ``` -Software libraries that perform image registration often return the transformation -from fixed image coordinates to moving image coordinates, because this "inverse" +Software libraries that perform image registration often return the transformation +from fixed image coordinates to moving image coordinates, because this "inverse" transformation is most often required when rendering the transformed moving image. -Implementations should be able to render the moving image into the fixed image by +Implementations should be able to render the moving image into the fixed image by applying this transformation directly. ```json @@ -472,7 +507,7 @@ applying this transformation directly. } ``` -Implementations are not expected to be able to to render the moving image +Implementations are not expected to be able to to render the moving image into the fixed image given this transformation. They may attempt to do so by estimating the transformations' inverse if they choose to. @@ -498,7 +533,7 @@ When stored as a 2D json array, the inner array contains rows (e.g. `[[1,2,3], [ #### Transformation types (transformation-types)= -Input and output dimensionality may be determined by the coordinate system referred to by the `input` and `output` fields, respectively. +Input and output dimensionality may be determined by the coordinate system referred to by the `input` and `output` fields, respectively. If the value of `input` is a path to an array, its shape gives the input dimension, otherwise it is given by the length of `axes` for the coordinate system with the name of the `input`. If the value of `output` is an array, its shape gives the output dimension, @@ -635,7 +670,7 @@ of the `i`th output axis. See the example below. `coordinates` and `displacements` transformations are not invertible in general, but implementations MAY approximate their inverses. -Metadata for these coordinate transforms have the following fields: +Metadata for these coordinate transforms have the following fields: **path** : The location of the coordinate array in this (or another) container. @@ -919,7 +954,7 @@ that maps Zarr array coordinates for this resolution level to the "intrinsic" co The transformation is defined according to [transformations metadata](#transformation-types). The transformation MUST take as input points in the array coordinate system corresponding to the Zarr array at location `path`. -The value of "input" MUST equal the value of `path`, +The value of "input" MUST equal the value of `path`, implementations should always treat the value of `input` as if it were equal to the value of `path`. The value of the transformation’s `output` coordinate system MUST be the same for every dataset in a single multiscales. This coordinate system (the "intrinsic" coordinate system) will generally be a representation of the image in its native physical coordinate system. @@ -1109,7 +1144,7 @@ used by the libraries generally applies for 2D and 3D spatial transformations, b transformations of arbitrary dimension and axis type, where there is not a strong convention we are aware of. An early consideration was to use axis names to indicate correspondence across different coordinate systems (i.e. if two -coordinate systems both have the "x" axis, then it is "the same" axis. We abandoned this for several reasons. It was +coordinate systems both have the "x" axis, then it is "the same" axis. We abandoned this for several reasons. It was restrictive - it is useful to have many coordinate systems with an "x" axis without requiring that they be "identical." Under our early idea, every set of spatial axes would need unique names ("x1", "x2", ...), and this seemed burdensome. As well, this approach would have also made transformations less explicit and likely would have required more complicated implementations. @@ -1123,7 +1158,7 @@ Additional transformation types should be added in the future. Top candidates in * thin-plate spline * b-spline * velocity fields -* by-coordinate +* by-coordinate * new-dimension ## Performance diff --git a/rfc/5/responses/1/index.md b/rfc/5/responses/1/index.md index e8b4b16ac..f2da04d02 100644 --- a/rfc/5/responses/1/index.md +++ b/rfc/5/responses/1/index.md @@ -1,5 +1,19 @@ +--- +authors: + - name: John Bogovic + affiliation: HHMI Janelia + github: bogovicj + - name: Johannes Soltwedel + affiliation: German BioImaging e.V. + github: jo-mueller +date: 2025-10-07 +--- + # RFC-5: Response 1 (2025-10-07 version) +```{document-authors} +``` + The authors extend their most sincere thanks and appreciation to all the reviewers of this RFC. diff --git a/rfc/5/responses/2/index.md b/rfc/5/responses/2/index.md index 62839d6b0..1cddc0e9e 100644 --- a/rfc/5/responses/2/index.md +++ b/rfc/5/responses/2/index.md @@ -1,5 +1,16 @@ +--- +authors: + - name: Johannes Soltwedel + affiliation: German BioImaging e.V. + github: jo-mueller +date: 2025-11-18 +--- + # RFC-5: Response 2 (2025-11-18 version) +```{document-authors} +``` + We thank all reviewers and community members for their time and effort in reviewing and discussing our [updated proposal](rfcs:rfc5:version2). Please find below our point-by-point replies to reviews and a summary of discussion outcomes. The provided [example datasets on Zenodo](https://zenodo.org/records/17313420/latest) have been updated accordingly diff --git a/rfc/5/reviews/1/index.md b/rfc/5/reviews/1/index.md index bf785f719..b674ce9cf 100644 --- a/rfc/5/reviews/1/index.md +++ b/rfc/5/reviews/1/index.md @@ -1,13 +1,27 @@ +--- +authors: + - name: Daniel Toloudis + affiliation: Allen Institute for Cell Science + github: toloudis + - name: David Feng + affiliation: Allen Institute for Neural Dynamics + github: dyf + - name: Forrest Collman + affiliation: Allen Institute for Brain Science + github: fcollman + - name: Nathalie Gaudreault + affiliation: Allen Institute for Cell Science +date: 2024-11-28 +recommendation: major_changes +--- + # RFC-5: Review 1 (rfcs:rfc5:review1)= ## Review authors -This review was written by: Daniel Toloudis1, David Feng2, Forrest Collman3, Nathalie Gaudreault1 - -1 Allen Institute for Cell Science -2 Allen Institute for Neural Dynamics -3 Allen Institute for Brain Science +```{document-authors} +``` ## Summary diff --git a/rfc/5/reviews/1b/index.md b/rfc/5/reviews/1b/index.md index 0fa693149..201643cb1 100644 --- a/rfc/5/reviews/1b/index.md +++ b/rfc/5/reviews/1b/index.md @@ -1,13 +1,27 @@ +--- +authors: + - name: Daniel Toloudis + affiliation: Allen Institute for Cell Science + github: toloudis + - name: David Feng + affiliation: Allen Institute for Neural Dynamics + github: dyf + - name: Forrest Collman + affiliation: Allen Institute for Brain Science + github: fcollman + - name: Nathalie Gaudreault + affiliation: Allen Institute for Cell Science +date: 2025-11-25 +recommendation: accept +--- + # RFC-5: Review 1b (rfcs:rfc5:review1b)= ## Review authors -This review was written by: Daniel Toloudis1, David Feng2, Forrest Collman3, Nathalie Gaudreault1 - -1 Allen Institute for Cell Science -2 Allen Institute for Neural Dynamics -3 Allen Institute for Brain Science +```{document-authors} +``` ## Recommendation diff --git a/rfc/5/reviews/2/index.md b/rfc/5/reviews/2/index.md index 896885459..57a8e308a 100644 --- a/rfc/5/reviews/2/index.md +++ b/rfc/5/reviews/2/index.md @@ -1,10 +1,25 @@ +--- +authors: + - name: William Moore + affiliation: University of Dundee + github: will-moore + - name: Jean-Marie Burel + affiliation: University of Dundee + github: jburel + - name: Jason Swedlow + affiliation: University of Dundee + github: jrswedlow +date: 2025-01-22 +recommendation: minor_changes +--- + # RFC-5: Review 2 (rfcs:rfc5:review2)= ## Review authors -This review was written by: William Moore1, Jean-Marie Burel1, Jason Swedlow1 -1 University of Dundee +```{document-authors} +``` ## Summary diff --git a/rfc/5/reviews/2b/index.md b/rfc/5/reviews/2b/index.md index ef86de5a6..4b514e85a 100644 --- a/rfc/5/reviews/2b/index.md +++ b/rfc/5/reviews/2b/index.md @@ -1,10 +1,22 @@ +--- +authors: + - name: William Moore + affiliation: University of Dundee + github: will-moore + - name: Jean-Marie Burel + affiliation: University of Dundee + github: jburel +date: 2025-11-19 +recommendation: accept +--- + # RFC-5: Review 2b (rfcs:rfc5:review2b)= ## Review authors -This review was written by: William Moore1 and Jean-Marie Burel1 -1 University of Dundee +```{document-authors} +``` ## Summary diff --git a/rfc/6/comments/1/index.md b/rfc/6/comments/1/index.md index 71fd111d7..916ee7105 100644 --- a/rfc/6/comments/1/index.md +++ b/rfc/6/comments/1/index.md @@ -1,10 +1,20 @@ +--- +authors: + - name: Chris Barnes + github: clbarnes + - name: Davis Bennett + github: d-v-b +date: 2025-11-05 +--- + # RFC-6: Comment 1 (rfcs:rfc6:comment1)= ## Comment authors -This comment was written by: Chris Barnes, Davis Bennett. +```{document-authors} +``` ## Summary diff --git a/rfc/6/index.md b/rfc/6/index.md index 64509792f..2265914a5 100644 --- a/rfc/6/index.md +++ b/rfc/6/index.md @@ -1,3 +1,44 @@ +--- +authors: + - name: Norman Rzepka + github: normanrz + affiliation: scalable minds + role: Author + date: "2024-12-03" +endorsers: + - name: David Stansby + github: dstansby + affiliation: University College London + date: "2024-12-03" + - name: Davis Bennett + github: d-v-b + date: "2024-12-12" + - name: Will Moore + github: will-moore + affiliation: OME, University of Dundee + date: "2024-12-12" + - name: Lachlan Deakin + github: LDeakin + affiliation: Australian National University + date: "2024-12-17" + - name: Joel Lüthi + github: jluethi + affiliation: BioVisionCenter, University of Zurich + date: "2024-12-18" + - name: Eric Perlman + github: perlman + date: "2024-12-18" + - name: Johannes Soltwedel + github: jo-mueller + affiliation: German BioImaging e.V. + date: "2025-10-22" +reference_pr: https://github.com/ome/ngff/pull/285 +manual_status: R9 +status_note: superseded by RFC-8 +description: Flattening the multiscales array +date: 2024-12-03 +--- + # RFC-6: Flattening the multiscales array ```{toctree} @@ -10,73 +51,7 @@ Turn the `multiscales` array into a single `multiscale` object. ## Status -This RFC has been withdrawn (R9) since it is superseded by RFC-8. - -```{list-table} Record -:widths: 8, 20, 20, 20, 15, 10 -:header-rows: 1 -:stub-columns: 1 - -* - Role - - Name - - GitHub Handle - - Institution - - Date - - Status -* - Author - - Norman Rzepka - - [normanrz](https://github.com/normanrz) - - scalable minds - - 2024-12-03 - - -* - Endorser - - David Stansby - - [dstansby](https://github.com/dstansby) - - University College London - - 2024-12-03 - - -* - Endorser - - Davis Bennett - - [d-v-b](https://github.com/d-v-b) - - - - 2024-12-12 - - -* - Endorser - - Will Moore - - [will-moore](https://github.com/will-moore) - - OME, University of Dundee - - 2024-12-12 - - -* - Endorser - - Lachlan Deakin - - [LDeakin](https://github.com/LDeakin) - - Australian National University - - 2024-12-17 - - -* - Endorser - - Joel Lüthi - - [jluethi](https://github.com/jluethi) - - BioVisionCenter, University of Zurich - - 2024-12-18 - - -* - Endorser - - Eric Perlman - - [perlman](https://github.com/perlman) - - - - 2024-12-18 - - -* - Endorser - - Johannes Soltwedel - - [jo-mueller](https://github.com/jo-mueller) - - German BioImaging e.V. - - 2025-10-22 - - -* - Commenter - - Chris Barnes, Davis Bennett - - [clbarnes](https://github.com/clbarnes), [d-v-b](https://github.com/d-v-b) - - - - 2025-11-05 - - [Comment](./comments/1/index) +```{rfc-status} ``` ## Overview diff --git a/rfc/7/index.md b/rfc/7/index.md index cd6d22dea..276b44a9a 100644 --- a/rfc/7/index.md +++ b/rfc/7/index.md @@ -1,3 +1,9 @@ +--- +manual_status: D1 +status_note: reserved, under preparation +description: Channel provenance +--- + # RFC-7: Channel provenance ```{toctree} @@ -6,4 +12,9 @@ comments/index ``` -RFC-7 has been reserved a number and a topic (channel provenance), but is yet under preparation. +RFC-7 has been reserved a number and a topic (channel provenance), but is yet under preparation. + +## Status + +```{rfc-status} +``` diff --git a/rfc/8/index.md b/rfc/8/index.md index 262a7b1df..e36d4d81c 100644 --- a/rfc/8/index.md +++ b/rfc/8/index.md @@ -1,3 +1,45 @@ +--- +authors: + - name: Norman Rzepka + github: normanrz + affiliation: scalable minds + role: Co-author + date: "2024-11-20" + - name: Eric Perlman + github: perlman + affiliation: Yikes LLC + role: Co-author + date: "2024-11-20" + - name: Joel Lüthi + github: jluethi + affiliation: BioVisionCenter Zurich + role: Co-author + date: "2024-11-20" + - name: Lorenzo Cerrone + github: lorenzocerrone + affiliation: BioVisionCenter Zurich + role: Co-author + date: "2024-11-20" + - name: Christian Tischer + github: tischi + affiliation: EMBL + role: Co-author + date: "2025-02-01" + - name: Matthew Hartley + github: matthewh-ebi + affiliation: EMBL-EBI + role: Co-author + date: "2025-05-05" + - name: Johannes Soltwedel + github: jo-mueller + affiliation: German BioImaging e.V. + role: Co-author + date: "2025-10-28" +manual_status: R1 +description: Collections +date: 2024-11-20 +--- + # RFC-8: Collections and Extensibility ```{toctree} @@ -11,26 +53,8 @@ Extending OME-Zarr with new metadata types, references, and collections ## Status -This proposal is early. Status: D1 - -| Name | GitHub Handle | Institution | Date | Status | -| --------- | ------------- | ----------- | ---------- | ------------------------------------- | -| Norman Rzepka | [normanrz](https://github.com/normanrz) | scalable minds | 2024-11-20 | Author | -| Eric Perlman | [perlman](https://github.com/perlman) | Yikes LLC | 2024-11-20 | Author | -| Joel Lüthi | [jluethi](https://github.com/jluethi) | BioVisionCenter Zurich | 2024-11-20 | Author | -| Lorenzo Cerrone | [lorenzocerrone](https://github.com/lorenzocerrone) | BioVisionCenter Zurich | 2024-11-20 | Author | -| Johannes Soltwedel | [jo-mueller](https://github.com/jo-mueller) | German BioImaging e.V. | 2025-10-28 | Author | -| Christian Tischer | [tischi](https://github.com/tischi) | EMBL | 2025-02-01 | Author | -| Matthew Hartley | [matthewh-ebi](https://github.com/matthewh-ebi) | EMBL-EBI | 2025-05-05 | Author | - - +```{rfc-status} +``` ## Overview @@ -226,7 +250,7 @@ The `path` string can be one of the following types: Examples: - `file:///home/user/data/image.ome.zarr` - `file://C:/Users/user/data/image.ome.zarr` -- **HTTP(S) URLs.** +- **HTTP(S) URLs.** To reference nodes that are stored remotely, URLs with the `http` or `https` scheme may be used. URLs follow the notation defined in [IETF RFC1738](https://datatracker.ietf.org/doc/html/rfc1738). Examples: @@ -410,7 +434,7 @@ Either `"nodes"` or `"path"` MUST be present, but not both. "name": "gallery1", "path": { "type": "json", - "path": "../gallery.json" + "path": "../gallery.json" } }, ...] } @@ -584,7 +608,7 @@ In a change from the previous specification, coordinate systems are referenced u "type": "zarr", "path": "./tile_0.zarr" } - }, + }, { "type": "multiscale", "id": "tile_1", @@ -599,7 +623,7 @@ In a change from the previous specification, coordinate systems are referenced u } ``` -The `type` field of a coordinate transformation defines its mathematical operation. RFC-5 defines several unprefixed transformation types including `identity`, `scale`, `translation`, and others. +The `type` field of a coordinate transformation defines its mathematical operation. RFC-5 defines several unprefixed transformation types including `identity`, `scale`, `translation`, and others. The `type` field of a `CoordinateTransformation` is an extension point. For detail on how to extend the `type` field with new values, see [Extensions](#extensions). @@ -670,7 +694,7 @@ under Damien's proposal #### Label maps and other derived images Previous versions of the OME-Zarr specification defined a mechanism for associating label images with a single multiscale image. -This was achieved by using a `labels` Zarr group that had to be a direct child of the multiscale Zarr group with some specific metadata. +This was achieved by using a `labels` Zarr group that had to be a direct child of the multiscale Zarr group with some specific metadata. This proposal replaces this mechanism. To denote a multiscale image as a label map, the `labels` attribute MUST be present. @@ -693,7 +717,7 @@ The `labelAttributes` field is an array of objects with the following fields: | Field | Type | Required? | Notes | | - | - | - | - | | `"labelValue"` | number | yes | Value MUST be the label value. | -| `"color"` | array of number | no | Value MUST be a color in array format. | +| `"color"` | array of number | no | Value MUST be a color in array format. | If present, the `color` field MUST have an array with four integers between 0 and 255, inclusive. These integers represent the uint8 values of red, green, blue and alpha. @@ -789,7 +813,7 @@ A `collection` node representing a well MUST have a `well` attribute with the fo The `acquisition` attribute MUST be a [`Reference`](#reference-interface) to one of the acquisitions. It MAY be set on individual `multiscale` nodes within a well or on a `collection` sub-node grouping all images from a single acquisition. -We suggest two possible layouts for HCS data, which are not mutually exclusive and can be used in combination: a "wide" layout where all images are direct children of the well collection and a "tall" layout where images are grouped in sub-collections by acquisition. +We suggest two possible layouts for HCS data, which are not mutually exclusive and can be used in combination: a "wide" layout where all images are direct children of the well collection and a "tall" layout where images are grouped in sub-collections by acquisition. ##### Wide example (acquisitions flat in the well) @@ -885,7 +909,7 @@ Derived images such as label maps are siblings of their source image and can sti In this layout, each acquisition is wrapped in a sub-collection inside the well. The `acquisition` attribute is set on the sub-collection rather than on individual nodes. -This serves as an example that wells can consist of collections, not just multiscales. +This serves as an example that wells can consist of collections, not just multiscales. ```jsonc { @@ -1008,7 +1032,7 @@ A series of images can now be represented as a collection of multiscale images. ## Extensions -This section describes how existing classes and class attributes can be extended +This section describes how existing classes and class attributes can be extended in a controlled manner, enabling custom functionality while maintaining interoperability. Extensions to the specification can be made at defined extension points, and @@ -1094,14 +1118,14 @@ Let's assume the example of a pixel classification task. This task would take an ``` ├─ input_image.zarr │ ├─ zarr.json # OME-Zarr multiscale -│ ├─ 0 -│ └─ ... +│ ├─ 0 +│ └─ ... └─ output_collection.zarr │ # includes collection metadata and link to "../input_image.zarr" - ├─ zarr.json + ├─ zarr.json └─ prediction.zarr ├─ zarr.json # OME-Zarr multiscale - ├─ 0 + ├─ 0 └─ ... ``` @@ -1123,7 +1147,7 @@ Examples of such applications are (among others) the following: lightsheet microscopes acquire multiple views of the same object from different angles. A set of coordinate transformations is used to map between the different views. - Multimodal medical imaging: Different imaging modalities (e.g., CT, MRI, PET, etc), - are often used either in conjunction or at different timepoints to observe the same object or anatomical structure. + are often used either in conjunction or at different timepoints to observe the same object or anatomical structure. Such applications require the storage of collections of images and their mutual relationships, the metadata for which has already been defined by RFC-5 (Coordinate Transformations in OME-NGFF). @@ -1197,7 +1221,7 @@ Implementations of this concept include: - [MoBIE grid views](https://mobie.github.io/tutorials/image_grids_and_tables.html) - [OME2024 NGFF challenge](https://ome.github.io/ome2024-ngff-challenge/) -For example, [this table](https://docs.google.com/spreadsheets/d/1t5xB0p0zd2-a6ynV-JAuLJqs-mg-pFFikhfmQGZwRpI/edit?usp=sharing) defines a MoBIE grid view of three OpenOrganelle vEM images along with label images of mitochondria segmentation. It can be opened in MoBIE via the "Open Simple Collection Table" menu entry: +For example, [this table](https://docs.google.com/spreadsheets/d/1t5xB0p0zd2-a6ynV-JAuLJqs-mg-pFFikhfmQGZwRpI/edit?usp=sharing) defines a MoBIE grid view of three OpenOrganelle vEM images along with label images of mitochondria segmentation. It can be opened in MoBIE via the "Open Simple Collection Table" menu entry: ![MoBIE grid view](./assets/mobie_grid_view.jpg) @@ -1426,7 +1450,7 @@ And the `zarr.json` at the location of the resolution level (`./s0/zarr.json`) c "type": "zarr", "path": "./raw", // a relative or absolute path }, - "attributes": { + "attributes": { "example-viewer:settings": { "isDisabled": true }, @@ -1440,7 +1464,7 @@ And the `zarr.json` at the location of the resolution level (`./s0/zarr.json`) c "type": "json", "path": "./nested_collection.json" } - }, ... + }, ... ], "attributes": { ... @@ -1501,7 +1525,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S @@ -1557,7 +1581,7 @@ It is also expected that programming libraries will support this new metadata fo Many RFCs have an "implementation" section which details how the implementation will work. This section should explain the rough specification changes. The goal is to give an idea to reviewers about the subsystems that require change -and the surface area of those changes. +and the surface area of those changes. This knowledge can result in recommendations for alternate approaches that perhaps are idiomatic to the project or result in less packages touched. Or, it @@ -1582,7 +1606,7 @@ For example, a collection can contain inlined metadata for multiscale images and This redundant metadata can go out of sync. It is the responsibility of implementations to ensure consistency where required. -For reading, implementations SHOULD parse the metadata as available to the implementation from the user-supplied entry point in the OME-Zarr hierarchy. +For reading, implementations SHOULD parse the metadata as available to the implementation from the user-supplied entry point in the OME-Zarr hierarchy. ### New Multiscale/Singlescale metadata @@ -1770,9 +1794,9 @@ Shortened version from https://fafb-ffn1.storage.googleapis.com/landing.html The MoBIE collection table allows users to specify a collection of images and segmentations (label mask images) and configure their rendering. -Each row in the table corresponds to one (single-channel) image or segmentation. +Each row in the table corresponds to one (single-channel) image or segmentation. -To open multi-channel images the image URI must be added several times and a `channel` column must be added to specify which channel to load. +To open multi-channel images the image URI must be added several times and a `channel` column must be added to specify which channel to load. One can specify an affine transformation for each image. @@ -2135,7 +2159,7 @@ It is strongly recommended to provide as many examples as possible of what both ## Additional considerations ### Security diff --git a/rfc/9/comments/1/index.md b/rfc/9/comments/1/index.md index a8807c58c..912affd5b 100644 --- a/rfc/9/comments/1/index.md +++ b/rfc/9/comments/1/index.md @@ -1,10 +1,20 @@ +--- +authors: + - name: Matt McCormick + affiliation: Fideus Labs LLC + github: thewtex +date: 2025-11-15 +--- + # RFC-9: Comment 1 (rfcs:rfc9:comment1)= ## Comment authors -This comment was written by: Matt McCormick, Fideus Labs LLC. +```{document-authors} + +``` ## Conflicts of interest (optional) @@ -23,6 +33,7 @@ We have implemented the specification, including reading, writing, and all the r We recommend including a concrete example of the expected file order for clarification. This would help implementers understand exactly how to order `zarr.json` files in breadth-first order. For instance, given a hierarchy like: + ``` / ├── zarr.json (root) @@ -37,6 +48,7 @@ For instance, given a hierarchy like: ``` The recommended ZIP entry order would be: + 1. `zarr.json` (root) 2. `image/zarr.json` 3. `labels/zarr.json` diff --git a/rfc/9/comments/2/index.md b/rfc/9/comments/2/index.md index 9ff9f1c0f..aa9004aae 100644 --- a/rfc/9/comments/2/index.md +++ b/rfc/9/comments/2/index.md @@ -1,10 +1,20 @@ +--- +authors: + - name: Joost de Folter + affiliation: BioImaging-NL + github: folterj +date: 2025-12-03 +--- + # RFC-9: Comment 2 (rfcs:rfc9:comment2)= ## Comment authors -This comment was written by: Joost de Folter, BioImaging-NL +```{document-authors} + +``` ## Conflicts of interest (optional) diff --git a/rfc/9/comments/3/index.md b/rfc/9/comments/3/index.md index d0f80c2cd..5f4c83519 100644 --- a/rfc/9/comments/3/index.md +++ b/rfc/9/comments/3/index.md @@ -1,10 +1,20 @@ +--- +authors: + - name: Chris Barnes + affiliation: German BioImaging + github: clbarnes +date: 2025-12-12 +--- + # RFC-9: Comment 3 (rfcs:rfc9:comment2)= ## Comment authors -This comment was written by: Chris Barnes, German BioImaging +```{document-authors} + +``` ## Conflicts of interest (optional) diff --git a/rfc/9/comments/4/index.md b/rfc/9/comments/4/index.md index e2bfe5088..79a55c8df 100644 --- a/rfc/9/comments/4/index.md +++ b/rfc/9/comments/4/index.md @@ -1,12 +1,21 @@ +--- +authors: + - name: Lenard Spiecker + affiliation: Miltenyi Biotec B.V. & Co. KG + - name: Matthias Grunwald + affiliation: Miltenyi Biotec B.V. & Co. KG +date: 2026-01-09 +--- + # RFC-9: Comment 4 (rfcs:rfc9:comment4)= ## Comment authors -This comment was written by: Lenard Spiecker1 and Matthias Grunwald1 +```{document-authors} -1 Miltenyi Biotec B.V. & Co. KG +``` ## Conflicts of interest @@ -22,7 +31,7 @@ We support standardizing single-file OME-Zarr via ZIP (.ozx). In our context at - **CRC/hash requirement:** ZIP requires CRC32 for file entries, which is useful for integrity verification, but it burdens implementations, especially for partial writes and reads. With sharding, recomputing CRCs for sub-ranges or appends is tricky; clarifying recommended strategies (e.g., validating at shard or chunk granularity and deferring CRC checks for in-flight writes) would help implementers. Implementers should also note that there is no support for CRC32(B) SIMD instructions on x86_64 (SSE4.2 only supports CRC32(C)). This point could be added under the drawback section in the RFC. -- **Ordering of zarr.json first:** While placing the root and all other `zarr.json` files at the beginning of the archive potentially aids discovery and streaming access, practical implementations may still read the ZIP comment together with the central directory first. The main reason is that the first `zarr.json` can become obsolete, rendering streaming access inefficient compared to seeking. We also observed that strict file ordering cannot be maintained when appending a new `zarr.json` (e.g., adding labels) to an existing .ozx file. Furthermore, we encounter cases where metadata is generated during acquisition; therefore, we lean toward writing data first and metadata second to avoid writing it twice. For the stated reasons, we will likely not produce .ozx files with `zarr.json` files ordered first. +- **Ordering of zarr.json first:** While placing the root and all other `zarr.json` files at the beginning of the archive potentially aids discovery and streaming access, practical implementations may still read the ZIP comment together with the central directory first. The main reason is that the first `zarr.json` can become obsolete, rendering streaming access inefficient compared to seeking. We also observed that strict file ordering cannot be maintained when appending a new `zarr.json` (e.g., adding labels) to an existing .ozx file. Furthermore, we encounter cases where metadata is generated during acquisition; therefore, we lean toward writing data first and metadata second to avoid writing it twice. For the stated reasons, we will likely not produce .ozx files with `zarr.json` files ordered first. - **Ordering of zarr.json in central directory:** This is reasonable for discoverability, especially for the root `zarr.json` if consolidated metadata is present. For all other `zarr.json` files, and for a root `zarr.json` without consolidated metadata, this seems less relevant for us and depends on the number of file entries. Therefore in our use case we might omit it for now and introduce it later if needed. @@ -30,7 +39,7 @@ We support standardizing single-file OME-Zarr via ZIP (.ozx). In our context at - **ZIP disadvantage in performance:** Compared to a directory store, file content is not necessarily stored page-aligned. In our implementation, we observed a significant performance impact for both reading and writing when using unbuffered, page-aligned I/O. To avoid read-modify-write cycles, we allocated a separate page for each local file header and kept partially filled pages empty. We also ensured this for chunks inside shards as well as the shard index. Unfortunately, due to the local file header, this results in memory overhead, though this is acceptable when sharding is turned on and chunksize is not too small. This point could be added under the drawback section in the RFC. -- **Split archives:** Field realities sometimes require multi-volume transport. Although splitting (e.g., channels or a measurement series) into smaller datasets is often possible — and recommended for other non-splittable file formats like .czi and .ims — we see use cases where archive-level splitting would be beneficial, particularly from a user-experience perspective. However, we acknowledge that this adds complexity to implementations, and support this decision. +- **Split archives:** Field realities sometimes require multi-volume transport. Although splitting (e.g., channels or a measurement series) into smaller datasets is often possible — and recommended for other non-splittable file formats like .czi and .ims — we see use cases where archive-level splitting would be beneficial, particularly from a user-experience perspective. However, we acknowledge that this adds complexity to implementations, and support this decision. - **Thumbnails:** Applications might benefit from pre-rendered thumbnails. As there is no standardized way to store thumbnails for Zarr and OME-Zarr it might be a question if this should be a topic to be addressed by zipped OME-Zarr separately or if this is out of scope for this RFC. As an example many ZIP based formats (e.g. docx, 3mf) follow the Open Packaging Conventions to store thumbnails in a standardized way. diff --git a/rfc/9/comments/5/index.md b/rfc/9/comments/5/index.md index d8a8c64cb..77a3ae776 100644 --- a/rfc/9/comments/5/index.md +++ b/rfc/9/comments/5/index.md @@ -1,14 +1,28 @@ +--- +authors: + - name: Anna Kreshuk + orcid: 0000-0003-1334-6388 + affiliation: ilastik + - name: Dominik Kutra + github: k-dominik + orcid: 0000-0003-4202-3908 + affiliation: ilastik + - name: Benedikt Best + github: btbest + orcid: 0000-0001-6965-1117 + affiliation: ilastik +date: 2026-02-05 +--- + # RFC-9: Comment 5 (rfcs:rfc9:comment5)= ## Comment authors -This comment was written by the ilastik team: +```{document-authors} -* Anna Kreshuk, https://orcid.org/0000-0003-1334-6388 -* Dominik Kutra, https://orcid.org/0000-0003-4202-3908 -* Benedikt Best, https://orcid.org/0000-0001-6965-1117 +``` ## Conflicts of interest (optional) @@ -75,8 +89,8 @@ Alternatively, one could make this clear by adding an observation like the follo ## Minor comments and questions -* The proposed new section of the specification uses the term "SHALL", which is so far not used elsewhere in the specification. Since according to IETF RFC 2119, SHALL is synonymous to MUST, and MUST is the term used in the rest of the specification, this should be replaced. -* Duplication of "the" in "The ZIP file MUST contain the the OME-Zarr’s root-level zarr.json." +- The proposed new section of the specification uses the term "SHALL", which is so far not used elsewhere in the specification. Since according to IETF RFC 2119, SHALL is synonymous to MUST, and MUST is the term used in the rest of the specification, this should be replaced. +- Duplication of "the" in "The ZIP file MUST contain the the OME-Zarr’s root-level zarr.json." ## Recommendation diff --git a/rfc/9/comments/6/index.md b/rfc/9/comments/6/index.md index 19689c6c4..5f4cd1951 100644 --- a/rfc/9/comments/6/index.md +++ b/rfc/9/comments/6/index.md @@ -1,10 +1,20 @@ +--- +authors: + - name: Assa Diabira + affiliation: Institut Cochin (IMAG'IC / CID), Université Paris Cité, France + github: assadiab +date: 2026-06-22 +--- + # RFC-9: Comment 6 (rfcs:rfc9:comment6)= ## Comment authors -This comment was written by: Assa Diabira, Institut Cochin (IMAG'IC / Cochin Image Database), Université Paris Cité, Paris, France. +```{document-authors} + +``` ## Conflicts of interest (optional) diff --git a/rfc/9/index.md b/rfc/9/index.md index 768d7bbf9..bca3b3f04 100644 --- a/rfc/9/index.md +++ b/rfc/9/index.md @@ -1,3 +1,32 @@ +--- +authors: + - name: Jonas Windhager + github: jwindhager + affiliation: SciLifeLab / Uppsala University, Sweden + role: Corresponding Author + date: "2025-07-02" + - name: Norman Rzepka + github: normanrz + affiliation: scalable minds GmbH, Germany + role: Co-author + date: "2025-08-27" + - name: Mark Kittisopikul + github: mkitti + affiliation: HHMI Janelia, United States + role: Co-author + date: "2025-08-27" +editors: + - name: Josh Moore + github: joshmoore + affiliation: German BioImaging e.V. + role: Editor + date: "2025-11-05" +reference_pr: https://github.com/ome/ngff/pull/316 +manual_status: R4 +description: Zipped OME-Zarr +date: 2025-07-02 +--- + # RFC-9: Zipped OME-Zarr ```{toctree} @@ -13,23 +42,9 @@ Add a specification for storing an OME-Zarr hierarchy within a ZIP archive. ## Status -This RFC is currently in state `R2` (waiting on reviewers). - -| Role | Name | GitHub Handle | Institution | Date | Status | -| --------- | ------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------- | ---------- | ---------------------------------------------------------------- | -| Author | Jonas Windhager | [jwindhager](https://github.com/jwindhager) | SciLifeLab / Uppsala University, Sweden | 2025-07-02 | Corresponding Author [PR](https://github.com/ome/ngff/pull/316) | -| Author | Norman Rzepka | [normanrz](https://github.com/normanrz) | scalable minds GmbH, Germany | 2025-08-27 | Co-author [PR](https://github.com/ome/ngff/pull/316) | -| Author | Mark Kittisopikul | [mkitti](https://github.com/mkitti) | HHMI Janelia, United States | 2025-08-27 | Co-author [PR](https://github.com/ome/ngff/pull/316) | -| Editor | Josh Moore | [joshmoore](https://github.com/joshmoore) | German BioImaging e.V. | 2025-11-05 | Editor | -| Reviewer | Pete Bankhead | [petebankhead](https://github.com/petebankhead) | University of Edinburgh, United Kingdom | 2026-01-26 | [Review](./reviews/1/index) | -| Reviewer | Kola Babalola, Matthew Hartley | [kbab](https://github.com/kbab), [matthewh-ebi](https://github.com/matthewh-ebi) | BioImage Archive, EMBL-EBI | 2026-01-29 | [Review](./reviews/2/index) | -| Reviewer | Curtis Rueden | [ctrueden](https://github.com/ctrueden) | University of Wisconsin-Madison, United States | 2026-01-30 | [Review](./reviews/3/index) | -| Commenter | Matt McCormick | [thewtex](https://github.com/thewtex) | Fideus Labs LLC | 2025-11-15 | [Comment](./comments/1/index) | -| Commenter | Joost de Folter | [folterj](https://github.com/folterj) | BioImaging-NL | 2025-12-03 | [Comment](./comments/2/index) | -| Commenter | Chris Barnes | [clbarnes](https://github.com/clbarnes) | German BioImaging | 2025-12-12 | [Comment](./comments/3/index) | -| Commenter | Anna Kreshuk, Dominik Kutra, Benedikt Best | [k-dominik](https://github.com/k-dominik), [btbest](https://github.com/btbest) | ilastik | 2026-01-09 | [Comment](./comments/5/index) | -| Commenter | Lenard Spiecker, Matthias Grunwald | [l-spiecker](https://github.com/l-spiecker) | Miltenyi Biotec B.V. & Co. KG | 2026-02-05 | [Comment](./comments/4/index) | -| Commenter | Assa Diabira | [assadiab](https://github.com/assadiab) | Institut Cochin (IMAG'IC / CID), Université Paris Cité, France | 2026-06-22 | [Comment](./comments/6/index) | +```{rfc-status} + +``` ## Overview @@ -166,13 +181,14 @@ The `centralDirectory` attribute MAY contain the following key: - `jsonFirst`: If `true`, this indicates that the `zarr.json` files are ordered breadth-first in the central directory and precede other content, as recommended above. This allows the hierarchical structure of the contents to be discovered without parsing the entire central directory, which could contain many entries of Zarr chunks. Implementations MAY assume that no further `zarr.json` files exist beyond the first non-`zarr.json` file if `jsonFirst` is `true`. If `jsonFirst` is omitted, the value defaults to `false`. For example, + ```json { "ome": { "version": "XX.YY", "zipFile": { "centralDirectory": { - "jsonFirst": true, + "jsonFirst": true } } } @@ -217,8 +233,6 @@ Socialization: see Prior art and references; the draft was further discussed amo - A [neuroglancer view](https://neuroglancer-demo.appspot.com/#!%7B%22dimensions%22:%7B%22x%22:%5B3.6039815346402084e-7%2C%22m%22%5D%2C%22y%22:%5B3.6039815346402084e-7%2C%22m%22%5D%2C%22z%22:%5B5.002025531914894e-7%2C%22m%22%5D%7D%2C%22position%22:%5B135%2C137%2C118%5D%2C%22crossSectionScale%22:1%2C%22projectionScale%22:512%2C%22layers%22:%5B%7B%22type%22:%22image%22%2C%22source%22:%22https://static.webknossos.org/misc/6001240.ozx%7Czip:%7Czarr3:%22%2C%22localDimensions%22:%7B%22c%27%22:%5B1%2C%22%22%5D%7D%2C%22localPosition%22:%5B0%5D%2C%22tab%22:%22source%22%2C%22opacity%22:1%2C%22blend%22:%22additive%22%2C%22shader%22:%22#uicontrol%20invlerp%20contrast%5Cn#uicontrol%20vec3%20color%20color%5Cnvoid%20main%28%29%20%7B%5Cn%20%20float%20contrast_value%20=%20contrast%28%29%3B%5Cn%20%20if%20%28VOLUME_RENDERING%29%20%7B%5Cn%20%20%20%20emitRGBA%28vec4%28color%20%2A%20contrast_value%2C%20contrast_value%29%29%3B%5Cn%20%20%7D%5Cn%20%20else%20%7B%5Cn%20%20%20%20emitRGB%28color%20%2A%20contrast_value%29%3B%5Cn%20%20%7D%5Cn%7D%5Cn%22%2C%22shaderControls%22:%7B%22contrast%22:%7B%22range%22:%5B7%2C927%5D%2C%22window%22:%5B0%2C1159%5D%7D%2C%22color%22:%22#ff0000%22%7D%2C%22volumeRenderingDepthSamples%22:256%2C%22name%22:%226001240.ozx%20c-0.5%22%7D%2C%7B%22type%22:%22image%22%2C%22source%22:%22https://static.webknossos.org/misc/6001240.ozx%7Czip:%7Czarr3:%22%2C%22localDimensions%22:%7B%22c%27%22:%5B1%2C%22%22%5D%7D%2C%22localPosition%22:%5B1%5D%2C%22tab%22:%22source%22%2C%22opacity%22:1%2C%22blend%22:%22additive%22%2C%22shader%22:%22#uicontrol%20invlerp%20contrast%5Cn#uicontrol%20vec3%20color%20color%5Cnvoid%20main%28%29%20%7B%5Cn%20%20float%20contrast_value%20=%20contrast%28%29%3B%5Cn%20%20if%20%28VOLUME_RENDERING%29%20%7B%5Cn%20%20%20%20emitRGBA%28vec4%28color%20%2A%20contrast_value%2C%20contrast_value%29%29%3B%5Cn%20%20%7D%5Cn%20%20else%20%7B%5Cn%20%20%20%20emitRGB%28color%20%2A%20contrast_value%29%3B%5Cn%20%20%7D%5Cn%7D%5Cn%22%2C%22shaderControls%22:%7B%22contrast%22:%7B%22range%22:%5B25%2C824%5D%2C%22window%22:%5B0%2C1025%5D%7D%2C%22color%22:%22#00ff00%22%7D%2C%22volumeRenderingDepthSamples%22:256%2C%22name%22:%226001240.ozx%20c0.5%22%7D%5D%2C%22selectedLayer%22:%7B%22visible%22:true%2C%22layer%22:%226001240.ozx%20c-0.5%22%7D%2C%22layout%22:%224panel-alt%22%2C%22helpPanel%22:%7B%22row%22:2%7D%2C%22settingsPanel%22:%7B%22row%22:3%7D%2C%22toolPalettes%22:%7B%22Shader%20controls%22:%7B%22side%22:%22left%22%2C%22row%22:1%2C%22query%22:%22type:shaderControl%22%7D%7D%7D) of the [generated data](https://static.webknossos.org/misc/6001240.ozx) has kindly been [made available](https://github.com/ome/ngff/pull/316#issuecomment-3302595684) by Davis Bennett. - [ozx-tck](https://github.com/clbarnes/ozx-tck) is a toolkit to validate existing .ozx files and generate valid, warning, and error test cases. - - ## Drawbacks, risks, alternatives, and unknowns Drawbacks: diff --git a/rfc/9/reviews/1/index.md b/rfc/9/reviews/1/index.md index cb081f6a0..c2955dd2c 100644 --- a/rfc/9/reviews/1/index.md +++ b/rfc/9/reviews/1/index.md @@ -1,10 +1,21 @@ +--- +authors: + - name: Pete Bankhead + affiliation: University of Edinburgh + github: petebankhead +date: 2026-01-26 +recommendation: accept +--- + # RFC-9: Review 1 (rfcs:rfc9:review1)= ## Comment authors -This comment was written by: Pete Bankhead, University of Edinburgh +```{document-authors} + +``` ## Conflicts of interest (optional) @@ -23,7 +34,7 @@ I am strongly in favor of standardized single-file support, which I think will m I'm not familiar enough with ZIP to understand the rationale for this recommendation or how straightforward it would be to follow. Specifically for Java, Zip files can be written with [`ZipFile`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/zip/ZipFile.html) or the [optional Zip file system module](https://docs.oracle.com/en/java/javase/25/docs/api/jdk.zipfs/module-summary.html). -I believe both support ZIP64, but I do not see an API to request that it is always used, including for smaller files. Apache Commons Compress [provides more ZIP64 control](https://commons.apache.org/proper/commons-compress/apidocs/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.html#setUseZip64(org.apache.commons.compress.archivers.zip.Zip64Mode)), at the expense of requiring an extra dependency. +I believe both support ZIP64, but I do not see an API to request that it is always used, including for smaller files. Apache Commons Compress [provides more ZIP64 control](), at the expense of requiring an extra dependency. The source for OpenJDK's `ZipFileSystem` [mentions a `"forceZIP64End"` property](https://github.com/openjdk/jdk/blob/master/src/jdk.zipfs/share/classes/jdk/nio/zipfs/ZipFileSystem.java#L179), but this appears to be undocumented. @@ -44,7 +55,6 @@ Under **User experience-related challenges**: The 'preview' aspect makes it tempting to want to embed a thumbnail, which could be supported by some applications or operating system plugins. Should this be explicitly forbidden / discouraged / encouraged in a standard way? - ## Recommendation Adopt, with some clarification around ZIP64 to ensure the recommendation is justified and readily achievable across most relevant programming languages. diff --git a/rfc/9/reviews/2/index.md b/rfc/9/reviews/2/index.md index 23f1e9d0f..441f5551d 100644 --- a/rfc/9/reviews/2/index.md +++ b/rfc/9/reviews/2/index.md @@ -1,10 +1,24 @@ +--- +authors: + - name: Kola Babalola + affiliation: BioImage Archive, EMBL-EBI + github: kbab + - name: Matthew Hartley + affiliation: BioImage Archive, EMBL-EBI + github: matthewh-ebi +date: 2026-01-29 +recommendation: minor_changes +--- + # RFC-9: Review 2 (rfcs:rfc9:review2)= ## Review authors -Kola Babalola, Matthew Hartley, the BioImage Archive, EMBL-EBI. +```{document-authors} + +``` ## Conflicts of interest @@ -17,10 +31,12 @@ This RFC represents highly valuable work, and we are in favour of adoption. The ## Significant comments and questions ### Versions of OME Zarr + The RFC only applies to OME-Zarrs with metadata in zarr.json (not .zattr / .zarray) which implies at least OME Zarr v0.5. Is it worth explicitly mentioning this in the RFC? This might make sense in the ‘Compatibility’ section. ### Recommendations on maximum archive size -The RFC in places alludes to the size of OME Zarrs and explicitly mentions 4GiB in the recommendation to use ZIP64 in the Proposal section. In the User experience-related challenges subsection of the Background section “a few small images” is mentioned. Additionally, the recommendations prohibit multi-volume archives. + +The RFC in places alludes to the size of OME Zarrs and explicitly mentions 4GiB in the recommendation to use ZIP64 in the Proposal section. In the User experience-related challenges subsection of the Background section “a few small images” is mentioned. Additionally, the recommendations prohibit multi-volume archives. However, no explicit guidance is given on size limitations associated with the single file format. Presumably the upper limit of size of a single file on filesystems is a hard limit, but there are practical limitations to the storage and transfer of extremely large files below the filesystem-imposed limit. Since the RFC explicitly prohibits multi-part archives, it would be useful to include a brief discussion of the limitations this imposes, and guidance for users with OME-Zarrs above this size. diff --git a/rfc/9/reviews/3/index.md b/rfc/9/reviews/3/index.md index 6227b45f9..46565a2de 100644 --- a/rfc/9/reviews/3/index.md +++ b/rfc/9/reviews/3/index.md @@ -1,10 +1,21 @@ +--- +authors: + - name: Curtis Rueden + affiliation: University of Wisconsin-Madison + github: ctrueden +date: 2026-01-30 +recommendation: major_changes +--- + # RFC-9: Review 3 (rfcs:rfc9:review3)= ## Review authors -Curtis Rueden, University of Wisconsin-Madison. +```{document-authors} + +``` ## Conflicts of interest @@ -27,6 +38,7 @@ The proposal should articulate the technical requirements of a single-file OME-Z #### Conventional use cases The phrase "conventional use cases" is frequently used, but not fully defined. Examples are given: + - Reasonably small images stored on the local desktop file system. - associate an OME-Zarr file type with their favorite image viewer (“double click” functionality) - effortlessly use their OME-Zarr images with existing file-centric tooling @@ -38,6 +50,7 @@ But a clear bullet-list of community-gathered use cases would be clarifying. #### Streaming There is only one mention of streaming. Is ozx intended to be streamable from a remote source? + - If not: this should be stated explicitly in the RFC that streamability is a non-goal. - Or if so: ZIP is not ideal out of the box, due to the central directory being at the end of the file. - From the beginning of the ZIP, you don't know how many ZIP entries you are going to receive. @@ -49,7 +62,7 @@ There is only one mention of streaming. Is ozx intended to be streamable from a A core use case of ZIP in general is the ability to modify the archive, adding and removing files after initial creation. Are the contents of a zipped OME-Zarr file intended to be mutable? Given that three of the five points in "Disadvantages of the ZIP archive file format" are about mutability concerns, I will assume yes -- although my tentative recommendation would actually be to disallow ZIP-specific mutation actions on .ozx files in favor of simply rewriting them cleanly when changes are needed, similar to most other image file formats. Of course, it ultimately depends on the community requirements around OME-Zarr, but for finite mutation-oriented scenarios, one can imagine extracting the ZIP contents, operating on the unzipped OME-Zarr directory structure, and then zipping it again after mutations are complete. -If zipped OME-Zarr *is* intended to be mutable, that should be explicitly stated as a requirement, and the ramifications of that decision should be discussed on more depth. For example, mutation of data or metadata may necessitate corresponding modifications to the zarr.json entry. According to the ZIP specification, modifying zarr.json in this way will orphan the entry at the head of the file and append the revised version to the tail, spoiling the file's "zarr.json files come first" recommendation, and also potentially impacting streamability (see also "Streaming" above). Small adjustments to the proposal could potentially mitigate these issues: e.g., the addition of an optional fixed-sized header file as first entry with directory tree mutations directly overwriting those header bytes in place, or the inclusion of trailing padding to all ome.zarr entries like how the ID3v2 tag format supports a padded leading header to allow metadata room to grow. Of course, such mitigations also complicate the mutation operation logic, since general-purpose ZIP libraries do not normally perform such bookkeeping. +If zipped OME-Zarr _is_ intended to be mutable, that should be explicitly stated as a requirement, and the ramifications of that decision should be discussed on more depth. For example, mutation of data or metadata may necessitate corresponding modifications to the zarr.json entry. According to the ZIP specification, modifying zarr.json in this way will orphan the entry at the head of the file and append the revised version to the tail, spoiling the file's "zarr.json files come first" recommendation, and also potentially impacting streamability (see also "Streaming" above). Small adjustments to the proposal could potentially mitigate these issues: e.g., the addition of an optional fixed-sized header file as first entry with directory tree mutations directly overwriting those header bytes in place, or the inclusion of trailing padding to all ome.zarr entries like how the ID3v2 tag format supports a padded leading header to allow metadata room to grow. Of course, such mitigations also complicate the mutation operation logic, since general-purpose ZIP libraries do not normally perform such bookkeeping. #### Encryption @@ -71,10 +84,10 @@ Is fast performance a goal of this format? If so, how fast? In my view, efficien It would be good for the RFC to break this down more explicitly, with a short discussion of each of ZIP's relevant advantages. That is: how good are each of these advantages in practice for OME Zarr? For example: -* Is it desirable/intended that users can feed a .ozx file to a general-purpose unzipping tool to produce a normal (non-zipped) ome-zarr dataset on disk? -* Is it desirable/intended that zipped ome-zarr files have integrity checksums (CRC32) for file contents? -* Is it desirable/intended that zipped ome-zarr files can be modified after initial creation? (See also "Mutability" above.) -* How +- Is it desirable/intended that users can feed a .ozx file to a general-purpose unzipping tool to produce a normal (non-zipped) ome-zarr dataset on disk? +- Is it desirable/intended that zipped ome-zarr files have integrity checksums (CRC32) for file contents? +- Is it desirable/intended that zipped ome-zarr files can be modified after initial creation? (See also "Mutability" above.) +- How > Simplicity @@ -87,6 +100,7 @@ If simplicity is a key requirement, ozx files might be better served defining th > Widespread adoption Why does this matter for OME-Zarr? + - As a binary file, the .ozx file will be opaque to most users. - Savvy users could work with the file as a ZIP file, using ZIP-compatible tools. - But should they? Any naive modification to the ozx file would corrupt it, as discussed above. @@ -99,6 +113,7 @@ Why does this matter for OME-Zarr? > on-board tooling of various operating systems When would this tooling come into play for users? + - They could rename the file from .ozx to .zip and then use on-board tooling to extract the contents. - Any other benefits? Reconstruction of damaged/incomplete archives? Would users do this often? @@ -117,10 +132,11 @@ For future-proofing, I suggest generalizing this field beyond only a boolean. It > This allows the hierarchical structure of the contents to be discovered without parsing the entire central directory, which could contain many entries of Zarr chunks. It would be helpful for the proposal to give an example of central directory size vs zarr.json size, to give a sense of performance gains here. + - For the example ozx file? - For a larger file, e.g. tubhiswt.ome.tif converted to ozx with a reasonable sharding structure? -Regardless: knowing the hierarchical structure unfortunately does not help with random access, due to compressed block size variability -- in what scenarios *does* it help to discover that structure up front? +Regardless: knowing the hierarchical structure unfortunately does not help with random access, due to compressed block size variability -- in what scenarios _does_ it help to discover that structure up front? ## Minor comments and questions @@ -157,6 +173,7 @@ And less crucial but still beneficial to the proposal: My specific recommendation would be to add language like the following to the RFC: > The following ZIP features MUST NOT be used in ozx files: +> > - Encryption (any method) > - Compression at ZIP level (STORE method only) > - Extra fields containing non-Zarr data @@ -176,7 +193,7 @@ Finally, as food for thought, here is my devil's-advocate pitch for a minimal bi - Existence of such files will necessitate demand for image software to support them. -- To support them while also supporting recommendation-compliant ozx files efficiently, ozx readers will need to implement (at least) two branches of case logic: one case achieving good performance for the well-performing ozx files, and another more general case achieving support *at all* for the noncompliant files. +- To support them while also supporting recommendation-compliant ozx files efficiently, ozx readers will need to implement (at least) two branches of case logic: one case achieving good performance for the well-performing ozx files, and another more general case achieving support _at all_ for the noncompliant files. - Such case logic will complexify ome-zarr reader implementations to such an extent that the gains in simplicity from using ZIP become outweighed by the losses (code complexity, maintainability) incurred by the case logic. diff --git a/rfc/index.md b/rfc/index.md index 82367c9ae..7151e0bc4 100644 --- a/rfc/index.md +++ b/rfc/index.md @@ -44,8 +44,5 @@ and open a PR. If there are any questions, please contact the editors under -```{csv-table} RFC Listing -:header-rows: 1 -:widths: 5, 30, 5, 10, 10 -:file: listing.csv +```{rfc-listing} ``` diff --git a/rfc/listing.csv b/rfc/listing.csv deleted file mode 100644 index e131ee737..000000000 --- a/rfc/listing.csv +++ /dev/null @@ -1,12 +0,0 @@ -RFC,Description,Date,Status,OME-Zarr Version -[0](0/index.md),Original consensus model for decision making,2021,N/A,N/A -[1](1/index.md),RFC Process,2024,Adopted,N/A -[2](2/index.md),Zarr V3 Support,2024,Adopted,0.5 -[3](3/index.md),Remove axis restrictions,2024,Under review, -[4](4/index.md),Axis Anatomical Orientation,2024,Accepted, -[5](5/index.md),Coordinate systems and transformations,2024,Implementation, -[6](6/index.md),Flattening the multiscales array,2025,Superseded, -[7](7/index.md),Channel provenance,TBD,TBD, -[8](8/index.md),Collections,2026,Under review, -[9](9/index.md),Zipped OME-Zarr,2025,Under review, -[10](10/index.md),NGFF Governance and the Editorial Board,2026,Under review, diff --git a/rfc/schema/front_matter.yaml b/rfc/schema/front_matter.yaml new file mode 100644 index 000000000..c6e8d0b94 --- /dev/null +++ b/rfc/schema/front_matter.yaml @@ -0,0 +1,196 @@ +id: https://w3id.org/ome/ngff/rfc-front-matter +name: NGFF_RFC_Front_Matter +version: 0.1.0 +description: >- + This schema describes the YAML front matter of the NGFF RFC documents. Every RFC page + carries a block of metadata at the top of its `index.md`, and so does every review, + comment and response filed against it. The website renders the record tables, the + status line and the RFC listing from those blocks (see `_ext/rfc_status.py` and + `_ext/document_authors.py`). This schema is what + `rfc/schema/validate.py` checks each document against. + +prefixes: + ome: https://w3id.org/ome/ + ngff: https://w3id.org/ome/ngff/ + linkml: https://w3id.org/linkml/ + orcid: https://orcid.org/ +imports: + - linkml:types +default_range: string +default_prefix: ngff + +created_on: "2026-09-09" + +classes: + + Person: + description: >- + Somebody listed on an RFC or on one of its reviews, comments or responses. Only + the name is required; the remaining fields enrich the rendered tables, and each + one that is present is turned into a link or a column entry. + attributes: + name: + description: Full name, written as the person wishes to be credited. + required: true + github: + description: GitHub handle, without the leading "@" or the profile URL. + orcid: + description: >- + ORCID identifier in its bare 0000-0000-0000-0000 form, without the + https://orcid.org/ prefix. The final character may be an X, which ORCID + uses as a checksum digit. + pattern: "^\\d{4}-\\d{4}-\\d{4}-\\d{3}[0-9X]$" + email: + description: Contact e-mail address. + affiliation: + description: Institution the person is credited under, as plain text. + affiliation_url: + description: Link for the institution, e.g. a ROR record or its homepage. + range: uri + role: + description: >- + The person's role on this RFC, shown in the "Status" column, e.g. + "Corresponding Author", "Co-author", "Editor" or "Implemented". + date: + description: >- + Date the person joined the document; people are added throughout the process, + so this differs from the document's own date. Write it as YYYY-MM-DD, quoted + so YAML keeps it a string rather than parsing it into a date object. + range: date + reference: + description: >- + Link backing an endorsement, e.g. the PR comment where it was given. Only + meaningful for entries under `endorsers`. + range: uri + + RFCFrontMatter: + description: The front matter of an RFC itself, i.e. of `rfc//index.md`. + tree_root: true + attributes: + manual_status: + description: >- + The status code the RFC currently sits at. Editors set it by hand as the RFC + moves through the process; it is never inferred from the reviews or responses + present in the directory. + range: StatusCode + required: true + description: + description: >- + A few words naming what the RFC changes, used as its row in the RFC listing. + required: true + status_note: + description: >- + Optional fragment explaining the status, e.g. "superseded by RFC-8". Shown in + parentheses after the status and in the listing's "Note" column. + ome_zarr_version: + description: >- + The OME-Zarr version this RFC landed in, once it has landed in a release. + date: + description: >- + Date the RFC moved from DRAFT to RFC status, ideally that of the reference + PR's merge. Its year is the listing's "Date" column. + range: date + reference_pr: + description: The pull request that introduced the RFC. + range: uri + authors: + description: The RFC's authors, in the order they should be credited. + range: Person + multivalued: true + inlined_as_list: true + editors: + description: The editors shepherding the RFC. + range: Person + multivalued: true + inlined_as_list: true + endorsers: + description: >- + Community members who have publicly endorsed the RFC. Optional, and each may + carry a `reference` link to where the endorsement was made. + range: Person + multivalued: true + inlined_as_list: true + + ReviewFrontMatter: + description: >- + The front matter of a review, comment or response, i.e. of + `rfc//{reviews,comments,responses}/