Skip to content

Commit

Permalink
Modularized Part 2
Browse files Browse the repository at this point in the history 
Created a simple query conformance class which contains all of the requirements related to the three defined query parameters. This conformance class, in turn, could be converted into registry content (the parameter definitions) and resource specific content.
  • Loading branch information
@cmheazel
cmheazel committed Jul 9, 2021
1 parent 2f8189a commit 584f25a
Show file tree
Hide file tree
Showing 32 changed files with 297 additions and 283 deletions.
10 changes: 6 additions & 4 deletions collections/OAPI_Common-Geospatial-Data.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
|[big]*Open Geospatial Consortium*
|Submission Date: <yyyy-mm-dd>
|Approval Date:   <yyyy-mm-dd>
|Publication Date:   2021-06-20
|Publication Date:   2021-07-09
|External identifier of this OGC(R) document: http://www.opengis.net/doc/IS/ogcapi-common-2/1.0
|Internal reference number of this OGC(R) document:    20-024
|Version: 0.0.1
Expand Down Expand Up @@ -91,11 +91,13 @@ include::clause_7_overview.adoc[]

include::clause_8_collections.adoc[]

include::clause_9_encodings.adoc[]
include::clause_9_simple_query.adoc[]

include::clause_10_media_types.adoc[]
include::clause_10_encodings.adoc[]

include::clause_11_security_considerations.adoc[]
include::clause_11_media_types.adoc[]

include::clause_12_security_considerations.adoc[]

include::annex_ats.adoc[]

Expand Down
0 collections/clause_9_encodings.adoc → collections/clause_10_encodings.adoc
View file
File renamed without changes.
0 collections/clause_10_media_types.adoc → collections/clause_11_media_types.adoc
View file
File renamed without changes.
0 ...ns/clause_11_security_considerations.adoc → ...ns/clause_12_security_considerations.adoc
View file
File renamed without changes.
165 changes: 3 additions & 162 deletions collections/clause_8_collections.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[[rc_collections-section]]
[[rc-collections-section]]
== Requirements Class "Collections"
:sectnums:

Expand Down Expand Up @@ -49,14 +49,6 @@ OGC APIs typically organize their Spatial Resources into collections. Informatio

include::requirements/collections/REQ_rc-md-op.adoc[]

===== Parameters

The following query parameters can be used with this operation:

* <<bbox-parameter-requirements,Bounding Box>>: Limits the contents of the `collections` response to those collections whose spatial extent intersects the bounding box specified by the Bounding Box parameter.
* <<datetime-parameter-requirements,Date Time>> Limits the contents of the `collections` response to those collections whose temporal extent intersects the instance or period specified by the Date Time parameter.
* <<limit-parameter-requirements,Limit>>: Limits the contents of the `collections` response to the number of items specified by the Limit parameter.

===== Response

include::requirements/collections/REQ_rc-md-success.adoc[]
Expand Down Expand Up @@ -85,38 +77,18 @@ The `collections` property of the Collections response provides a description of

include::requirements/collections/REQ_rc-md-items.adoc[]

A client may select a subset of the hosted collections using the <<bbox-parameter-requirements,`bbox`>> and the <<datetime-parameter-requirements,`datetime`>> parameter. These parameters are evaluated against the `extent` element of each Collection item in the Collections response.
A client may wish to select a subset of the hosted collections using HTTP query parameters. The <<rc-simple-query-section,Simple Query>> Conformance Class defines the <<bbox-parameter-requirements,`bbox`>> and the <<datetime-parameter-requirements,`datetime`>> parameter for that purpose. It also defines how a server should process those parameters. These parameters are evaluated against the `extent` element of each Collection item in the Collections response.

The requirements governing the processing of these parameters are:

include::requirements/collections/REQ_rc-bbox-collections-unsupported.adoc[]

include::requirements/collections/REQ_rc-bbox-collections-response.adoc[]

include::requirements/collections/REQ_rc-time-collections-unsupported.adoc[]

include::requirements/collections/REQ_rc-time-collections-response.adoc[]

