Merge pull request #225 from tomkralidis/issue-26

update informative text on resource types (#26)

README.md

@@ -244,13 +244,13 @@ The search capabilities of the Records API are organized into various levels of
 
 ## Deployment patterns
 
-There are a number of ways that records can be deployed as a "collection of records" or a catalogue.  The OGC API Records specification envisions three deployment patterns using the building blocks described above:
+There are a number of ways that records can be deployed as a "collection of records" or a catalogue.  The OGC API - Records specification envisions three deployment patterns using the building blocks described above:
 
 * a catalogue deployed as a crawlable collection of records
 * a catalogue deployed as a searchable endpoint(s)
 * a local resources catalogue
 
-:warning: In STAC the terms _static_ and _dynamic_ are used to describe these deployment patterns.  However, a _static_ catalogue is not really static since additional records can be added at any time.  As a result, it was decided to try some different, more descriptive, terminology.  The terms _crawlable_ and _searchable_ have been proposed and are used in this README and in the OGC API Records specification.  Other proposed terms include _basic_ and _searchable_.  The SWG decided to try out _crawlable_ and _searchable_ for now but these terms are subject to change based on feedback.
+:warning: In STAC the terms _static_ and _dynamic_ are used to describe these deployment patterns.  However, a _static_ catalogue is not really static since additional records can be added at any time.  As a result, it was decided to try some different, more descriptive, terminology.  The terms _crawlable_ and _searchable_ have been proposed and are used in this README and in the OGC API - Records specification.  Other proposed terms include _basic_ and _searchable_.  The SWG decided to try out _crawlable_ and _searchable_ for now but these terms are subject to change based on feedback.
 
 ### Crawlable Catalogue
 
@@ -317,7 +317,7 @@ The OGC API resource tree has a number of resource endpoints that represent list
 * `/processes` - list of processes offered by an OGC API
 * `/collections/{collectionId}/scenes` - list of source scenes for a coverage or map
 
-The OGC API Records building blocks can be used to enable catalogue-like queries at these endpoints.  This is especially useful if the endpoint can potentially have a very large number of sub-resources as might be the case at the `/collections` endpoint.  For example, the following request searches for collections whose spatial extent intersects a specified bounding box and whose temporal extent intersects a specified time period:
+The OGC API - Records building blocks can be used to enable catalogue-like queries at these endpoints.  This is especially useful if the endpoint can potentially have a very large number of sub-resources as might be the case at the `/collections` endpoint.  For example, the following request searches for collections whose spatial extent intersects a specified bounding box and whose temporal extent intersects a specified time period:
 
 ```
 GET /collections?bbox=-69.64,37.76,-56.12,46.63&datetime=2020-01-11T00:00:00/2020-01-12T00:00:00
@@ -331,7 +331,7 @@ The OpenSearch protocol defines an XML description document describing how to re
 
 The OpenSearch protocol used by OGC API - Records is based on a protocol that was launched in 2005 by A9.com, an Amazon subsidiary.  In 2021, Amazon.com launched the open source OpenSearch search engine project, unrelated to the OpenSearch launched by A9.com aside from repurposing the name.  The two projects will continue to independently co-exist, though the search protocol (now hosted [here](https://github.com/dewitt/opensearch)) has largely remained stable and unchanged for over ten years, with no significant updates expected on the horizon.  Neither of these two efforts is related to the Open Search Foundation project found [here](https://opensearchfoundation.org/).
 
-Because of this shift in status of OpenSearch issolating it in its part of the OGC API Records suite of standards would allow the related conformance class(es) to be easilt deprecated or renamed in the future.  The work for this part, Part 2, is being carried out [here](https://github.com/opengeospatial/ogcapi-records/tree/master/extensions/OpenSearch).
+Because of this shift in status of OpenSearch issolating it in its part of the OGC API - Records suite of standards would allow the related conformance class(es) to be easilt deprecated or renamed in the future.  The work for this part, Part 2, is being carried out [here](https://github.com/opengeospatial/ogcapi-records/tree/master/extensions/OpenSearch).
 
 ## Using the standard
 
@@ -370,7 +370,7 @@ The current expectation is to have a stable version of the Core specification in
 
 The contributor understands that any contributions, if accepted by the OGC Membership and ISO/TC 211, shall be incorporated into OGC and ISO/TC 211 standards documents and that all copyright and intellectual property shall be vested to the OGC.
 
-The OGC API Records Standards Working Group (SWG) is the group at OGC responsible for the stewardship of the standard, but is working to do as much work in public as possible.
+The OGC API - Records Standards Working Group (SWG) is the group at OGC responsible for the stewardship of the standard, but is working to do as much work in public as possible.
 
 * [Open issues](https://github.com/opengeospatial/ogcapi-records/issues)
 * [Proposing changes](https://github.com/opengeospatial/ogcapi-records/wiki/Propose-a-change-to-a-draft-of-a-CAT40-specification-document)

core/examples/yaml/ogcapi-record-1-example1.yaml

@@ -7,7 +7,7 @@ info:
     classes "Core", "GeoJSON", "HTML" and "OpenAPI 3.0" of the draft
     standard "OGC API - Records - Part 1: Core".
 
-    This example is a generic OGC API Records definition that uses path
+    This example is a generic OGC API - Records definition that uses path
     parameters to describe all record collections and all records.
     The generic OpenAPI definition does not provide any details on the
     collections or the record content. This information is only available

core/openapi/ogcapi-records-1.yaml

@@ -206,7 +206,7 @@ components:
         itemType:
           description: |-
             indicator about the type of the items in the collection (the
-            default value is 'record' for OAPIR).
+            default value is 'record' for OGC API - Records).
           type: string
           default: record
         crs:
@@ -799,7 +799,7 @@ components:
         The URIs of all conformance classes supported by the server.
 
         To support "generic" clients that want to access multiple
-        OGC API Records implementations - and not "just" a specific
+        OGC API - Records implementations - and not "just" a specific
         API / server, the server declares the conformance
         classes it implements and conforms to.
       content:

core/openapi/responses/ConformanceDeclaration.yaml

@@ -2,7 +2,7 @@ description: |-
   The URIs of all conformance classes supported by the server.
 
   To support "generic" clients that want to access multiple
-  OGC API Records implementations - and not "just" a specific
+  OGC API - Records implementations - and not "just" a specific
   API / server, the server declares the conformance
   classes it implements and conforms to.
 content:

core/openapi/schemas/recordGeoJSON.yaml

@@ -58,7 +58,7 @@ properties:
         type: string
         description:
           The nature or genre of the resource. The value should be a code,
-          convenient for filtering the records. Where available, a link to
+          convenient for filtering records. Where available, a link to
           the canonical URI of the record type resource will be added to
           the 'links' property.
         maxLength: 64

core/standard/README.md

@@ -1,7 +1,7 @@
 
 # OGC API - Records Specification
 
-This directory contains the OGC API - Records Specification. This specification, working with the parallel OGC API Common specification, defines the API analog to the CSW standard.
+This directory contains the OGC API - Records Specification. This specification, working with the parallel OGC API - Common specification, defines the API analog to the CSW standard.
 
 This specification addresses only those parts of an API which are specific to Records resources. Those capabilities which may have applicability beyond Records should be considered for inclusion in OGC API - Common.
 

core/standard/annex_common.adoc

@@ -6,7 +6,7 @@
 [[common-overview]]
 === Overview
 
-This annex describes the components of the OGC API Records that are derived for OGC API Common.
+This annex describes the components of the OGC API - Records that are derived from OGC API - Common.
 
 [[core-dependencies-section]]
 === Dependencies

core/standard/annex_resource_types.adoc

@@ -6,12 +6,33 @@
 [[common_resource_types-overview]]
 === Overview
 
-This annex describes commonly used codelists and identifiers for OGC resource types when qualifying resources via the record
-schema's `properties.type` property.  Please note that these codelists and identifiers are NOT normative.  For information
-communities wishing to further identify, it is suggested that a specification extension be developed to meet those
+This annex describes common resource types when qualifying resources via a record's `properties.type` property, in the absence
+of a formal controlled vocabulary.  Please note that these codelists and identifiers are NOT normative.  For information
+communities wishing to formally identify and qualify, it is suggested that a specification extension be developed to meet those
 requirements.
 
-* ISO 19115:2003: https://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml (`MD_ScopeCode`)
-* ISO 19115-1:2014: https://github.com/ISO-TC211/XML/blob/master/schemas.isotc211.org/19115/resources/Codelist/cat/codelists.xml (`MD_ScopeCode`)
-* OSGeo Catalogue Interoperability Group link types: https://github.com/OSGeo/Cat-Interop/blob/master/LinkPropertyLookupTable.csv
-* Service types from the OGC Naming Authority: http://www.opengis.net/def/serviceType
+==== Data
+
+* http://www.opengis.net/def/rel/ogc/1.0/dataset
+
+==== Services
+
+===== OGC Web Services
+
+* http://www.opengis.net/def/serviceType/ogc/csw
+* http://www.opengis.net/def/serviceType/ogc/wms
+* http://www.opengis.net/def/serviceType/ogc/wfs
+* http://www.opengis.net/def/serviceType/ogc/wcs
+* http://www.opengis.net/def/serviceType/ogc/wps
+* http://www.opengis.net/def/serviceType/ogc/sos
+
+===== OGC API
+
+* http://www.opengis.net/spec/ogcapi-records-1/1.0
+* http://www.opengis.net/spec/ogcapi-features-1/1.0
+* http://www.opengis.net/spec/ogcapi-coverages-1/1.0
+* http://www.opengis.net/spec/ogcapi-maps-1/1.0
+* http://www.opengis.net/spec/ogcapi-tiles-1/1.0
+* http://www.opengis.net/spec/ogcapi-styles-1/1.0
+* http://www.opengis.net/spec/ogcapi-processes-1/1.0
+* http://www.opengis.net/spec/ogcapi-edr-1/1.0

core/standard/clause_11_searchable_catalogue.adoc

@@ -3,7 +3,7 @@
 
 include::requirements/requirements_class_searchable-catalogue.adoc[]
 
-The `Searchable Catalogue` Requirements Class defines the requirements for a catalogue that is searchable through an API.  A searchable catalogue is an implementation of <<OAFeat-1,OGC API Features>> that uses a defined information model.  In the case of OGC API Records, that information model is the <<clause-record-core,Record>>.
+The `Searchable Catalogue` Requirements Class defines the requirements for a catalogue that is searchable through an API.  A searchable catalogue is an implementation of <<OAFeat-1,OGC API - Features>> that uses a defined information model.  In the case of OGC API - Records, that information model is the <<clause-record-core,Record>>.
 
 === Core
 

core/standard/clause_13_sorting.adoc

@@ -22,7 +22,7 @@ include::requirements/sorting/REQ_get-sortables-op.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.
+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.
 

core/standard/clause_2_conformance.adoc

@@ -29,7 +29,7 @@ The <<clause-record-core,_Record Core_>> conformance class defines the requireme
 
 The <<clause-record-collection,_Record Collection_>> conformance class defines requirements for the metadata used to describe a collection of related records.
 
-The <<clause-records-api,_Records API_>> conformance class defines the requirements for an API for searching collections of records based on logically connected predicates that can include spatial and/or temporal predicates.  The Records API is based on http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Feature - Part 1: Core] with <<records-access,extensions>> specific to OGC API Records.
+The <<clause-records-api,_Records API_>> conformance class defines the requirements for an API for searching collections of records based on logically connected predicates that can include spatial and/or temporal predicates.  The Records API is based on http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Feature - Part 1: Core] with <<records-access,extensions>> specific to OGC API - Records.
 
 The <<clause-sorting,_Sorting_>> conformance class defines the requirements to support sorting of records in a query response.
 

core/standard/clause_3_references.adoc

@@ -11,7 +11,7 @@ The following normative documents contain provisions that, through reference in
 * [[GeoJSON]] IETF RFC 7946: *The GeoJSON Format*, https://tools.ietf.org/rfc/rfc7946.txt[GeoJSON]
 * [[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]
+* [[OACommon]] OGC 19-072: *OGC API - 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]

core/standard/clause_6_overview.adoc

@@ -72,12 +72,12 @@ It is anticipated that this set of properties will be extended to enrich the inf
 
 The Records API allows a subset of records to be retrieved from a catalogue using a logically connected set of predicates that may include spatial and/or temporal predicates.
 
-The Records API extends https://github.com/opengeospatial/ogcapi-common[OGC API Common] and http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Core: Part 1] to:
+The Records API extends https://github.com/opengeospatial/ogcapi-common[OGC API - Common] and http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Core: Part 1] to:
 
 . Provide modern API patterns and encodings to facilitate further lowering the barrier to finding the existence of spatial resources on the Web.
 . Provide functionality comparable to that of the <<api-behaviour-model-overview,OGC Catalogue Service (CSW) standard>> so that a facade can be created over legacy services thus allowing them to participate in the new OGC API ecosystem.
 
-Collections of records exposed though this OGC API may be accessed through an https://www.ogc.org/standards/ogcapi-features[OGC API Features API] that has been:
+Collections of records exposed though this OGC API may be accessed through an https://www.ogc.org/standards/ogcapi-features[OGC API - Features API] that has been:
 
 * extended with <<records-access,additional parameters>> at the `/collections/{collectionId}/items` endpoint,
 * and constrained to a single <<record-overview,information model>> (i.e. the <<record-overview,record>>).

core/standard/clause_7_record.adoc

@@ -93,6 +93,8 @@ A record has one `properties.type` and one `properties.license` property. The va
 
 include::recommendations/record-core/REC_record-type.adoc[]
 
+include::recommendations/record-core/PER_record-type.adoc[]
+
 include::recommendations/record-core/REC_record-license.adoc[]
 
 In addition, links to external resources representing the record type and the licenses are recommended, as described in the next section.
@@ -154,7 +156,7 @@ Link: <http://data.example.org/collections/my_catalogue.html>; rel="collection";
 [[sc_templated_links_with_variables]]
 ==== Templated links with variables
 
-OGC API Records uses links to express associations between resources including links that bind to the resource(s) being described by a record.  In some situations, a static link does not adequately express all the information necessary to retrieve the referenced resource OR does not allow for the resource to be retrieved in an efficient manner.
+OGC API - Records uses links to express associations between resources including links that bind to the resource(s) being described by a record.  In some situations, a static link does not adequately express all the information necessary to retrieve the referenced resource OR does not allow for the resource to be retrieved in an efficient manner.
 
 Consider the case where a record describing a coverage resource is discovered by searching the catalogue using a spatial constraint (e.g. a bbox).  Further consider that the found record contains a link to retrieve the coverage.  Using a static link for the binding link would only allow retrieval of the entire coverage.  Using a templated link, however, would allow the context of the catalogue query (i.e. the bbox) to be passed to down to the binding link.  The templated link with all substitution values resolved would thus retrieve the subset of the coverage that corresponds to the spatial contraint used to discover the record in the first place which presumably represents the area of interest.
 

core/standard/clause_8_collection.adoc

@@ -12,7 +12,7 @@ A _collection_ is an object that provides information about and access to a set
 
 The schema for the collection resource is an extension of the collection schema defined in http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features].
 
-While http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features] defines a specific location for the collection resource (path: `/collections/{collectionId}`), OGC API Records only fixes the location of the collection in the <<clause-records-api,Record API>> conformance class.  Otherwise the collection resource can live anywhere the provider wishes to place it including as a static file in web space (e.g. a web-accessible directory or an S3 bucket).
+While http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features] defines a specific location for the collection resource (path: `/collections/{collectionId}`), OGC API - Records only fixes the location of the collection in the <<clause-records-api,Record API>> conformance class.  Otherwise the collection resource can live anywhere the provider wishes to place it including as a static file in web space (e.g. a web-accessible directory or an S3 bucket).
 
 [[record-collection-schema]]
 === Record collection schema

core/standard/clause_9_api.adoc

@@ -72,7 +72,7 @@ include::recommendations/records-api/REC_cors.adoc[]
 
 === Encodings
 
-While OGC API Records does not specify any mandatory encoding, support for the following encodings is recommended.
+While OGC API - Records does not specify any mandatory encoding, support for the following encodings is recommended.
 
 include::recommendations/records-api/REC_html.adoc[]