Merge pull request #339 from opengeospatial/tk-review-2024-01-19

editorial updates

core/examples/README.md

@@ -3,5 +3,5 @@
 The sub-folders contain examples of responses of implementations of
 OGC API - Records - Part 1: Core.
 
-* [OpenAPI examples](openapi)
 * [JSON/GeoJSON examples](json)
+* [YAML examples](yaml)

core/examples/json/templated-link-ref.json

@@ -3,5 +3,5 @@
   "type": "image/png",
   "title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations",
   "uriTemplate": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}&bbox={bbox}&layers=stations&width={width}&height={height}&format=image/png",
-  "varBase": "https://www.someserver.com/variables/"
+  "varBase": "https://example.org/variables/"
 }

core/standard/20-004.adoc

@@ -29,7 +29,7 @@
 |Internal reference number of this OGC(R) document: 20-004
 |Version: 1.0.0-oab-review.1
 |Category: OGC(R) Implementation Standard
-|Editors:  Panagiotis (Peter) A. Vretanos, Tom Kralidis, Charles Heazel, Angelos Tzotsos
+|Editors:  Panagiotis (Peter) A. Vretanos, Tom Kralidis, Angelos Tzotsos, Charles Heazel
 |===
 
 [cols = "^", frame = "none"]

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-bbox.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_bbox]]
+[[ats_record-core-query-parameters_bbox]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/bbox*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/bbox*
 ^|Test Purpose |Validate bbox query parameter.
-^|Requirement |<<req_records-core-query-parameters_bbox,/req/records-core-query-parameters/bbox>>
+^|Requirement |<<req_record-core-query-parameters_bbox,/req/record-core-query-parameters/bbox>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-datetime.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_datetime]]
+[[ats_record-core-query-parameters_datetime]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/datetime*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/datetime*
 ^|Test Purpose |Validate datetime query parameter.
-^|Requirement |<<req_records-core-query-parameters_datetime,/req/records-core-query-parameters/datetime>>
+^|Requirement |<<req_record-core-query-parameters_datetime,/req/record-core-query-parameters/datetime>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-definition.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_externalIds-definition]]
+[[ats_record-core-query-parameters_externalIds-definition]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/externalIds-definition*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/externalIds-definition*
 ^|Test Purpose |Validate datetime query parameter.
-^|Requirement |<<req_records-core-query-parameters_externalIds-definition,/req/records-core-query-parameters/externalIds-definition>>
+^|Requirement |<<req_record-core-query-parameters_externalIds-definition,/req/record-core-query-parameters/externalIds-definition>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-response.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_externalIds-response]]
+[[ats_record-core-query-parameters_externalIds-response]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/externalIds-response*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/externalIds-response*
 ^|Test Purpose |Validate externalIds query parameter.
-^|Requirement |<<req_records-core-query-parameters_externalIds-response,/req/records-core-query-parameters/externalIds-response>>
+^|Requirement |<<req_record-core-query-parameters_externalIds-response,/req/record-core-query-parameters/externalIds-response>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-definition.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_ids-definition]]
+[[ats_record-core-query-parameters_ids-definition]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/ids-definition*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/ids-definition*
 ^|Test Purpose |Validate ids query parameter.
-^|Requirement |<<req_records-core-query-parameters_ids-definition,/req/records-core-query-parameters/ids-definition>>
+^|Requirement |<<req_record-core-query-parameters_ids-definition,/req/record-core-query-parameters/ids-definition>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-response.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_ids-response]]
+[[ats_record-core-query-parameters_ids-response]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/ids-response*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/ids-response*
 ^|Test Purpose |Validate ids query parameter.
-^|Requirement |<<req_records-core-query-parameters_ids-response,/req/records-core-query-parameters/ids-response>>
+^|Requirement |<<req_record-core-query-parameters_ids-response,/req/record-core-query-parameters/ids-response>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-limit.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_limit]]
+[[ats_record-core-query-parameters_limit]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/limit*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/limit*
 ^|Test Purpose |Validate limit query parameter.
-^|Requirement |<<req_records-core-query-parameters_limit,/req/records-core-query-parameters/limit>>
+^|Requirement |<<req_record-core-query-parameters_limit,/req/record-core-query-parameters/limit>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-definition.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_q-definition]]
+[[ats_record-core-query-parameters_q-definition]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/q-definition*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/q-definition*
 ^|Test Purpose |Validate q query parameter.
-^|Requirement |<<req_records-core-query-parameters_q-definition,/req/records-core-query-parameters/q-definition>>
+|Requirement |<<req_record-core-query-parameters_q-definition,/req/record-core-query-parameters/q-definition>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-response.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_q-response]]
+[[ats_record-core-query-parameters_q-response]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/q-response*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/q-response*
 ^|Test Purpose |Validate q query parameter.
-^|Requirement |<<req_records-core-query-parameters_q-response,/req/records-core-query-parameters/q-response>>
+^|Requirement |<<req_record-core-query-parameters_q-response,/req/record-core-query-parameters/q-response>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-definition.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_type-definition]]
+[[ats_record-core-query-parameters_type-definition]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/type-definition*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/type-definition*
 ^|Test Purpose |Validate type query parameter.
-^|Requirement |<<req_records-core-query-parameters_type-definition,/req/records-core-query-parameters/type-definition>>
+^|Requirement |<<req_record-core-query-parameters_type-definition,/req/record-core-query-parameters/type-definition>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-response.adoc

@@ -1,9 +1,9 @@
-[[ats_records-core-query-parameters_type-response]]
+[[ats_record-core-query-parameters_type-response]]
 [width="90%",cols="2,6a"]
 |===
-^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/type-response*
+^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/type-response*
 ^|Test Purpose |Validate type query parameter.
-^|Requirement |<<req_records-core-query-parameters_type-response,/req/records-core-query-parameters/type-response>>
+^|Requirement |<<req_record-core-query-parameters_type-response,/req/record-core-query-parameters/type-response>>
 ^|Test Method |. Construct a path for a searchable endpoint
 . Issue an HTTP GET request on the path
 . Check that the HTTP response header value is `+200+`.

core/standard/clause_0_front_material.adoc

@@ -6,21 +6,21 @@ This document defines the OGC API for Records.
 
 A Record makes a resource discoverable by providing summary information (metadata) about the resource. In this context, resources are things that would be useful to a user or developer, such as features, coverages, tiles / maps, styles, assets, machine models, services, processes, widgets, etc.
 
-OGC API - Records provides a way to browse or search a curated collection of records known as a catalog.  This specification envisions deploying a catalog as:
+OGC API - Records provides a way to browse or search a curated collection of records known as a catalog.  This specification envisions deploying a catalog using one of the following patterns:
 
 * a collection of static files,
 * a collection of records accessed via an API.
 
-A catalog can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing.  Such a deployment is amenable to browsing using a web browser or being crawled by a search engine crawler.
+A catalog can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing.  Such a deployment is amenable to browsing using a web browser, being crawled by a search engine crawler, or traversed by automated tools.
 
-A catalog can also be deployed as an API with well known endpoints for retrieving information about the catalog, retrieving records from the catalog and searching the catalog for sub-sets of records that satisfy user-defined search criteria.
+A catalog can also be deployed as an API with well known endpoints for retrieving information about the catalog, retrieving records from the catalog and searching the catalog for subsets of records that satisfy user-defined search criteria (area of interest, temporal extent, keywords, etc.).
 
 To enable this kind of flexible deployment of a collection of records, this specification defines the following set of building blocks:
 
 * a record,
 * a collection (of records),
 * a set of common query parameters
-* and a search API.
+* a search API.
 
 A record is the atomic unit of information in a catalog, It contains descriptive information (metadata) about a resource such as:
 
@@ -32,7 +32,7 @@ A record is the atomic unit of information in a catalog, It contains descriptive
 * links to access the resource,
 * etc.
 
-This information is generic and can be used to describe a wide variety of resources.  This specification expects and encourages implementations to enrich the information content of a record to suit specific use cases or requirements.
+This information is generic and can be used to describe a wide variety of resources.  This specification expects and encourages implementations to enrich the information content of a record to suit specific use cases, requirements, domains or communities.
 
 A collection of records is itself described by a record that provides descriptive information about the catalog.  The collection also provides access to the records of the collection either by explicitly linking to each record that is an item of the collection or by providing a search endpoint that allows the collection of records to be searched.
 
@@ -51,7 +51,7 @@ The search API allows collections of records to be searched using logically conn
 |Record |`/collections/{collectionId}/items/{recordId}` |GET |<<clause-record-core,Record Core>>
 |===
 
-A special use case of the catalog deployed as an API is the _local resources catalog_.  A local resources catalog is a catalog deployed to make local resources offered by a provider searchable using the catalog information model and API.  An example of a local resources catalog is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core].  Adding catalog capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression.  Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog.
+A special use case of the catalog deployed as an API is the _local resources catalog_.  A local resources catalog is a catalog deployed to make local resources offered by a provider searchable using the catalog information model and API.  An example of a local resources catalog is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core].  Adding catalog capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression.  Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog to search for records describing resources served by that API.
 
 [[keywords]]
 [big]*ii.    Keywords*

