For retrieving the list of available discrete global grid reference systems:

The Implementation SHALL support an HTTP GET operation at a resource path ending with …​/dggs.

The Implementation SHALL support a JSON representation of this …​/dggs resource.

The …​/dggs resource SHALL include a dggs array property listing all discrete global grid reference systems supported by the Implementation.

Each element of the dggs array SHALL include a subset of the information available in the individual DGGS information described below, including at minimum the id, title, uri (if applicable), and links.

The links property SHALL include at minimum a link to the discrete global grid reference system using the self link relation type, as well as a link to the discrete global grid reference system using the [ogc-rel:dggs-definition] relation type.

For retrieving information for a particular available discrete global grid reference system:

The Implementation SHALL support an HTTP GET operation at a resource path ending with …​/dggs/{dggsId}.

The Implementation SHALL support a JSON representation of this …​/dggs/{dggsId} resource.

The …​/dggs/{dggsId} resource SHALL include an id property consistent with the {dggsId} resource path parameter.

The …​/dggs/{dggsId} resource SHALL include a link to the resource itself using the self link relation type.

The …​/dggs/{dggsId} resource SHALL include a link to a definition of the discrete global grid reference system (describing both the discrete global grid as well as the particular indexing scheme to identify zones by identifiers), using the link relation type [ogc-rel:dggs-definition]. The schema for that definition is likely to evolve in order to support describing a growing number of classes of DGGS. A first draft of this schema is available here.

The …​/dggs/{dggsId} resource SHALL include a templated link in the linkTemplates array to request information for a particular zone using the link relation type [ogc-rel:dggs-zone-info].

If the discrete global grid reference system (the combination of the discrete global grid and indexing system) is registered with an authority, the resource SHALL include uri property corresponding to that registered discrete global grid reference system.

If the discrete global grid reference system is based on a particular coordinate reference system, the resource shall specify that CRS in a crs property, preferably as a URI (if one is available).

The Implementation SHALL include a short title property identifying the discrete global grid reference system intended for display to a human.

The Implementation SHALL include a description property providing a summary description of the discrete global grid reference system used by this particular DGGS instance.

For retrieving information for a particular DGGS zone:

The Implementation SHALL support an HTTP GET operation at a resource path ending with …​/dggs/{dggsId}/zones/{zoneId} providing information for a valid individual zones of the discrete global grid reference system.

The zone information resource SHALL support a JSON representation.

The zone information resource SHALL include an id property corresponding to the {zoneId} resource path parameter.

The zone information resource SHALL include a link back to the corresponding DGGS resource (…​/dggs) using the [ogc-rel:dggs] link relation type.

The zone information resource SHOULD include an areaMetersSquare property indicating the surface area of the zone in square meters.

For a DGGS with three spatial dimension, the zone information resource SHOULD include a volumeMetersCube property indicating the volume of the zone in cubic meters.

For a temporal DGGS, the zone information resource SHOULD include a temporalDurationSeconds property indicating the amount of time covered by the zone in seconds.

The zone information resource SHOULD include a geometry property indicating the 2D and/or 3D spatial geometry of the zone, using GeoJSON or OGC Features & Geometry JSON for the JSON encoding.

For a temporal DGGS, the zone information resource SHOULD include a temporalInterval property indicating the start and end time of the zone.

The implementation SHOULD support a GeoJSON and/or OGC Features & Geometry JSON representation of the zone information resource where the top-level object is a feature representing the zone geometry, the feature ID corresponds to the {zoneId}, and the other properties described in this recommendation are properties of that feature.

For a zone associated with a particular collection, the implementation SHOULD provide summary statistics (minimum, maximum, average, stdDev) pertaining to this zone for each field (fields of the range of a coverage, or relevant numeric properties of a feature collection) of the data. In the JSON encoding, this SHOULD be implemented as a JSON dictionary mapping field names to an object with each statistic.

For a zone associated with a particular collection, the implementation SHOULD provide areaMetersSquareWithData, volumeMetersCubeWithData, temporalDurationSecondsWithData properties corresponding to the respective properties defined above for the overall zones, but considering only the portions of the zone where there is data (e.g., regions of the zone excluding NODATA values for a gridded coverage, or within geometry for a feature collection).

