Skip to content

When composed with multiscales, disallow spatial:transform at top level; require it on all layout items#15

Open
kylebarron wants to merge 5 commits into
zarr-conventions:mainfrom
kylebarron:kyle/enforce-transform-multiscales
Open

When composed with multiscales, disallow spatial:transform at top level; require it on all layout items#15
kylebarron wants to merge 5 commits into
zarr-conventions:mainfrom
kylebarron:kyle/enforce-transform-multiscales

Conversation

@kylebarron
Copy link
Copy Markdown
Contributor

@kylebarron kylebarron commented Apr 7, 2026

Closes #12

Schema changes

  • If multiscales.layout exists, then spatial:transform must not exist at the top level
  • If multiscales.layout exists, then spatial:shape must not exist at the top level
  • If multiscales.layout exists, then spatial:transform must exist on all items within layout

Change list

  • Adds tests for invalid examples, to assert that they are correctly rejected by the schema validator.
    • sentinel2-tci.json is invalid because it doesn't have a spatial:transform on each item in layout.
    • dem-multiresolution.json is invalid because it has a spatial:transform at the top level.

@kylebarron kylebarron changed the title For multiscales, disallow transform at top level and require transform on all layout items When composed with multiscales, disallow spatial:transform at top level; require it on all layout items Apr 7, 2026
Comment thread schema.json
Comment on lines +225 to +230
"properties": {
"multiscales": {
"required": ["layout"]
}
},
"required": ["multiscales"]
Copy link
Copy Markdown
Contributor Author

@kylebarron kylebarron Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could change this to look for the specific multiscales uuid instead of the fields multiscales and layout, though above it hard-codes multiscales and layout as keys anyways

@geospatial-jeff
Copy link
Copy Markdown

Just make transform and shape required everywhere. It doesn't hurt to be explicit, and it's tiny.

@emmanuelmathot emmanuelmathot self-requested a review May 13, 2026 20:55
Copy link
Copy Markdown
Contributor

@emmanuelmathot emmanuelmathot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean, well-scoped change. if/then plus required on layout items reads correctly, and asserting invalid examples are rejected is a nice addition. A few notes:

  1. spatial:shape asymmetry. Forbidden at root but not required on layout items either, so it can vanish entirely. Intentional (derivable from the array shape) or oversight? Should mirror spatial:transform if it's normative.
  2. README not updated. Existing prose still says these properties "can be added to layout items" / "placed at root", which doesn't reflect the new normative rule.
  3. dem-multiresolution-partial.json violates two rules at once (missing on some items and root-level present), so it doesn't independently exercise the "missing on some items" branch. Inline fix below.
  4. Will conflict with #24 (removes the 2D/3D oneOf arms); easiest to rebase after that lands.

Comment thread schema.json
"multiscales": {
"type": "object",
"description": "When composing with multiscales convention, spatial: properties can be added to layout items",
"description": "When composing with multiscales convention, spatial: properties must be added to every layout item. spatial:transform is required on all layout items to unambiguously define the coordinate transformation for each resolution level.",
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only spatial:transform is actually required on every layout item, not spatial: properties generally:

Suggested change
"description": "When composing with multiscales convention, spatial: properties must be added to every layout item. spatial:transform is required on all layout items to unambiguously define the coordinate transformation for each resolution level.",
"description": "When composing with the multiscales convention, `spatial:transform` is required on every layout item to unambiguously define the coordinate transformation for each resolution level. `spatial:transform` and `spatial:shape` must not appear at the root attributes level in this case.",

Comment thread schema.json
"spatial:transform": {
"type": "array",
"description": "Transform override for this resolution level",
"description": "Affine transform for this resolution level mapping array indices to coordinates. Required on every layout item when using multiscales with this convention.",
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required below is unconditional inside layout items, so the qualifier is misleading:

Suggested change
"description": "Affine transform for this resolution level mapping array indices to coordinates. Required on every layout item when using multiscales with this convention.",
"description": "Affine transform for this resolution level, mapping array indices to coordinates. Required on every layout item.",

Comment on lines +119 to +126
"spatial:transform": [
0.000277778,
0.0,
-180.0,
0.0,
-0.000277778,
90.0
],
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop the root-level spatial:transform so this isolates the "missing on some items" violation:

Suggested change
"spatial:transform": [
0.000277778,
0.0,
-180.0,
0.0,
-0.000277778,
90.0
],

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ambiguous usage of spatial:transform in conjunction with multiscales convention

4 participants