Merge pull request #3 from opengeospatial/master

Sync from master.

.gitignore

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

README.md

@@ -20,7 +20,6 @@ The _**Record**_ is the atomic unit of information in a catalogue.  The record b
 
 The following is an example of a catalogue record encoded as GeoJSON:
 
-[source,JSON]
 ```
     {
       "id": "urn:uuid:dc9b6d52-932a-11ea-ad6f-823cf448c401",
@@ -76,7 +75,7 @@ The following is an example of a catalogue record encoded as GeoJSON:
 ```
 ## The Record collection building block
 
-A catalogue is a collection of records.  The `Record collection` building block extends the information defined for a collection by http://docs.opengeospatial.org/DRAFTS/20-024.html#collection-description(OGC API - Common - Part 2: Geospatial Data) and http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml(OGC API - Features - Part 1: Core) to:
+A catalogue is a collection of records.  The `Record collection` building block extends the information defined for a collection by [OGC API - Common - Part 2: Geospatial Data](http://docs.opengeospatial.org/DRAFTS/20-024.html#collection-description) and [OGC API - Features - Part 1: Core](http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml) to:
 
 * include additional metadata for describing a catalogue (i.e. collection of records)
 * and to provide links for accessing the records of the collection

core/examples/json/queryables.json

@@ -5,7 +5,7 @@
             "type": "string"
         },
         {
-            "queryable": "externalid",
+            "queryable": "externalId",
             "type": "string"
         },
         {

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/examples/yaml/ogcapi-record-1-example1.yaml

@@ -143,7 +143,7 @@ paths:
         - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/limit'
         - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/q'
         - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/type'
-        - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/externalid'
+        - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/externalId'
         - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1.yaml#/components/parameters/sortby'
       responses:
         '200':

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/annex_common.adoc

@@ -269,7 +269,9 @@ The requirements for handling unsuccessful requests are provided in <<http-respo
 The primary unit of information in a catalogue is a record. Tables <<core-queryables-record-table>> and <<core-queryables-resource-table>> in this clause present a generic set of properties, called _**core queryables**_, that may be included in a catalogue record.  The choice of which properties to include in the set of core queryables was primarily informed by the following record models:
 
 * The https://docs.ogc.org/is/12-168r6/12-168r6.html#17[core catalogue schema] from the https://www.ogc.org/standards/cat[OGC® Catalogue Services 3.0] suite of standards,
-* the https://www.w3.org/TR/vocab-dcat/[Data Catalog Vocabular (DCAT) - Version 2] specification.
+
+* the https://www.w3.org/TR/vocab-dcat/[Data Catalog Vocabulary (DCAT) - Version 2] specification.
+
 * and the https://www.unece.org/fileadmin/DAM/stats/documents/ece/ces/ge.58/2017/mtg3/2017-UNECE-topic-i-EC-GeoDCAT-ap-paper.pdf[GeoDCAT-AP] specification.
 
 It is expected that the information necessary to populate the core queryables is readily available for any resource that is being registered in the catalogue.  

core/standard/clause_10_record-filter.adoc

@@ -1,4 +1,4 @@
-[[clause-record-filter]]
+[[clause-cql-filter]]
 == Requirements Class "Filtering using the Common Query Language (CQL)"
 
 [[record-filter-overview]]

core/standard/clause_2_conformance.adoc

@@ -23,7 +23,9 @@ The Requirements Classes for OGC API - Records are:
 * <<requirements-class-atom-clause,ATOM-Record>>
 * <<requirements-class-html-clause,HTML-Record>>
 
-The <<clause-static-catalogue,Static Catalogue>> conformance class defines the core requirements for a static catalogue.  The <<clause-record-core,Record>>, <<clause-record-collection,Record collection>> are mandatory requirements classes that must be implemented for this conformance class.
+The <<clause-static-catalogue,Static Catalogue>> conformance class defines the core requirements for a static catalogue.
+
+The <<clause-record-core,Record>>, <<clause-record-collection,Record collection>> are mandatory requirements classes that must be implemented for this conformance class.
 
 The <<clause-searchable-catalogue,Searchable Catalogue>> conformance class defines the core requirements for a searchable catalogue.  The <<clause-record-core,Record>>, <<clause-record-collection,Record collection>> and <<clause-core-api,Record API>> requirements are mandatory requirements classes that must be implemented for this conformance class.
 

core/standard/clause_3_references.adoc

@@ -12,6 +12,8 @@ The following normative documents contain provisions that, through reference in
 * [[rfc8288]] Nottingham, M.: IETF RFC 8288, *Web Linking*, https://tools.ietf.org/rfc/rfc8288.txt[RFC 8288]
 
 * [[OAPI_Common]] OGC 19-072: *OGC API (OAPI) Common Specification*, (Draft) https://github.com/opengeospatial/oapi_common[API Common]
+* [[OAFeat-1]] OGC 17-069r3: *OGC API - Features - Part 1: Core*, http://docs.opengeospatial.org/is/17-069r3/17-069r3.html 
+* [[OAFeat-3]] OGC 19-079: *OGC API - Features - Part 3: Filtering and the Common Query Language (CQL)*, https://docs.ogc.org/DRAFTS/19-079.html
 * [[OpenAPI]] Open API Initiative: *OpenAPI Specification 3.0.2*, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md[OpenAPI]
 * [[schema.org]] *Schema.org*: https://schema.org/docs/schemas.html[Schema.org]
 * [[HTML5]] W3C: *HTML5*, W3C Recommendation, https://www.w3.org/TR/html5/[HTML5]
@@ -32,4 +34,3 @@ The following normative documents contain provisions that, through reference in
 * W3C: W3C JSON-LD 1.0, A JSON-based Serialization for Linked Data. https://www.w3.org/TR/json-ld/, 2014
 * W3C: W3C JSON-LD 1.0 Processing Algorithms and API. https://www.w3.org/TR/json-ld-api, 2014
 * W3C: W3C RDF 1.1 Concepts and Abstract Syntax. https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/, 2014
-* [[OAFeat-3]] OGC 19-19-079: *OGC API - Features - Part 3: Filtering and the Common Query Language (CQL)*, https://docs.ogc.org/DRAFTS/19-079.html

core/standard/clause_6_overview.adoc

@@ -40,7 +40,7 @@ Using these building blocks a catalogue can be deployed as:
 
 or as:
 
-* a searchable catalogue with records that are accessed through an API.
+* a searchable catalogue with records accessed through an API/
 
 [[record-schema-overview]]
 === Record Schema
@@ -181,16 +181,82 @@ Where:
 [[api-behavior-model-overview]]
 ==== API Behavior Model
 
-This standard is designed to be compatible (but not conformant) with the OGC Catalogue Service for the Web (CSW). This allows OGC API - Records implementations and CSW implementations to co-exist in a single environment.
+A catalogue can be searched to identify subsets of records that satisfy search criteria specified by a client.
 
-The https://www.ogc.org/standards/cat[OGC Catalogue Service standard version 3] provides an abstract core model of metadata (data about data) describing a number of different information types (data, services, styles, processes, etc.) on which the classic operations GetCapabilities, DescribeRecord, GetRecords, and GetRecordById can be explained naturally. This model consists of a 1..n catalogue collections residing in a CSW backend repository. It holds service metadata describing service qualities (identification, contact, operations, filtering capabilities, etc.). At its heart, a catalogue may provide discovery services to any number of metadata repositories. The core catalogue model is based on an extension of Dublin Core (CSW Record). Application profiles can be developed to target specific metadata information models (such as ISO 19115/19139, etc.).
+Having found one or more records of interst via a search, the client can then access (i.e. bind) the resource using the descriptive information contained in each record.
 
-Discussion has shown that the API model also assumes underlying service and object descriptions, so a convergence seems possible. In any case, it will be advantageous to have a similar "mental model" of the server store organization on hand to explain the various functionalities introduced below.
+The following table lists the set of properties defined in this specification, called _**core queryables**_, that may be included in a catalogue record.
+
+[#core-queryables-list,reftext='{table-caption} {counter:table-num}']
+.Table of Core Queryables related to the catalogue record
+[cols="2,5",options="header"]
+|===
+|Queryables |Description
+|recordId |A unique record identifier assigned by the server.
+|recordCreated |The date this record was created in the server.
+|recordUpdated |The most recent date on which the record was changed.
+|links |A list of links for navigating the API.
+|type |The nature or genre of the resource.
+|title |A human-readable name given to the resource.
+|description |A free-text description of the resource.
+|keywords |A list of keywords or tag associated with the resource.
+|keywordsCodespace |A reference to a controlled vocabulary used for the keywords property.
+|language |This refers to the natural language used for textual values.
+|externalId |An identifier for the resource assigned by an external entity.
+|created |The date the resource was created.
+|updated |The more recent date on which the resource was changed.
+|publisher |The entity making the resource available.
+|themes |A knowledge orgnaization system used to classify the resource.
+|formats |A list of available distributions for the resource.
+|contactPoint |An entity to contact about the resource.
+|license |A legal document under which the resource is made available.
+|rights |A statement that concerns all rights not addressed by the license such as a copyright statement.
+|extent |The spatio-temporal coverage of the resource.
+|associations |A list of links for accessing the resource, links to other resources associated with this resource, etc.
+|===
+
+A complete definition of a record can be found in the query <<query-response,Response>> sub-clause of the <<record-access,Records access>> clause.
+
+The choice of which properties to include in the set of core queryables was primarily informed by the following record models:
+
+* The http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#17[core catalogue schema] from the https://www.ogc.org/standards/cat[OGC® Catalogue Services 3.0] suite of standards,
+* the https://www.w3.org/TR/vocab-dcat/[Data Catalog Vocabular (DCAT) - Version 2] and the https://www.unece.org/fileadmin/DAM/stats/documents/ece/ces/ge.58/2017/mtg3/2017-UNECE-topic-i-EC-GeoDCAT-ap-paper.pdf[GeoDCAT-AP] specifications.
+
+It is expected that the information necessary to populate this core set of record properties is readily available for any resource that is being registered in the catalogue.  
+
+It is anticipated that this _core_ set of record properties will be extended to describe specific resource types (e.g. datasets, services, etc.) and also extended by information communities wishing to enrich the information content of the record to suit their needs.  Extending the information content of a record to suit specific needs is allowed and encouraged by this specification.
+
+Although this document does not mandate any particular encoding for a record, the document does define conformance classes for three encodings:
+
+* A <<record_json_encoding,GeoJSON>> record encoding,
+* an <<record_atom_encoding,ATOM>> record encoding,
+* and an <<record_html_encoding,HTML>> encoding.
+
+Other encoding are allow but are not described in this document.
+
+Accessing collections of records through the API defined in this document is described in the <<records-access,Records access>> section.
+
+Accessing individual records through the API defined in this document is described in the <<record-access,Record access>> section.
 
 ==== Search
 
-This standard offers various levels of search capability. At the core is the ability to search the catalogue with the following constructs:
+This specification defines three levels of search capability of increasing complexity and capability.
+
+The first or core level of search capability is based on <<OAFeat-1,OGC API - Features>> and thus supports:
+
+* bounding box searches,
+* time instant or time period searches,
+* and equality predicates (i.e. _property_=_value_).
+
+OGC API - Record extends these core search capabilities to include:
+
+* searches based on a subset of core queryables (e.g. by resource type, by external identifier).
+* keyword searches
+
+The <<clause-opensearch,second level of search capability>> extends the search API so that it is compatible with the https://portal.opengeospatial.org/files/?artifact_id=56866[OGC OpenSearch Geo and Time Extensions] (OpenSearch Geo).  OpenSearch Geo gives the user more control over the kinds of geometries, beyond a bounding box, that can be used to define an area of interest.
 
+The third level of search capability, defined by the <<clause-record-filter,_Filter using the Common Query Language_ Requirements Class>>, supports complex filter expressions using a rich set of logically connected query predicates.
+=======
 * a bounding box
 * a time instant or time period
 * keywords

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`).
+|===