Implementations SHOULD include a Robots.txt file at the root of their Web API discouraging robots from crawling the DGGS zone resources.

The content of that Robots.txt file SHOULD include Disallow: /dggs//zones/* to prevent crawling all DGGS resources under the /zones/ resource path.

For retrieving data for a single DGGS zone:

The operation SHALL support an HTTP GET operation at a resource path ending with …​/dggs/{dggsId}/zones/{zoneId}/data.

The operation SHALL include a templated link to this resource path in the “Core” …​/dggs/{dggsId} resource link templates, and regular link in the …​/dggs/{dggsId}/zones/{zoneId} resource links using the link relation type [ogc-rel:dggs-zone-data].

The response of the HTTP GET operation SHALL have a status code of 200.

The content of the response SHALL be a data packet corresponding precisely to the area covered by the DGGS zone.

The selection of an encoding for the response SHALL be consistent with HTTP content negotiation.

The …​/dggs/{dggsId} resource SHALL include a defaultDepth property indicating the implementation’s default depth for when the zone-depth parameter is omitted. This default value could be any valid value and/or form as defined in the /req/data-custom-depths/zone-depth-parameter requirement (single depth, range of depths, or list of depths, relative to the {zoneId} hierarchy level).

Unless a zone-depth parameter is specified, the response SHALL return a data packet consistent with this defaultDepth property, in accordance with the capabilities of the negotiated data packet encoding.

For specifying a multi-dimensional subset for the zone data being retrieved (excluding dimensions of the discrete global grid reference system):

The Implementation SHALL support a subset query parameter for the zone data retrieval operation (resource path ending with …​/dggs/{dggsId}/zones/{zoneId}/data) conforming to the following Augmented Backus Naur Form (ABNF) fragment:

  SubsetSpec:       "subset"=axisName(intervalOrPoint)
  axisName:         {text}
  intervalOrPoint:  interval \| point
  interval:         low : high
  low:              point \| *
  high:             point \| *
  point:            {number} \| "{text}"

  Where:
     \" = double quote = ASCII code 0x42,
     {number} is an integer or floating-point number, and
     {text} is some general ASCII text (such as a time and date notation in ISO 8601).

The implementation SHALL support as axis names time for a temporal dataset, unless this temporal axis is an axis of the discrete global grid reference system.

If a third vertical spatial dimension is supported (if the resource’s spatial extent bounding box is three dimensional) and that dimension is not part of the discrete global grid system definition, the implementation SHALL also support a h dimension (elevation above the ellipsoid in EPSG:4979 or CRS84h) for geographic CRS and z for projected CRS, which are to be interpreted as the vertical axis in the CRS definition.

The implementation SHALL support as axis names any additional dimension (beyond spatial and temporal) as described in the extent property of the collection or dataset description.

The implementation SHALL return a 400 error status code if an axis name does not correspond to one of the axes of the Coordinate Reference System (CRS) of the data or an axis defined in the relevant extent property.

If a subset parameter including any of the dimensions corresponding to the axes of the discrete global grid reference system is used, the server SHALL return a 400 client error.

The implementation SHALL interpret multiple subset parameters, as if all dimension subsetting values were provided in a single subset parameter (comma separated). Example: subset=time(“2018-02-12T16:00:0Z”:”2018-02-12T20:00:00Z”)&subset=atm_pressure_hpa(500:750) is equivalent to subset=time(“2018-02-12T16:00:0Z”:”2018-02-12T20:00:00Z”),atm_pressure_hpa(500:750)

For specifying a time instant or interval for which to retrieve data from a zone for a non-temporal DGGS:

The implementation SHALL support a datetime parameter expressed corresponding to either a date-time instant or a time interval, conforming to the following syntax (using ABNF):

interval-closed     = date-time "/" date-time
interval-open-start = [".."] "/" date-time
interval-open-end   = date-time "/" [".."]
interval            = interval-closed / interval-open-start / interval-open-end
datetime            = date-time / interval

The syntax of date-time is specified by RFC 3339, 5.6.

