Discrete Global Grid System Attribute Convention for Zarr

• UUID: 7b255807-140c-42ca-97f6-7a1cfecdbc38
• Name: dggs
• Schema URL: https://raw.githubusercontent.com/zarr-conventions/dggs/refs/tags/v1/schema.json
• Spec URL: https://github.com/zarr-conventions/dggs/blob/v1/README.md
• Extension Maturity Classification: Pilot
• Owner: @keewis

Description

This convention describes a JSON object that encodes the coordinate and grid parameters of a discrete global grid system (DGGS) under the dggs key in the attributes of zarr groups and arrays.

It is inspired by the CF conventions' healpix grid mapping (first included in version 1.13), but deliberately makes different choices in some cases to be more broadly useful in the zarr ecosystem.

Inheritance Model

The dggs convention object follows a simple group-to-array inheritance model that should be understood first:

Inheritance Rules

1. Group-level definition (recommended): When the dggs convention is defined at the group level, it applies to all arrays that are direct children of that group. It does not apply to groups or arrays deeper in the hierarchy (e.g., grandchildren).
2. Array-level override: An array can completely override the group's dggs convention with its own definition.
3. Partial replacement: Partial inheritance (overriding only some fields while inheriting others) is not allowed.

Configuration

The configuration in the Zarr convention metadata can be used in these parts of the Zarr hierarchy:

• Group
• Array

	Type	Description	Required	Reference
dggs	object	The grid metadata	✓ Yes	dggs

Field Details

dggs

Object representing the conrete instance of the discrete global grid system.

• Type: object
• Required: ✓ Yes

This field MUST describe the concrete instance of the discrete global grid system. See the DGGS Object section below for details.

DGGS Object

	Type	Description	Required	Reference
name	string	The lower-cased name of the DGGS.	✓ Yes	name
refinement_level	integer	The refinement level as an unsigned integer.	✓ Yes	refinement_level
ellipsoid	object	The ellipsoid used as a reference body.	✕ No	ellipsoid
spatial_dimension	string	Name of the spatial dimension	✓ Yes	spatial_dimension
coordinate	string	Name of the coordinate	✕ No	coordinate
compression	string	Compression type of the coordinate	Conditional	compression

Additional DGGS-specific parameters are allowed (see DGGS specific parameters).

name

The canonical name of the DGGS, normalized to a lower-cased string.

• Type: string
• Required: ✓ Yes

refinement_level

Also called the "depth" or "order", this parameter describes the size of the DGGS cells.

• Type: integer | null
• Required: ✓ Yes

It MUST only be null if the associated coordinate is variable-sized.

ellipsoid

The ellipsoid describes the reference system of the DGGS. See the ellipsoid object for more information.

• Type: object
• Required: ✕ No

If not given, a sphere with a radius of 6370997 m MUST be assumed.

spatial_dimension

The name of spatial dimension.

• Type: string
• Required: ✓ Yes

coordinate

coordinate points to the array containing the cell ids. If not provided, the entire domain must be covered and the refinement_level MUST NOT be null.

• Type: string
• Required: ✕ No

compression

compression describes the cell id compression method chosen. It MUST only be provided if the coordinate was provided. If refinement_level is null, compression MUST be "none".

Uncompressing the cell ids MUST result in an array of the same length as the spatial_dimension.

• Type: string
• Required: Conditional

The following values are possible:

• "none": the array referenced by coordinate MUST be 1-dimensional and have the same size as the spatial_dimension.
• "compacted": the array referenced by coordinate MUST be 1-dimensional.
• "ranges": the array referenced by coordinate MUST have a shape of (n_ranges, 2) that describes the contiguous ranges covered.

Ellipsoid object

The ellipsoid object is modelled after projjson's definition. It can describe either a sphere or an ellipsoid.

Following projjson and WKT the name is required to help compare the values in the ellipsoid object against other sources, but should not be used to infer the values. For examples, look for the ellipsoid fields in these CRS definitions:

Naming Authority	URL
European Petroleum Survey Groups (EPSG)	http://www.opengis.net/def/crs/EPSG or http://epsg.org
International Astronomical Union (IAU)	http://www.opengis.net/def/crs/IAU
Open Geospatial Consortium (OGC)	http://www.opengis.net/def/crs/OGC
ESRI	https://spatialreference.org/ref/esri/

(taken from the proj:code documentation of the proj convention)

Sphere

	Type	Description	Required
name	string	Human-readable name of the sphere	✓ Yes
radius	number	The radius of the sphere	✓ Yes

Ellipsoid

	Type	Description	Required
name	string	Human-readable name of the ellipsoid	✓ Yes
semi_major_axis	number	The semimajor axis of the ellipsoid	✓ Yes
semi_minor_axis	number	The semiminor axis of the ellipsoid	Conditional
inverse_flattening	number	The inverse flattening of the ellipsoid	Conditional

semi_minor_axis and inverse_flattening are mutually exclusive.

DGGS specific parameters

Some DGGS have parameters other than refinement_level, which can be added to the dggs object. This section contains standardized extensions for common DGGS.

HEALPix

The HEALPix DGGS ("name": "healpix") has one additional required parameter:

	Type	Description	Required
indexing_scheme	string	HEALPix indexing scheme	✓ Yes

The indexing_scheme parameter describes the space-filling curve used to index the cells. For values other than ring or nested the refinement_level must be null.

Known values are: nested, ring, zuniq, nuniq (but there are many more where the name matches [a-z_]*uniq).

Examples

HEALPix

Uncompressed subdomain:

{
  "attributes": {
    "zarr_conventions": [
      {
        "schema_url": "https://raw.githubusercontent.com/zarr-conventions/dggs/refs/tags/v1/schema.json",
        "spec_url": "https://github.com/zarr-conventions/dggs/blob/v1/README.md",
        "uuid": "7b255807-140c-42ca-97f6-7a1cfecdbc38",
        "name": "dggs",
        "description": "Discrete Global Grid Systems convention for zarr"
      }
    ],
    "dggs": {
      "name": "healpix",
      "refinement_level": 10,
      "indexing_scheme": "nested",
      "spatial_dimension": "cells",
      "ellipsoid": {
        "name": "WGS84",
        "semi_major_axis": 6378137.0,
        "inverse_flattening": 298.257223563
      },
      "coordinate": "cell_ids",
      "compression": "none"
    }
  }
}

Full domain, spherical, missing coordinate:

{
  "attributes": {
    "zarr_conventions": [
      {
        "schema_url": "https://raw.githubusercontent.com/zarr-conventions/dggs/refs/tags/v1/schema.json",
        "spec_url": "https://github.com/zarr-conventions/dggs/blob/v1/README.md",
        "uuid": "7b255807-140c-42ca-97f6-7a1cfecdbc38",
        "name": "dggs",
        "description": "Discrete Global Grid Systems convention for zarr"
      }
    ],
    "dggs": {
      "name": "healpix",
      "refinement_level": 16,
      "indexing_scheme": "nested",
      "spatial_dimension": "cells"
    }
  }
}

Acknowledgements

This template is based on the STAC extensions template.