Merge pull request #220 from philvarner/clarify-limit-min-and-max

clarify semantics of the limit parameter

Author: philvarner

CHANGELOG.md

@@ -5,6 +5,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [v1.0.0-beta5 - Unreleased] - TBD
+
+### Added
+
+### Changed
+
+- Limit parameter semantics now match OAFeat. Previously, the behavior was not precisely defined.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
 ## [v1.0.0-beta4] - 2020-10-05
 
 ### Added

item-search/README.md

@@ -115,7 +115,7 @@ The core parameters for STAC search are defined by OAFeat, and STAC adds a few p
 
 | Parameter   | Type             | Source API | Description                                                                                                                                                                     |
 | ----------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| limit       | integer          | OAFeat     | The maximum number of results to return (page size). Defaults to 10                                                                                                             |
+| limit       | integer          | OAFeat     | The maximum number of results to return (page size).                                                                                                            |
 | bbox        | \[number]        | OAFeat     | Requested bounding box.                                                                                                                                                         |
 | datetime    | string           | OAFeat     | Single date+time, or a range ('/' separator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Use double dots `..` for open date ranges. |
 | intersects  | GeoJSON Geometry | STAC       | Searches items by performing intersection between their geometry and provided GeoJSON geometry.  All GeoJSON geometry types must be supported.                                  |
@@ -124,6 +124,14 @@ The core parameters for STAC search are defined by OAFeat, and STAC adds a few p
 
 See [examples](examples.md) for some example requests.
 
+**limit** The limit parameter follows the same semantics of the OAFeat Item resource limit parameter. The value is 
+a suggestion to the server as to the maximum number of Item objects the
+client would prefer in the response. The OpenAPI specification defines the default and maximum values
+for this parameter. The base specifications define these with a default of 10 and a maximum of 10000, but implementers
+may choose other values to advertise through their `service-desc` endpoint.  If the limit parameter value is greater
+than the advertised maximum limit, the server shall return the maximum possible number of items (ideally, the number 
+as the advertised maximum limit), rather than responding with an error.
+
 Only one of either **intersects** or **bbox** may be specified.  If both are specified, a 400 Bad Request response 
 must be returned. 
 

item-search/openapi.yaml

@@ -190,8 +190,8 @@ components:
       name: limit
       in: query
       description: |-
-        The optional limit parameter limits the number of items that are presented in the response document.
-
+        The optional limit parameter recommends the number of items that should be present in the response document.
+        
         Only items are counted that are on the first level of the collection in the response document.
         Nested objects contained within the explicitly requested items shall not be counted.
 
@@ -232,7 +232,16 @@ components:
       example: 10
       default: 10
       maximum: 10000
-      description: The maximum number of results to return (page size). Defaults to 10
+      description: |-
+        The optional limit parameter limits the number of items that are presented in the response document.
+
+        If the limit parameter value is greater than advertised limit maximum, the server shall return the
+        maximum possible number of items, rather than responding with an error.
+
+        Only items are counted that are on the first level of the collection in the response document.
+        Nested objects contained within the explicitly requested items shall not be counted.
+
+        Minimum = 1. Maximum = 10000. Default = 10.
     bboxFilter:
       type: object
       description: Only return items that intersect the provided bounding box.

ogcapi-features/openapi.yaml

@@ -254,7 +254,10 @@ components:
       name: limit
       in: query
       description: |-
-        The optional limit parameter limits the number of items that are presented in the response document.
+        The optional limit parameter recommends the number of items that should be present in the response document.
+
+        If the limit parameter value is greater than advertised limit maximum, the server shall return the
+        maximum possible number of items, rather than responding with an error.
 
         Only items are counted that are on the first level of the collection in the response document.
         Nested objects contained within the explicitly requested items shall not be counted.