Only the portions of the data within the specified interval SHALL be part of the zone data response, performing a trim operation for an interval or a slicing operation for an instant (in the case of a gridded coverage), or a filtering operation for feature data.

The implementation SHALL support a double-dot (..) or an empty string for the start/end as indicating an unbounded or half-bounded interval (only having a start or end).

If a datetime parameter is specified requesting zone data where no temporal dimension applies, the implementation SHALL either ignore the parameter or return a 4xx client error.

Parameter to specify the DGGS resolution levels beyond the specified DGGS zone’s hierarchy level to include in the response, when retrieving data for that zone

The implementation SHALL support a zone-depth parameter for the HTTP GET operation on a resource path ending with …​/dggs/{dggsId}/zones/{zoneId}/data.

The implementation SHALL accept the following types of values for the zone-depth parameter:

• A single positive integer value — representing a specific zone depth to return (e.g., zone-depth=5);

• A range of positive integer values in the form “{low}-{high}” — representing a continuous range of zone depths to return (e.g., zone-depth=1-8); or,

• A comma separated list of at least two (2) positive integer values — representing a set of specific zone depths to return (e.g., zone-depth=1,3,7). Some or all of these forms of the zone-depth parameter may not be supported with particular data packet encodings (the data encoding may support a fixed depth, a range of depths, and/or an arbitrary selection of depths).

For each zone depth to be included in the response, the interpretation of a selected depth (whether requesting a single depth, a range of depths, or a list of depths) SHALL be:

• 0 corresponding to a single set of range (properties / field) value(s) for the requested zone,

• 1 corresponding to all zones of the next deeper hierarchy level associated with the requested zone by the indexing scheme,

• ..

• n corresponding to all zones for the n‘th deeper level in the hierarchy level associated with the requested zone by the indexing scheme.

The association of zones of deeper hierarchy levels with the requested zone SHALL be based on the DGGS reference system, which takes into consideration both the grid definition as well as the indexing system in use for the DGGS resource.

If a zone-depth is specified, the operation SHALL return the data at the resolution(s) / scale(s) specified.

For retrieving a list of DGGS zones:

The Implementation SHALL support an HTTP GET operation at a resource path ending with …​/dggs/{dggsId}/zones.