core/standard/clause_2_conformance.adoc

@@ -41,6 +41,8 @@ https://docs.ogc.org/is/19-072/19-072.html[OGC API - Common] provides a common f
 
 NOTE: Should we remove this statement about Common?  Records is really an extension of Features and so the reference to Features conformance should be sufficient.  Features should then reference common ... but it does not currently do so.
 
+NOTE TK: suggest to reference OGC API - Features and open issue on the OGC API - Features issue tracker to update their specification accordingly.
+
 https://docs.opengeospatial.org/is/17-069r4/17-069r4.html[OGC API - Features] provides a common foundation for OGC API standards for feature access. Therefore, this standard should also be viewed as an extension to OGC API - Features. Conformance to this standard requires demonstrated conformance to the applicable Conformance Classes of https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_conformance[OGC API - Features].
 
 The Conformance Classes implemented by an API are advertised through the <<conformance-classes,`/conformance`>> path on the <<landing-page,landing page>>. Each Conformance Class has an associated Requirements Class. The Requirements Classes define the functional requirements which will be tested through the associated Conformance Class.
@@ -81,7 +83,7 @@ The <<clause-autodiscovery,Autodiscovery>> conformance class defines requirement
 [[catalog-requirements-classes]]
 === Catalog deployments
 
-Using the above mentioned building blocks, this standard identifies the following catalog requirements classes:
+Using the above-mentioned building blocks, this standard identifies the following catalog requirements classes:
 
 * <<clause-crawlable-catalog,Crawlable Catalog>>
 * <<clause-searchable-catalog,Searchable Catalog>>
@@ -147,7 +149,7 @@ OGC Compliance Testing web site.
 |Conformance class |URI
 |<<ats_core_record,Record Core>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core
 |<<ats_record_collection,Record Collection>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection
-|<<atr_record_core-query-parameters,Record query parameters>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters
+|<<ats_record_core-query-parameters,Record query parameters>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters
 |<<ats_record_api,Records API>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-api
 |<<ats_sorting,Sorting>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting
 |<<ats_filtering,Filtering>> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/filtering

core/standard/clause_4_terms_and_definitions.adoc

@@ -47,7 +47,7 @@ aggregate of requirements and recommendations of a specification against a singl
 an asset of interest that may be described by metadata in a catalog for the purpose of discovery and access (i.e. binding)
 
 === Searchable catalog endpoint
-an endpoint in the OGC API resource tree that has been enhanced to support catalog queries
+an endpoint in the OGC API resource tree that designed to support catalog queries
 
 NOTE: For <<clause-searchable-catalog,searchable catalogs>>, the searchable catalog endpoint is at `/items`.  For <<clause-local-resources-catalog,local resources catalogs>>, an example of a searchable catalog endpoint might be `/collections` or `/processes`.