update Queryables to use JSON Schema

extensions/cql/standard/clause_6_filter.adoc

@@ -7,62 +7,73 @@ include::requirements/requirements_class_filter.adoc[]
 
 The <<OACommon-1,OGC API - Common>> standard defines two filtering operators at the `/items` endpoint: bbox and datetime.  <<OAFeat-1,OGC API - Features - Part 1: Core>> also adds support, beyond <<OACommon-1,OGC API - Common>> for simple equality predicates logically joined using the AND operator.  This capabilities offer simple  resource filtering for HTTP requests.
 
-This conformance class defines additional query parameters that allow more 
+This conformance class defines additional query parameters that allow more
 complex filtering expressions to be specified when querying server resources.
 
 Specifically, this clause defines the parameters, `filter`, `filter-lang` and
 `filter-crs`.
 
-This conformance class also defines resources for discovering the list of 
+This conformance class also defines resources for discovering the list of
 resource properties (and their types) that may be used to construct filter
 expressions.
 
 [[filter-queryables]]
 === Queryables
 
-This extension does not assume that the schema (internal or external) of a 
+This extension does not assume that the content schema of a
 resource being queried is available for inspection and thus a means needs
 to exist to interrogate an endpoint to determine the names and types of the
-properties or keys that may be used to construct a filter expression.
+properties or keys that may be used to construct a filter expression
+("queryables").
+
+In addition, a publisher may want to support queryables that are not
+directly represented as resource properties in the content schema of the
+resource. Or the publisher may want to restrict filtering on certain
+properties, e.g., because the backend datastore has not been configured
+to allow performant queries on those properties.
 
 include::requirements/filter/REQ_get-queryables-op-global.adoc[]
 
 include::requirements/filter/REQ_get-queryables-op-local.adoc[]
 
 include::requirements/filter/REQ_get-queryables-response.adoc[]
 
+To support clients, it is recommended to provide additional detail
+about the meaning of the property and the possible values:
+
+include::recomendations/filter/REC_queryables-schema.adoc[]
+
 [[example_1]]
 .Queryables example
 ====
 [source,JSON]
 ----
 {
-   "queryables": [
-      {
-         "queryable": "elevation",
-         "title": "Elevation",
-         "description": "The average distance of the road segment above sea level.",
-         "type": "double"
-      },
-      {
-         "queryable": "nlanes",
-         "title": "Temperature",
-         "description": "The total number of lanes in all directions.",
-         "type": "integer"
-      },
-      {
-         "queryable": "geom",
-         "title": "Segment Geometry",
-         "description": "The geometry of the road segment",
-         "type": "linestring"
-      },
-      {
-         "queryable": "name",
-         "title": "Segment Name",
-         "description": "The common name of the road segment.",
-         "type": "string"
-      }
-   ]
+  "$schema" : "http://json-schema.org/draft-07/schema#",
+  "$id" : "https://demo.ldproxy.net/daraa/collections/CulturePnt/queryables",
+  "type" : "object",
+  "title" : "Cultural (Points)",
+  "description" : "Cultural: Information about features on the landscape with a point geometry that have been constructed by man.",
+  "properties" : {
+    "F_CODE" : {
+      "title" : "Feature Type",
+      "type" : "string",
+      "enum" : [ "AK121", "AL012", "AL030", "AL130", "BH075" ]
+    },
+    "ZI001_SDV" : {
+      "title" : "Last Change",
+      "type" : "string",
+      "format" : "date-time"
+    },
+    "ZI037_REL" : {
+      "title" : "Religious Designation",
+      "type" : "integer",
+      "enum" : [ -999999, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 ]
+    },
+    "geometry" : {
+      "$ref" : "https://geojson.org/schema/Point.json"
+    }
+  }
 }
 ----
 ====
@@ -86,7 +97,7 @@ potentially operate on multiple collections.  The simplest approach for handling
 such cross-collection queries is one that is consistent with one-collection
 queries.  Specifically, any specified `filter` parameter should apply to all
 referenced collections.  This, of course, implies that all properties referenced
-in the filter expression are valid for all referenced collections and should be 
+in the filter expression are valid for all referenced collections and should be
 taken from  the <<filter-queryables,global queryables list>>.
 
 include::requirements/filter/REQ_filter-param-multiple-collections.adoc[]
@@ -105,18 +116,18 @@ NOTE: Arrays of filter expressions that operate on each collection specified in
 [[filter-lang-param]]
 === Parameter filter-lang
 
-Any predicate language that can be suitably expressed as the value of an 
+Any predicate language that can be suitably expressed as the value of an
 HTTP query parameter may be specified as the value of the `filter` parameter.
 In order to specify that specific language that is being used, this clause
 defines the `filter-lang` parameter.
 
 include::requirements/filter/REQ_filter-lang-param.adoc[]
 
-The enumerated value `cql-text` is used to indicate that the value of the 
-<<filter-param,`filter`>> parameter is the <<simple-cql-text,text encoding of CQL>>.  
+The enumerated value `cql-text` is used to indicate that the value of the
+<<filter-param,`filter`>> parameter is the <<simple-cql-text,text encoding of CQL>>.
 
 The enumerated value `cql-json` is used to indicate that the value of the
