Proper handling of the Z dimension #10

Problem

The schema currently accepts 3D variants for several properties without fully specifying their semantics:

• spatial:transform: Allows 9 elements ("3D affine transform (future extension)"), but the spec only describes the 2D case. The element count is also wrong — a 3D affine is a 3x4 matrix requiring 12 elements, not 9.
• spatial:shape: Allows 3 elements ([depth, height, width])
• spatial:bbox: Allows 6 elements ([xmin, ymin, zmin, xmax, ymax, zmax])
• spatial:dimensions: Allows 3 elements (["z", "y", "x"])

An implementation could write a 9-element transform that validates against the schema but has no defined semantics.

Background

No mainstream geospatial library supports 3D affine transforms:

• GDAL, rasterio, Affine library: All strictly 2D (6 coefficients)
• GeoTIFF: 2D only
• NetCDF/CF: Doesn't use affine transforms — each dimension gets its own 1D coordinate variable (including depth/level)

The Z dimension is universally treated as a separate concern from XY in geospatial software: either as a band index (GeoTIFF), a 1D coordinate variable (CF), or a separate vertical CRS (OGC compound CRS). The only domain where 3D affine transforms are standard is medical/neuroimaging (NIfTI).

In practice, the Z dimension is almost always independent of XY — no rotation coupling them. It's typically just a scale + offset, or irregular coordinate values.

Options

Option 1: Remove 3D from the schema, delegate Z to CF convention (recommended)

Restrict spatial:transform to 2D only (6 elements). Keep the spatial convention focused on the XY affine transform, which aligns with GDAL/rasterio and the geospatial ecosystem. The Z dimension would be handled by CF coordinate variables, which is already the standard approach for depth, pressure levels, altitude, etc.

Depending on how strict we want to be, we could also restrict spatial:dimensions to 2 elements and spatial:bbox/spatial:shape to their 2D variants.

Pros:

• No undefined behavior in v1
• Matches how the geospatial ecosystem actually handles Z
• CF coordinate variables are more flexible than an affine for irregular Z spacing (e.g., pressure levels)
• Can revisit in a future version if a real use case emerges

Cons:

• Requires CF convention composition for datasets with a Z dimension
• Non-geospatial 3D use cases (microscopy, medical imaging) would need a different solution

Option 2: Define full 3D affine semantics

Fix the element count to 12 and document the 3D affine transform formula.

Pros:

• Complete spec for both 2D and 3D

Cons:

• No geospatial library supports 3D affine transforms
• A full 3D affine (with XZ/YZ rotation) is overkill — Z is almost never coupled to XY
• More spec surface area to maintain with no clear use case driving it