The number of collections returned in a response may be further limited by the client using the `limit` parameter. When applied against the `/collections` resource, the <<limit-parameter-requirements,`limit`>> parameter indicates the maximum number of collections which should be included in a single response.
The <<rc-simple-query-section,Simple Query>> Conformance Class also defines a parameter to limit the number of collections returned in a response. This <<limit-parameter-requirements,`limit`>> parameter indicates the maximum number of collections which should be included in a single response.

include::requirements/collections/REQ_rc-limit-collections-unsupported.adoc[]

include::requirements/collections/REQ_rc-limit-collections-response.adoc[]

The `numberMatched` property of the Collections response indicates the number of Collection items included in the Collections response. This may be a subset of the total set of collections hosted by the API. Selection of which collections to include in a subset is controled through the <<bbox-parameter-requirements,`bbox`>>, <<datetime-parameter-requirements,`datetime`>> and other selection parameters provided by the client.

include::requirements/collections/REQ_rc-numberMatched.adoc[]

The Collections response should describe all of the collections that meet the client's selection criteria. However, in some cases that is impractical. An API implementation has the option of limiting the size of the Collections response.

include::recommendations/collections/PER_rc-md-items.adoc[]

The number of collection items included in a Collections response may be a subset of the number matched. In that case, the `numberReturned` property of the Collections response indicates the number of collection items returned in this "page" of the Collections response.

include::requirements/collections/REQ_rc-numberReturned.adoc[]

If the Collections response contains a subset of the selected collection items (numberReturned is less than numberMatched) then the Collections response should contain links for navigating to the rest of the collection items as described in the <<limit-parameter-requirements,limit parameter>> section.

===== Error situations

See <<http-status-codes>> for general guidance.
Expand All @@ -130,10 +102,6 @@ Each resource collection is described by a set of metadata. That metadata is acc

include::requirements/collections/REQ_src-md-op.adoc[]

===== Parameters

No parameters have been standardized for this operation.

===== Response

include::requirements/collections/REQ_src-md-success.adoc[]
Expand Down Expand Up @@ -187,131 +155,4 @@ See <<http-status-codes>> for general guidance.

If the parameter `collectionId` does not exist on the server, the status code of the response will be `404` (see <<status-codes>>).

[[parameter-requirements]]
=== Parameter Requirements

Query parameters are used in URLs to limit the resources which are returned on a GET request. The OGC API - Common - Part 2: Geospatial Data Standard defines three query parameters for use in OGC API standards:

* <<bbox-parameter-requirements,bbox>>: Bounding Box
* <<parameter-datetime-requirements,datetime>>: Date and Time
* <<limit-parameter-requirements,limit>>: Response resource count limit

The behavior generated by these parameters is specific to the operation and resource upon which they are applied. Those behaviors are described for each resource type and operation in the <<collection-resource-requirements,Resource Requirements>> section.

Use of these query parameters with any specific operation is optional. Developers of API-GeoData servers should document their supported parameters in the API definition as describe in <<apicore,API-Core>>.

[[bbox-parameter-requirements]]
==== Parameter bbox

The `bbox` parameter is defined as follows:

include::requirements/collections/REQ_rc-bbox-definition.adoc[]

While the processing of the `bbox` parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.

include::requirements/collections/REQ_rc-bbox-response.adoc[]

"Intersects" means that a coordinate that is part of the spatial geometry of the resource falls within the area specified in the parameter `bbox`. This includes the boundaries of the geometries. For curves the boundary includes the start and end position. For surfaces the boundary includes the outer and inner rings.

In case of a degenerate bounding box, the resulting geometry is used. For example, if the lower left corner is the same as the upper right corner, all resources match where the geometry intersects with this point.

This standard does not specify requirements for the parameter `bbox-crs`. Those requirements will be specified in a later version of this standard.

For WGS 84 longitude/latitude the bounding box is in most cases the sequence of minimum longitude, minimum latitude, maximum longitude and maximum latitude. However, in cases where the box spans the anti-meridian (180th meridian) the first value (west-most box edge) is larger than the third value (east-most box edge).