-<<filter-param,`filter`>> parameter is the <<simple-cql-JSON,JSON encoding of CQL>>.  
+<<filter-param,`filter`>> parameter is the <<simple-cql-JSON,JSON encoding of CQL>>.
 
 Servers that support other filtering languages can extend this list of values
 as necessary although the meaning of any additional values are not described
@@ -136,9 +147,9 @@ include::requirements/filter/REQ_mixing-expressions.adoc[]
 === Filter expression language
 
 This extension does not mandate that a specific filter expression language be
-used as the value of the <<filter-param,filter parameter>>.  However, this 
+used as the value of the <<filter-param,filter parameter>>.  However, this
 extension defines a filter expression language called the `Common Query
-Language` (CQL).  A <<cql-core,simple CQL core>> is defined along with a 
+Language` (CQL).  A <<cql-core,simple CQL core>> is defined along with a
 number of <<cql-enhancements,enhancements>> that add additional, more advanced
 capabilities to the language.  Two encodings, a <<simple-cql-text,text
 encoding>> and a <<simple-cql-json,JSON>> encoding are also defined and
@@ -148,5 +159,3 @@ recommended if they are suitable for their intended use.
 === Response
 
 include::requirements/filter/REQ_response.adoc[]
-
-

extensions/cql/standard/recommendations/filter/REC_queryables-schema.adoc

@@ -0,0 +1,21 @@
+[[rec_filter_queryables-schema]]
+[width="90%",cols="2,6a"]
+|===
+^|*Recommendation {counter:rec-id}* |*/rec/filter/queryables-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`).
+^|C |For string properties `minLength`, `maxLength`, `enum` and/or `pattern`
+SHOULD be provided, where applicable.
+^|D |For numeric properties `multipleOf`, `minimum`, `exclusiveMinimum`,
+`maximum`, `exclusiveMaximum` SHOULD be provided, where applicable.
+^|E |For integer properties that represent enumerated values, `enum` SHOULD
+be provided.
+^|F |For temporal properties that are a `string` literal, the appropriate
+format `date-time`, `date`, `time`, or `duration` SHOULD be provided.
+^|G |For spatial properties, the property SHOULD reference a well-known
+JSON schema of the geometry object. For geometry types according to the
+Simple Features standard the JSON Schema of the GeoJSON geometry object
+SHOULD be referenced; for example, `https://geojson.org/schema/Point.json`
+for a point geometry.
+|===

extensions/cql/standard/requirements/filter/REQ_get-queryables-op-global.adoc

@@ -2,7 +2,8 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/filter/get-queryables-op-global*
-^|A |A server that implements this conformance class shall support the HTTP GET operation at the '/queryables' path.
-^|B |The queryables accessed at this path shall be valid for all collections identified in the collections response (path `/collections`).
+^|A |A server that implements this conformance class shall support the HTTP GET operation at the path `/queryables` and the media type `application/schema+json`.
+^|B |The queryables accessed at this path shall be valid for all collections identified in the Collections resource (path `/collections`).
+^|C |The Queryable resource SHALL be referenced from the Landing Page resource
+with a link with the link relation type `http://www.opengis.net/def/rel/ogc/1.0/queryables`.
 |===
-

extensions/cql/standard/requirements/filter/REQ_get-queryables-op-local.adoc

@@ -1,8 +1,11 @@
 [[req_filter_get-queryables-op-local]]
 [width="90%",cols="2,6a"]
 |===
-^|*Requirement {counter:req-id}* |*/req/filter/get-queryables-op-local* 
-^|A |For every collection identified in the collections response (path
- `/collections`), the server SHALL support the HTTP GET operation at the path `/collections/{collectionId}/queryables`.
+^|*Requirement {counter:req-id}* |*/req/filter/get-queryables-op-local*
+^|A |For every collection identified in the Collections resource (path
+ `/collections`), the server SHALL support the HTTP GET operation at the path
+ `/collections/{collectionId}/queryables` and the media type `application/schema+json`.
 ^|B |The parameter `collectionId` is each `id` property in the collections response (JSONPath: `$.collections[*].id`).
+^|C |The Queryable 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/queryables`.
 |===

extensions/cql/standard/requirements/filter/REQ_get-queryables-response.adoc

@@ -2,44 +2,13 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/filter/get-queryables-response*
-^|A |A successful execution of the operation SHALL be reported as a response wit
-h a HTTP status code `200`.
-^|B |The content of the response shall have the following characteristics (using an OpenAPI Specification 3.0 fragment):
+^|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:
 
-[source,YAML]
-----
-type: object
-required:
-  - queryables
-properties:
-  queryables:
-    type: array
-    items:
-      type: object
-      required:
-      - queryable
-      - type
-      properties:
-         queryable:
-            description: the token that may be used in a CQL predicate
-            type: string
-         title:
-            description: a human readble title for the queryable
-            type: string
-         description:
-         description: a human-readable narrative describing the queryable
-            type: string
-         language:
-            description: the language used for the title and description
-            type: string
-            default:
-               - en
-         type:
-            description: the data type of the queryable
-            type: string
-         type-ref:
-            description: a reference to the formal definition of the type
-            type: string
-            format: url
-----
+* 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 queryable.
 |===