Merge pull request #124 from opengeospatial/issue-106

update sortables

.gitignore

@@ -1,2 +1,3 @@
 core/*.html
 core/*.pdf
+.DS_Store

core/examples/json/sortables.json

@@ -1,20 +1,23 @@
-[
-   {
-      "id": "id",
-      "title": "Record Identifier",
-      "description": "A unique record identifier assigned by the server.",
-      "language": "en"
-   },
-   {
-      "id": "updated",
-      "title": "Updated",
-      "description": "The more recent date on which the resource was changed.",
-      "language": "en"
-   },
-   {
-      "id": "extent",
-      "title": "Spatio-Temporal Extent",
-      "description": "The spatio-temporal coverage of the resource.",
-      "language": "en"
+{
+   "$schema": "https://json-schema.org/draft/2019-09/schema",
+   "$id": "https://data.example.com/collections/abc/sortables",
+   "type": "object",
+   "properties": {
+      "id": {
+         "title": "Record Identifier",
+         "description": "A unique record identifier assigned by the server.",
+         "type": "string"
+      },
+      "updated": {
+         "title": "Updated",
+         "description": "The more recent date on which the resource was changed.",
+         "type": "string",
+         "format": "date"
+      },
+      "extent": {
+         "title": "Spatio-Temporal Extent",
+         "description": "The spatio-temporal coverage of the resource.",
+         "type": "object"
+      }   
    }
-]
+ }

core/openapi/responses/Sortables.yaml

@@ -1,8 +1,5 @@
 type: object
-required:
-  - sortables
-properties:
-  sortables:
-    type: array
-    items:
-      $ref: ../schemas/sortable.yaml
+title: Sortables
+description: Describes the properties that can be used to sort the results
+additionalProperties:
+  $ref: 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v3.0/schema.json#/definitions/Schema'

core/standard/clause_9_sorting.adoc

@@ -18,24 +18,27 @@ handling missing values; specifying a high value indicating that the correspondi
 
 include::requirements/sorting/REQ_sortby-response.adoc[]
 
-include::requirements/sorting/REQ_sortables-op.adoc[]
+include::requirements/sorting/REQ_get-sortables-op.adoc[]
 
-include::requirements/sorting/REQ_sortables-success.adoc[]
+include::requirements/sorting/REQ_get-sortables-success.adoc[]
+
+The response is returned as a JSON Schema document that describes a single JSON object where each property is a sortable. Note that the sortables schema does not specify a schema of any object that can be retrieved from the API. JSON Schema is used for the sortables to have a consistent approach for describing schema information and JSON Schema is/will be used in other parts of OGC API Features to describe schemas for GeoJSON feature content including in OpenAPI documents.
+
+NOTE: The OGC Features API Standards Working Group has a schema harmonization task that could lead to a future OGC API standard that will deprecate the approach for the sortables resource specified in this document.
+
+To support clients, providing additional detail about the meaning of the sortables is recommended:
+
+include::recommendations/sorting/REC_sortables-schema.adoc[]
+
+In an OpenAPI 3.0 document, the Sortables resources has the following schema:
 
 [[schema_sortables]]
-.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/responses/Sortables.yaml[Schema for the list of sortables (Sortables.yaml)]
+.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/responses/Sortables.yaml[Schema for the list of sortable properties (Sortables.yaml)]
 [source,YAML]
 ----
 include::../openapi/responses/Sortables.yaml[]
 ----
 
-[[schema_sortable]]
-.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/sortable.yaml[Schema for a sortable description(sortable.yaml)]
-[source,YAML]
-----
-include::../openapi/schemas/sortable.yaml[]
-----
-
 === Examples
 
 [#sortables-example,reftext=`Sortables Example`]

core/standard/recommendations/sorting/REC_sortables-schema.adoc

@@ -0,0 +1,8 @@
+[[rec_sorting_sortables-schema]]
+[width="90%",cols="2,6a"]
+|===
+^|*Recommendation {counter:rec-id}* |*/rec/sorting/sortables-schema*
+^|A |Each property SHOULD have a human readable title (`title`) and where
+necessary a description (`description`).
+^|B |Each property SHOULD have a single type (`type`).
+|===

core/standard/requirements/sorting/REQ_get-sortables-op.adoc

@@ -0,0 +1,11 @@
+[[req_sorting_get-sortables-op]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/sorting/get-sortables-op*
+^|A |For every collection identified in the Collections resource (path
+ `/collections`), the server SHALL support the HTTP GET operation at the path
+ `/collections/{collectionId}/sortables` and the media type `application/schema+json`.
+^|B |The parameter `collectionId` is each `id` property in the collections response (JSONPath: `$.collections[*].id`).
+^|C |The Sortables resource SHALL be referenced from the Collection resource
+with a link with the link relation type `\http://www.opengis.net/def/rel/ogc/1.0/sortables`.
+|===

core/standard/requirements/sorting/REQ_get-sortables-success.adoc

@@ -0,0 +1,14 @@
+[[req_sorting_get-sortables-success]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/sorting/get-sortables-success*
+^|A |A successful execution of the operation SHALL be reported as a response
+with a HTTP status code `200`.
+^|B |For responses that use `application/schema+json` as the `Content-Type` of
+the response, the response SHALL have the following characteristics:
+
+* The property `$schema` is `\http://json-schema.org/draft-07/schema#` or
+`\https://json-schema.org/draft/2019-09/schema`.
+* The property `$id` is the URI of the resource without query parameters.
+* The `type` is `object` and each property is a sortable.
+|===