README.md; standard/: Changes to reflect implications of OGC API - Co…

…mmon - Part 2: Geospatial data

- As discussed in opengeospatial#64
- Other clarifications
- Also edited for completeness (e.g. Communication, Contributions)

CONTRIBUTORS.md

@@ -1,3 +1,3 @@
 * Chuck Heazel [@cmheazel](https://github.com/cmheazel)
 * Stephan Meissl [@Schpidi](https://github.com/Schpidi)
-
+* Jerome Jacovella-St-Louis [@jerstlouis](https://github.com/jerstlouis)

standard/OAPI_Coverages.adoc

@@ -94,11 +94,11 @@ include::clause_5_conventions.adoc[]
 
 include::clause_6_overview.adoc[]
 
-include::clause_7_core.adoc[]
+include::clause_7_geodata_coverage.adoc[]
 
 include::clause_8_media_types.adoc[]
 
-include::clause_9_subset.adoc[]
+include::clause_9_coverage_subset.adoc[]
 
 include::clause_10_HTML.adoc[]
 

standard/clause_10_HTML.adoc

@@ -6,73 +6,58 @@ The following requirements apply to an OGC API-Coverage implementation when the
 . The API advertises conformance to the HTML Conformance Class
 . The client negotiates an HTML format
 
-The HTML Requirements Class restricts requirements defined in the `Core` Requirements Class by imposing encoding-specific requirements. At this time, these additional requirements only apply to the HTTP response payloads. The sections below identify the scope of each new requirement and the `Core` requirements which lay within each scope.
+The HTML Requirements Class restricts requirements defined in the `GeoData-Coverage` Requirements Class by imposing encoding-specific requirements. At this time, these additional requirements only apply to the HTTP response payloads. The sections below identify the scope of each new requirement and the `GeoData-Coverage` requirements which lay within each scope.
 
 include::requirements/requirements_class_html.adoc[]
 
 === Common
 
 This section covers the requirements inherited from the API-Common standard. Its scope includes responses for the following operations:
 
-* `{root}/`: Landing Page
-* `{root}/api`: API Description
-* `{root}/conformance`: Conformance Classes
-* `{root}/collections`: Collections
-* `{root}/collections/{coverageid}`: Collection Information
+* `{datasetAPI}/`: Dataset API Landing Page
+* `{datasetAPI}/api`: API Description
+* `{datasetAPI}/conformance`: Conformance Classes
+* `{datasetAPI}/collections`: Collections
+* `{datasetAPI}/collections/{coverageid}`: Collection Information
 
 include::requirements/html/REQ_api-common.adoc[]
 
 It is also necessary to advertise conformance with this Requirements Class.
 
 include::requirements/html/REQ_html-conformance.adoc[]
 
-=== Coverage Offering
+=== Coverage
 
-This section covers the <<coverage-clause,Coverage Offering>> response for the
-`{root}/collections/{coverageid}/coverage` operation.
+This section covers the <<coverage-clause,Coverage>> response for the
+`{datasetAPI}/collections/{coverageid}/coverage` operation.
 
-include::requirements/html/REQ_cov-offer-success.adoc[]
-
-=== Coverage Description
-
-This section covers the <<coverage-description-clause,Coverage Description>> response for the
-`{root}/collections/{coverageid}/coverage/description` operation.
-
-include::requirements/html/REQ_cov-desc-success.adoc[]
+include::requirements/html/REQ_coverage-success.adoc[]
 
 === Coverage Domain Set
 
 This section covers the <<coverage-domainset-clause,Coverage Domain Set>> response for the
-`{root}/collections/{coverageid}/coverage/domainset` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/domainset` operation.
 
-include::requirements/html/REQ_cov-ds-success.adoc[]
+include::requirements/html/REQ_domainset-success.adoc[]
 
 === Coverage Range Type
 
 This section covers the <<coverage-rangetype-clause,Coverage Range Type>> response for the
-`{root}/collections/{coverageid}/coverage/rangetype` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/rangetype` operation.
 
-include::requirements/html/REQ_cov-rt-success.adoc[]
+include::requirements/html/REQ_rangetype-success.adoc[]
 
 === Coverage Range Set
 
 This section covers the <<coverage-rangeset-clause,Coverage Range Set>> response for the
-`{root}/collections/{coverageid}/coverage/rangeset` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/rangeset` operation.
 
-include::requirements/html/REQ_cov-rs-success.adoc[]
+include::requirements/html/REQ_rangeset-success.adoc[]
 
 === Coverage Metadata
 
 This section covers the <<coverage-metadata-clause,Coverage Metadata>> response for the
-`{root}/collections/{coverageid}/coverage/metadata` operation.
-
-include::requirements/html/REQ_cov-md-success.adoc[]
-
-=== Coverage All
-
-This section covers the <<coverage-all-clause,Coverage All>> response for the
-`{root}/collections/{coverageid}/coverage/all` operation.
-
-include::requirements/html/REQ_cov-all-success.adoc[]
+`{datasetAPI}/collections/{coverageid}/coverage/metadata` operation.
 
+include::requirements/html/REQ_metadata-success.adoc[]
 

standard/clause_11_JSON.adoc

@@ -1,78 +1,63 @@
-[[requirements-class-json-clause]]
-== Requirements Class JSON
+[[requirements-class-cisjson-clause]]
+== Requirements Class CIS JSON
 
 The following requirements apply to an OGC API-Coverage implementation when the following conditions apply:
 
-. The API advertises conformance to the JSON Conformance Class
-. The client negotiates a JSON or GeoJSON format
+. The API advertises conformance to the CIS JSON Conformance Class
+. The client negotiates a JSON or CIS JSON format
 
-The JSON Requirements Class restricts requirements defined in the `Core` Requirements Class by imposing encoding-specific requirements. At this time, these additional requirements only apply to the HTTP response payloads. The sections below identify the scope of each new requirement and the `Core` requirements which lay within each scope.
+The CIS JSON Requirements Class restricts requirements defined in the `GeoData-Coverage` Requirements Class by imposing encoding-specific requirements. At this time, these additional requirements only apply to the HTTP response payloads. The sections below identify the scope of each new requirement and the `GeoData-Coverage` requirements which lay within each scope.
 
-include::requirements/requirements_class_json.adoc[]
+include::requirements/requirements_class_cisjson.adoc[]
 
 === Common
 
 This section covers the requirements inherited from the API-Common standard. Its scope includes responses for the following operations:
 
-* `{root}/`: Landing Page
-* `{root}/api`: API Description
-* `{root}/conformance`: Conformance Classes
-* `{root}/collections`: Collections
-* `{root}/collections/{coverageid}`: Collection Information
+* `{datasetAPI}/`: Dataset API Landing Page
+* `{datasetAPI}/api`: API Description
+* `{datasetAPI}/conformance`: Conformance Classes
+* `{datasetAPI}/collections`: Collections
+* `{datasetAPI}/collections/{coverageid}`: Collection Information
 
-include::requirements/json/REQ_api-common.adoc[]
+include::requirements/cisjson/REQ_api-common.adoc[]
 
 It is also necessary to advertise conformance with this Requirements Class.
 
-include::requirements/json/REQ_json-conformance.adoc[]
+include::requirements/cisjson/REQ_cisjson-conformance.adoc[]
 
-=== Coverage Offering
+=== Coverage
 
-This section covers the <<coverage-clause,Coverage Offering>> response for the
-`{root}/collections/{coverageid}/coverage` operation.
+This section covers the <<coverage-clause,Coverage>> response for the
+`{datasetAPI}/collections/{coverageid}/coverage` operation.
 
-include::requirements/json/REQ_cov-offer-success.adoc[]
-
-=== Coverage Description
-
-This section covers the <<coverage-description-clause,Coverage Description>> response for the
-`{root}/collections/{coverageid}/coverage/description` operation.
-
-include::requirements/json/REQ_cov-desc-success.adoc[]
+include::requirements/cisjson/REQ_coverage-success.adoc[]
 
 === Coverage Domain Set
 
 This section covers the <<coverage-domainset-clause,Coverage Domain Set>> response for the
-`{root}/collections/{coverageid}/coverage/domainset` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/domainset` operation.
 
-include::requirements/json/REQ_cov-ds-success.adoc[]
+include::requirements/cisjson/REQ_domainset-success.adoc[]
 
 === Coverage Range Type
 
 This section covers the <<coverage-rangetype-clause,Coverage Range Type>> response for the
-`{root}/collections/{coverageid}/coverage/rangetype` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/rangetype` operation.
 
-include::requirements/json/REQ_cov-rt-success.adoc[]
+include::requirements/cisjson/REQ_rangetype-success.adoc[]
 
 === Coverage Range Set
 
 This section covers the <<coverage-rangeset-clause,Coverage Range Set>> response for the
-`{root}/collections/{coverageid}/coverage/rangeset` operation.
+`{datasetAPI}/collections/{coverageid}/coverage/rangeset` operation.
 
-include::requirements/json/REQ_cov-rs-success.adoc[]
+include::requirements/cisjson/REQ_rangeset-success.adoc[]
 
 === Coverage Metadata
 
 This section covers the <<coverage-metadata-clause,Coverage Metadata>> response for the
-`{root}/collections/{coverageid}/coverage/metadata` operation.
-
-include::requirements/json/REQ_cov-md-success.adoc[]
-
-=== Coverage All
-
-This section covers the <<coverage-all-clause,Coverage All>> response for the
-`{root}/collections/{coverageid}/coverage/all` operation.
-
-include::requirements/json/REQ_cov-all-success.adoc[]
+`{datasetAPI}/collections/{coverageid}/coverage/metadata` operation.
 
+include::requirements/cisjson/REQ_metadata-success.adoc[]
 

standard/clause_6_overview.adoc

@@ -6,12 +6,12 @@
 
 The OGC API family of standards enable access to resources using the HTTP protocol and its' associated operations (GET, PUT, POST, etc.). OGC API-Common defines a set of features which are applicable to all OGC APIs. Other OGC standards extend API-Common with features specific to a resource type. This OGC API-Coverages standard defines an API with two goals:
 
-. Provide access to `Coverages` conformant to the <<coverage-implementation-schema-overview,OGC CIS standard>>.
+. Provide access to *_Coverages_* conformant to the <<coverage-implementation-schema-overview,OGC CIS standard>>.
 . Provide functionality comparable to that of the <<web-coverage-service-overview,OGC WCS standard>>.
 
 Resources exposed through an OGC API may be accessed through a Universal Resource Identifier <<rfc3986,(URI).>> URIs are composed of three sections:
 
-* Service Offering: The service endpoint (subsequently referred to as Base URI or {root})
+* Dataset distribution API: The endpoint corresponding to a dataset distribution, where the landing page resource as defined in OGC API - Common - Part 1: Core is available (subsequently referred to as Base URI or `{datasetAPI}`)
 * Access Paths: Unique paths to Resources
 * Query: Parameters to adjust the representation of a Resource or Resources like encoding format or subsetting
 
@@ -25,27 +25,31 @@ Some resources are also accessible through links on previously accessed resource
 |===
 ^|**Path Template** ^|**Relation** ^|**Resource**
 3+^|**Common**
-|<<landing-page,{root}/>> |none |Landing page
-|<<api-definition,{root}/api>> |`service-desc` +
-or +
-`service-doc` |API Description (optional)
-|<<conformance-classes,{root}/conformance>> |`conformance` |Conformance Classes
-|<<collections,{root}/collections>> |`data` |Metadata describing the spatial collections (coverages) available from this API.
-|<<collectionInfo,{root}/collections/{coverageid}>> | |Metadata describing the coverge which has the unique identifier `{coverageid}`
+|<<landing-page,{datasetAPI}/>> |`ogc:common:dataset` |Landing page for this dataset distribution
+|<<api-definition,{datasetAPI}/api>>
+(not a fixed path) |`service-desc` | API description (e.g. OpenAPI)
+|<<api-definition,{datasetAPI}/api>>
+(not a fixed path) |`service-doc` | API documentation (optional, e.g. HTML)
+|<<conformance-classes,{datasetAPI}/conformance>> |`conformance` |Conformance Classes
+|<<collections,{datasetAPI}/collections>> |`data` |The list off all collections available, some or all of which may be accessible using this Coverage API. Each of these collection objects take the same form as that of the collection resource object described immediately below.
+|<<collectionInfo,{datasetAPI}/collections/{coverageId}>> | `ogc:common:collection` |resource corresponding to the collection with the unique identifier `{coverageId}`, which may be accessible as a coverage.
+The resource will describe key elements such as an `id`, `title`, `description`, available `crs` and `extent` (the coverage envelope) as well as
+links to resources pertaining to this collection. For coverages, it will either embed or link to a CIS JSON encoding of both the range type and the domain set.
+It is comparable to a WCS *_DescribeCoverage_* response, with the exception that the range type and domain set may have to be retrieved separately by following a link
+to accommodate the case where they may be considerably large, and the domain set may support query parameters to subset it.
 3+^|**Coverages**
-|<<coverage-clause,{root}/collections/{coverageid}/coverage>> |`items` |A general description of the coverage identified by {coverageid} including the coverage's envelope.
-|<<coverage-description-clause,{root}/collections/{coverageid}/coverage/description>> |none |returns the whole coverage description consisting of domainset, rangetype, and metadata (but not the rangeset)
-|<<coverage-domainset-clause,{root}/collections/{coverageid}/coverage/domainset>> |none |returns the coverage's domain set definition
-|<<coverage-rangetype-clause,{root}/collections/{coverageid}/coverage/rangetype>> |none |returns the coverage's range type information (i.e., a description of the data semantics)
-|<<coverage-metadata-clause,{root}/collections/{coverageid}/coverage/metadata>> |none |returns the coverage's metadata (may be empty)
-|<<coverage-rangeset-clause,{root}/collections/{coverageid}/coverage/rangeset>> |none |returns the coverage's range set, i.e., the actual values in the coverage's Native Format (see format encoding for ways to retrieve in specific formats)
-|<<coverage-all-clause,{root}/collections/{coverageid}/coverage/all>> |none |returns all of the above namely the coverage's domainset, rangetype, metadata, and rangeset comparable to a GetCoverage response
+|<<coverage-clause,{datasetAPI}/collections/{coverageId}/coverage>> +
+(not a fixed path) |`ogc:coverage:coverage` |returns the coverage including all of its components (domain set, range type, range set and metadata), to the extent that it is supported by the selected representation (see format encoding for ways to retrieve in specific formats). It is comparable to a WCS *_GetCoverage_* response.
+|<<coverage-rangeset-clause,{datasetAPI}/collections/{coverageId}/coverage/rangeset>> |`ogc:coverage:rangeset` |if supported by the service and by the selected representation, returns only the coverage's range set, i.e., the actual values in the selected representation without any accompanying description or extra information.
+|<<coverage-rangetype-clause,{datasetAPI}/collections/{coverageId}/coverage/rangetype>> |`ogc:coverage:rangetype` |if available separately from the collection resource, returns the coverage's range type information, i.e., a description of the data semantics (their components and data type).
+|<<coverage-domainset-clause,{datasetAPI}/collections/{coverageId}/coverage/domainset>> |`ogc:coverage:domainset` |if available separately from the collection resource, returns the coverage's domain set definition (the detailed n-dimensional space covered by the data).
+|<<coverage-metadata-clause,{datasetAPI}/collections/{coverageId}/coverage/metadata>> |`ogc:coverage:metadata` |if available, returns the associated coverage metadata as defined by the CIS model, which may be e.g. domain specific metadata.
 |===
 
 Where:
 
-* {root} = Base URI for the API server
-* {coverageid} = an identifier for a specific coverage (collection)
+* {datasetAPI} = URI of the landing page for the API distributing the dataset
+* {coverageId} = an identifier for a specific coverage (collection)
 
 [[coverage-implementation-schema-overview]]
 === Coverage Implementation Schema
@@ -84,9 +88,9 @@ The OGC API-Coverages standard is an extension of the OGC API-Common standard. T
 |<<landing-page,API Landing Page>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core
 |<<api-definition,API Definition>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core
 |<<conformance-classes,Declaration of Conformance Classes>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core
-|<<collection-access-section,Collections>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/collections
+|<<collection-access-section,Collections>>| http://www.opengis.net/spec/ogcapi_common-2/1.0/req/collections
 |<<requirements-class-openapi_3_0-clause,OpenAPI 3.0>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/oas30
-|<<requirements-class-json-clause,JSON>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/geojson
+|<<requirements-class-json-clause,JSON>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/json
 |<<requirements-class-html-clause,HTML>>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/html
 |====