Sort Extension: simple format for GET

CHANGELOG.md

@@ -61,6 +61,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
     - moved label:overview to be a list of Overview Objects from a single Overview Object in spec markdown and json schema (matching previous example JSON).
     - Renamed fields to use plural forms (`label:property` -> `label:properties`, `label:task` -> `label:tasks`, `label:method` -> `label:methods` and `label:overview` -> `label:overviews`)
 
+- Moved Single Item Extension to core (`license` and `providers` properties for Items)
+- Sort Extension - added non-JSON query/form parameter format 
 
 ## [v0.7.0] - 2019-05-06
 

api-spec/extensions/sort/README.md

@@ -2,7 +2,29 @@
 
 **Extension [Maturity Classification](../../../extensions/README.md#extension-maturity): Pilot**
 
-The STAC search endpoint, `/stac/search`, by default returns results in descending order using the datetime property. The sort API extension adds a new parameter, `sort` that allows the user to define fields to sort results by. Only properties may be used to sort results. The syntax for the `sort` parameter is:
+By default, the STAC search endpoint `/stac/search` returns results in no specified order.  Whatever order the results are in is up to the implementor, and will typically default to an arbitrary that is fastest for the underlying data store to retrieve results.
+
+ The Sort API Extension adds a new field, `sort`, that allows the user to define fields by which to sort results. Only string, numeric, and datetime attributes of Item (`id` and `collection` only) or Item Properties (any attributes) may be used to sort results.  It is not required that implementations support sorting over all attributes, but implementations should return an error when attempting to sort over a field that does not support sorting. 
+
+Two values for direction are supported: "asc" (ascending) or "desc" (descending). If the direction is not specified, the value is ascending. The `sort` value is an array, so multiple sort fields can be defined which will be used to sort the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`).
+
+## GET or POST Form
+
+When calling `/stac/search` using GET or POST with `Content-Type: application/x-www-form-urlencoded` or `Content-Type: multipart/form-data`, the semantics are the same, except the syntax is a single parameter `sort` with a comma-separated list of "<name>|<direction>" definitions.  The sort order must be specified.
+
+Examples of `sort` parameter:
+
+    GET /stac/search?sort=created|asc,id|desc
+
+    GET /stac/search?sort=eo:cloud_cover|desc
+
+    GET /stac/search?sort=created
+
+# POST JSON Entity
+
+When calling `/stac/search` using POST with`Content-Type: application/json`, this extension adds an attribute `sort` with an object value to the core JSON search request body.  If no direction is specified, the default is ascending.
+
+The syntax for the `sort` attribute is:
 
 ```json
 {
@@ -15,4 +37,21 @@ The STAC search endpoint, `/stac/search`, by default returns results in descendi
 }
 ```
 
-where <direction> is either "asc" (ascending) or "desc" (descending). The `sort` value is an array, so multiple sort fields can be defined which will be used to sort the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`).
+```json
+{
+    "sort": [
+        {
+            "field": "created",
+            "direction": "asc"
+        },
+        {
+            "field": "id",
+            "direction": "desc"
+        },
+        {
+            "field": "collection"
+        }
+    ]
+}
+```
+