The Implementation SHALL include a link to this resource path in the “Core” …​/dggs/{dggsId}` resource links using the link relation type http://www.opengis.net/def/rel/ogc/1.0/dggs-zone-query.

The response of the HTTP GET operation SHALL have a status code of 200.

The content of the response SHALL be a list of zones fully covering where data is available (in the case where the resource is associated with a particular dataset), and matching any additional query parameters specified by the client (e.g., a filtering query parameter), without any redundancy.

Unless the zones is a compact list of zones (see compact-zones parameter), the zones returned SHALL all be of the same DGGS hierarchy level.

The selection of an encoding for the returned list of zones SHALL be consistent with HTTP content negotiation.

The implementation SHALL support at minimum a JSON encoding (media type application/json) where each zone ID is specified as a string within an array of zones assigned to a zones property within a JSON object (e..g, { “zones”: [ “1-E-14”s, “1-E-15”, “1-F-14”, “1-F-15”, “1-F-16” ] }.

For specifying a level at which to return a list of DGGS zones using a zone-level query parameter:

The Implementation SHALL support a zone-level query parameter for the zone query operation (resource path ending with …​/dggs/{dggsId}/zones).

If a compact zones list is used (the default), the zones returned in the response SHALL be of the DGGS hierarchy level specified by the zone-level query parameter, or of a lower hierarchy level standing in for a compact representation of multiple zones at the requested hierarchy level.

If a compact zones list is not used, the zones returned in the response SHALL be of the DGGS hierarchy level specified by the zone-level query parameter.

For specifying whether to retrieve a list of DGGS zones using a compact-zones parameter:

The Implementation SHALL support a boolean compact-zones query parameter for the zone query operation (resource path ending with …​/dggs/{dggsId}/zones), where a value of true corresponds to the default behavior when the paramter is not specified, and a value of false disables the use of compact-zones in the response.

When the compact-zones parameter is to false, the zones list response SHALL NOT be a compact list, and SHALL explicitly list every individual zone at the requested or default DGGS hierarchy level.

When the compact-zones parameter is to true (or unspecified), the zones list response SHALL be a compact list, where children zones completely covering the area of a parent zone SHALL be replaced by that parent zone, in a recursive manner all the way to the lowest DGGS hierarchy level.

For specifying a parent zone within which to restrict zone listing using a parent-zone query parameter:

The Implementation SHALL support a parameter parent-zone zone identifier query parameter.

When specified, the response SHALL NOT contain zones which are not this parent zone itself or a descendant of that zone.

For specifying a paging limit for the list of zones using a limit query parameter:

The Implementation SHOULD support a parameter limit integer query parameter, with a minimum value of 1.

The response SHOULD not contain more zones than specified by the optional limit parameter (if specified).

If the API definition specifies a maximum value for the limit parameter, the response SHOULD not contain more zones than this maximum value.

If the value of the limit parameter is larger than the maximum value, this SHOULD NOT result in an error (but instead be replaced by the maximum as the parameter value).

If using compact zones, the parent zones SHOULD count as a single zone, rather than the number of children zones they stand in for.

If an implementation does not return the full list of zones for the request, a link with relation type next SHOULD be included in a links array property of the response, which a client can request to resume listing the zones.

For specifying a spatial bounding box for which to return a list of DGGS zones:

The Implementation SHALL support a bbox query parameter for the zone query operation (resource path ending with …​/dggs/{dggsId}/zones) with the characteristics defined in the OpenAPI Specification 3.0 fragment:

  bbox:
    name: bbox
    in: query
    description:
      Bounding box of the rendered map. The bounding box is provided as four or six coordinates

      * Lower left corner, coordinate axis 1
      * Lower left corner, coordinate axis 2
      * Minimum value, coordinate axis 3 (optional)
      * Upper right corner, coordinate axis 1
      * Upper right corner, coordinate axis 2
      * Maximum value, coordinate axis 3 (optional)

      The coordinate reference system and axis order of the values are indicated in the `bbox-crs` parameter or if the parameter is missing in http://www.opengis.net/def/crs/OGC/1.3/CRS84
    required: false
    schema:
      type: array
      oneOf:
      - minItems: 4
        maxItems: 4
      - minItems: 6
        maxItems: 6
      items:
        type: number
        format: double
    style: form
    explode: false

bbox SHALL be a comma separated list of four or six floating point numbers. If the bounding box consists of six numbers, the first three numbers are the coordinates of the lower bound corner of a three-dimensional bounding box and the last three are the coordinates of the upper bound corner. The axis order is determined by the bbox-crs parameter value or longitude and latitude if the parameter is missing (http://www.opengis.net/def/crs/OGC/1.3/CRS84 axis order for a 2D bounding box, http://www.opengis.net/def/crs/OGC/1.3/CRS84h for a 3D bounding box). For example in http://www.opengis.net/def/crs/OGC/1.3/CRS84 the order is left_lon, lower_lat, right_lon, upper_lat.

The returned list of zone IDs SHALL only contain zones inside or intersecting with the spatial extent of the geographical area of bounding box.

For specifying the CRS in used for the bbox parameter using the bbox-crs parameter

The list of zones resource SHALL support a bbox-crs parameter specifying the CRS used for the bbox parameter.

For Earth centric data, the implementation SHALL support http://www.opengis.net/def/crs/OGC/1.3/CRS84 as a value.

If the bbox-crs is not indicated http://www.opengis.net/def/crs/OGC/1.3/CRS84 SHALL be assumed.

The native CRS (storageCRS) SHALL be supported as a value. Other conformance classes may allow additional values (see crs parameter definition).

The CRS expressed as URIs or as safe CURIEs SHALL be supported.

If the bbox parameter is not used, the bbox-crs SHALL be ignored.

For specifying a multi-dimensional subset for which to return a list of DGGS zones:

The Implementation SHALL support a subset query parameter for the zone query operation (resource path ending with …​/dggs/{dggsId}/zones) conforming to the following Augmented Backus Naur Form (ABNF) fragment:

  SubsetSpec:       "subset"=axisName(intervalOrPoint)
  axisName:         {text}
  intervalOrPoint:  interval \| point
  interval:         low : high
  low:              point \| *
  high:             point \| *
  point:            {number} \| "{text}"

  Where:
     \" = double quote = ASCII code 0x42,
     {number} is an integer or floating-point number, and
     {text} is some general ASCII text (such as a time and date notation in ISO 8601).

The implementation SHALL support as axis names Lat and Lon for geographic CRS and x and y for projected CRS, which are to be interpreted as the best matching spatial axis in the CRS definition.

If a third spatial dimension is supported (if the resource’s spatial extent bounding box is three dimensional), the implementation SHALL also support a h dimension (elevation above the ellipsoid in EPSG:4979 or CRS84h) for geographic CRS and z for projected CRS, which are to be interpreted as the vertical axis in the CRS definition.

The implementation SHALL support as axis names time for a temporal dataset.

The implementation SHALL support as axis names any additional dimension (beyond spatial and temporal) as described in the extent property of the collection or dataset description.

The implementation SHALL return a 400 error status code if an axis name does not correspond to one of the axes of the Coordinate Reference System (CRS) of the data or an axis defined in the relevant extent property.

For a CRS where an axis can wrap around, such as subsetting across the dateline (anti-meridian) in a geographic CRS, a low value greater than high SHALL be supported to indicate an extent crossing that wrapping point.

The implementation SHALL interpret the coordinates as values for the named axis of the CRS specified in the subset-crs parameter value or in http://www.opengis.net/def/crs/OGC/1.3/CRS84 (http://www.opengis.net/def/crs/OGC/1.3/CRS84h for vertical dimension) if the subset-crs parameter is missing.

If the subset parameter including any of the dimensions corresponding to those of the map bounding box is used with a bbox, the server SHALL return a 400 client error.

The implementation SHALL interpret multiple subset parameters, as if all dimension subsetting values were provided in a single subset parameter (comma separated). Example: subset=Lat(-90:90)&subset=Lon(-180:180) is equivalent to subset=Lat(-90:90),Lon(-180:180)

For specifying the CRS in used for the subset parameter using the subset-crs parameter

The zone listing operation SHALL support a parameter subset-crs with the characteristics identifying the CRS in which the subset parameter is specified with a URI or safe CURIE.

For Earth centric data, http://www.opengis.net/def/crs/OGC/1.3/CRS84 as a value SHALL be supported.

If the subset-crs is not indicated, http://www.opengis.net/def/crs/OGC/1.3/CRS84 SHALL be assumed.

The native CRS (storageCRS) SHALL be supported as a value. Other requirements classes may allow additional values (see crs parameter definition).

CRSs expressed as URIs or as safe CURIEs SHALL be supported.

If no subset parameter referring to an axis of the CRS is used, the subset-crs SHALL be ignored.

For specifying a multi-dimensional subset for which to return a list of DGGS zones:

The implementation SHALL support a datetime parameter expressed corresponding to either a date-time instant or a time interval, conforming to the following syntax (using ABNF):

interval-closed     = date-time "/" date-time
interval-open-start = [".."] "/" date-time
interval-open-end   = date-time "/" [".."]
interval            = interval-closed / interval-open-start / interval-open-end
datetime            = date-time / interval

The syntax of date-time is specified by RFC 3339, 5.6.

Only the zones with data whose geometry intersect with the specified temporal interval SHALL be part of the zone list response.

The implementation SHALL support a double-dot (..) or an empty string for the start/end as indicating an unbounded or half-bounded interval (only having a start or end).

If a datetime parameter is specified requesting zone data where no temporal dimension applies, the implementation SHALL either ignore the parameter or return a 4xx client error.

For API/dataset-wide DGGS resources:

The Implementation SHALL support DGGS resources for the dataset as a whole, for the “Core” requirement class, as well as any resources defined in additional supported requirements classes.

For collection DGGS resources:

The Implementation SHALL support DGGS resources for at least one collection, for the “Core” requirement class, as well as any resources defined in additional supported requirements classes.

The /collections/{collectionId}/dggs and /collections/{collectionId}/dggs/{dggsId} resources SHALL include a link to the collection using the link relation type [ogc-rel:geodata].