.The bounding box of the New Zealand Exclusive Economic Zone
=================
The bounding box of the New Zealand Exclusive Economic Zone in WGS84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON as `[ 160.6, -55.95, -170, -25.89 ]` and in a query as `bbox=160.6,-55.95,-170,-25.89`.
=================

Note that the server will return an error if a latitude value of ``160.0`` is used.

If the vertical axis is included, the third and the sixth number are the bottom and the top of the 3-dimensional bounding box.

A template for the definition of the parameter in YAML according to OpenAPI 3.0 is available at link:http://schemas.opengis.net/ogcapi/common/part2/1.0/parameters/bbox.yaml[bbox.yaml].

[[datetime-parameter-requirements]]
==== Parameter datetime

The `datetime` parameter is defined as follows:

include::requirements/collections/REQ_rc-time-definition.adoc[]

While the processing of the `datetime` parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.

include::requirements/collections/REQ_rc-time-response.adoc[]

"Intersects" means that the time (instant or period) specified in the parameter `datetime` includes a timestamp that is part of the temporal geometry of the resource (again, a time instant or period). For time periods this includes the start and end time.

[width="90%",cols="2,6a"]
|====
| Note | ISO 8601-2 distinguishes open start/end timestamps (double-dot) and unknown start/end timestamps (empty string). For queries, an unknown start/end has the same effect as an open start/end.
|====

.A date-time
=================
February 12, 2018, 23:20:52 GMT:
`time=2018-02-12T23%3A20%3A52Z`
=================

For resources with a temporal property that is a timestamp (like `lastUpdate`), a date-time value would match all resources where the temporal property is identical.

For resources with a temporal property that is a date or a time interval, a date-time value would match all resources where the timestamp is on that day or within the time interval.

.Intervals
=================
February 12, 2018, 00:00:00 GMT to March 18, 2018, 12:31:12 GMT:
`datetime=2018-02-12T00%3A00%3A00Z%2F2018-03-18T12%3A31%3A12Z`
February 12, 2018, 00:00:00 UTC or later:
`datetime=2018-02-12T00%3A00%3A00Z%2F..`
March 18, 2018, 12:31:12 UTC or earlier:
`datetime=..%2F2018-03-18T12%3A31%3A12Z`
=================

A template for the definition of the parameter in YAML according to OpenAPI 3.0 is available at link:http://schemas.opengis.net/ogcapi/common/part2/1.0/parameters/datetime.yaml[datetime.yaml].

[[limit-parameter-requirements]]
==== Parameter limit

The `limit` parameter limits the number of resources that can be returned in a single response.

include::requirements/collections/REQ_rc-limit-definition.adoc[]

While the processing of the `limit` parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.

include::requirements/collections/REQ_rc-limit-response.adoc[]

The number of resources returned depends on the server and the value of the `limit` parameter.

* The client can request a limit to the number of resources returned.
* The server may have a default value for the limit, and a maximum limit.
* If the server has any more results available than it returns (the number it returns is less than or equal to the requested/default/maximum limit) then the server will include a link to the next set of results.

include::recommendations/collections/PER_rc-server-limit.adoc[]

include::recommendations/collections/REC_rc-server-limit.adoc[]

The effect of the limit parameter is to divide the response into a number of pages. Each page (except for the last) contains the specified number of entities. The response contains the first page. Additional pages can be accessed through hyperlink navigation.

include::recommendations/collections/REC_rc-next-1.adoc[]

include::recommendations/collections/REC_rc-next-2.adoc[]

include::recommendations/collections/REC_rc-next-3.adoc[]

Providing `prev` links supports navigating back and forth between pages, but depending on the implementation approach it may be too complex to implement.

include::recommendations/collections/PER_rc-prev.adoc[]

[[general-requirements]]
=== General Requirements

The following general requirements and recommendations apply to all OGC APIs which implement the API-Common Geospatial Data Standard.

include::../general/clause_8_general.adoc[]
Loading

0 comments on commit 584f25a

Please sign in to comment.