a proposal to simplify encoding for zarr data

What is your issue?

When used for zarr data, the .encoding dict is populated with keys derived from the signature of a high-level function (zarr.create_array). That function is abstract, and deliberately elides differences between zarr v2 and zarr v3 data, and obscures important properties of the an array, like the exact chunk grid metadata it uses.

Better than the signature of create_array is an array metadata document itself. The array metadata document is small and defined by the zarr specs, so it's independent of zarr-python changes. You could represent the array metadata as a dict, or as a dataclass, if that's more ergonomic (a dict is simpler in case there are extra fields in metadata).

I think this could work by adding a new zarr_array_metadata key to the encoding dict. The value is a dict that models either a zarr v2 or zarr v3 metadata document. Zarr python (and any other zarr implementation) can create an array from a plain metadata dict. Note: the metadata is a complete description of a stored array, but it doesn't include runtime configuration like write_empty_chunks, so you might need a separate zarr_array_config key for this, if you want to consolidate that kind of configuration info. In any case, the full metadata document is a much more durable representation of an array than what you are using today (a subset of the signature of create_array)

xarray would need a bit of machinery to ensure that the old encoding keys still work, that their value is consistent with the array metadata, and that their use is ultimately deprecated. And it's likely that we need to improve things on the zarr-metadata side, to make the static types better. But I think this is a much better direction than putting create_array kwargs in your encoding dict.

Start with the zarr-metadata v2 and v3 array.py definitions linked in the issue, then trace xarray’s current encoding handling for zarr.create_array kwargs. Determine how zarr_array_metadata and runtime configuration should coexist with legacy encoding keys and how consistency should be tested. Done means supporting a durable v2/v3 metadata representation without breaking existing encoding behavior.