7-data-retrieval: moved `zone-depth` definition/response to a separate

[geofizzydrink]

requirement class: 7-data-retrieval - zone-depth parameter

A suggestion to solving the default value issue with zone-depth parameter.

1. Following the OGC API Features - Part 3 approach to the filter-lang query parameter - where the parameter is formally defined in the OpenAPI Definition schema - with a default value specified by the implementer of the API. If the parameter is omitted then the schema defined default value is assumed.
2. Followed the example of the bbox parameter to define a parameter schema for zone-depth that caters for either:
   • A single depth value (e.g. zone-depth=5);
   • A continuous range of depth values (e.g. zone-depth=2-8); or,
   • A defined list of specific depth values (e.g. zone-depth=0,3,4,7,8).

Because in this suggested change we're defining a specific schema for the parameter (and there are now quite a number of requirements for the 'definition' and 'response' for that parameter) I've created a separate set of requirements for the zone-depth parameter and linked that to the data retrieval operation and response requirements rather than just having it all in the original requirement classes.

[ldesousa]

This is a brief summary of the discussion around this topic during the 125th OGC Member Meeting:

• A case can be made for the zone-depth parameter to be entirely optional, be it from the service side as well as from the client side. This in order to make the API as easy to use as possible.

• In case zone-depth is not specified in the request, the service should default to the native resolution. The goal is for the service to provide non-manipulated or transformed data by default.

• The service can define its own default for zone-depth in cases where large areas are served at high resolution. This seems to be already previewed.

• In abstract, the concept of "zone" is perceived as the area or extent of interest, i.e. the segment of the Earth's surface on which the user is interested. This contrasts with the concept of "zone" as tile. It is recognised that both concepts have their use cases.

• It would be preferable for zone-depth to be expressed with an absolute resolution, and not as a relative resolution. This should simplify things client side and render interaction more transparent. It should also make it easier server side. An obvious implication: zone-depth should then be greater or equal to the "zone" resolution. A zone-depth equal to the zone resolution returns a single (representative) value for the zone.

Please let me know if something needs more clarity.

[geofizzydrink]

This is a brief summary of the discussion around this topic during the 125th OGC Member Meeting:

• A case can be made for the zone-depth parameter to be entirely optional, be it from the service side as well as from the client side. This in order to make the API as easy to use as possible.
• In case zone-depth is not specified in the request, the service should default to the native resolution. The goal is for the service to provide non-manipulated or transformed data by default.
• The service can define its own default for zone-depth in cases where large areas are served at high resolution. This seems to be already previewed.
• In abstract, the concept of "zone" is perceived as the area or extent of interest, i.e. the segment of the Earth's surface on which the user is interested. This contrasts with the concept of "zone" as tile. It is recognised that both concepts have their use cases.
• It would be preferable for zone-depth to be expressed with an absolute resolution, and not as a relative resolution. This should simplify things client side and render interaction more transparent. It should also make it easier server side. An obvious implication: zone-depth should then be greater or equal to the "zone" resolution. A zone-depth equal to the zone resolution returns a single (representative) value for the zone.

Please let me know if something needs more clarity.

Thanks Luis.

[jerstlouis]

@ldesousa @geofizzydrink

Sorry for the late feedback, but chiming in on Luis's summary of the discussion at the MM.

• optional zone-depth parameter -- for sure I think it should be optional, which brings the topic of what should the default be.
• the service should default to the native resolution -- I disagree with this, because it is not practical with low-resolution / large extent zones, and it means always returning an error at a specific resource. We had a similar discussion for /coverage.
• The service can define its own default for zone-depth in cases where large areas are served at high resolution. -- I agree with this, but it seems to contradict the previous point.
• In abstract, the concept of "zone" is perceived as the area or extent of interest. -- Should this be understood as explicitly not implying a particular resolution of interest? My understanding is that there are use cases for both implying a particular resolution of interest for a zone level (e.g., the reasonable amount of data that can be retrieved for a particular zone level) and not doing so (e.g., compact-zones listing where bigger zones can be used when they fully cover an area to describe). So in this sense the resolution is not as strongly tied to the zone as in a TileMatrixSet, but the concept of implying a particular resolution for a given hierarchy level is still useful.
• It would be preferable for zone-depth to be expressed with an absolute resolution, and not as a relative resolution. -- I am of a (strong) opposite opinion. With a relative zone-depth, a value of 0 always means a single value is being retrieved, and all other relative values always means retrieving a specific number of values back and therefore allows the client to expect a particular payload size. Relative is the consistent with the size=243 parameter in the FMSDI experiments with the University of Calgary / PYXIS server which returned 243x243 values (zone-depth = 5 -- 3^5 for ISEA9R).
• zone-depth should then be greater or equal to the "zone" resolution. -- was the intent to say smaller or equal?

I did not review the state of the latest merged commit correspond to these discussion points, but I hope we can continue the discussion and review.