From b89f9588c63f4e8e03b8d98f4c9befd3c75b6ec7 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Mon, 22 Jan 2024 03:44:35 -0500 Subject: [PATCH] PAV Review edits. --- .../ogcapi-records-1-building-blocks.yaml | 10 +++ ...s-1-example-ref-buildingblocks-bundle.yaml | 1 + ...api-records-1-example-ref-schema-repo.yaml | 1 + core/openapi/parameters/ids.yaml | 13 ++++ .../ATS_class_searchable-catalog_crs.adoc | 13 ---- .../searchable-catalog_crs/ATS_crs.adoc | 12 --- core/standard/annex_ats.adoc | 9 +-- core/standard/clause_0_front_material.adoc | 6 +- core/standard/clause_10_security.adoc | 2 +- core/standard/clause_2_conformance.adoc | 42 +++++----- core/standard/clause_3_references.adoc | 31 ++------ .../clause_4_terms_and_definitions.adoc | 2 +- core/standard/clause_5_conventions.adoc | 12 +-- core/standard/clause_6_overview.adoc | 78 +++++++------------ core/standard/clause_7_building_blocks.adoc | 75 ++++++++++-------- core/standard/clause_8_deployments.adoc | 16 ++-- core/standard/clause_9_media_types.adoc | 4 +- .../PER_additional-collection-properties.adoc | 4 +- .../REC_json-encoding.adoc | 2 +- .../REC_text-encoding.adoc | 2 +- .../record-filter/REC_json-encoding.adoc | 2 +- .../record-filter/REC_text-encoding.adoc | 2 +- .../PER_additional-properties.adoc | 4 +- .../PER_additional-requirements.adoc | 6 +- .../autodiscovery/REQ_autodiscovery_link.adoc | 2 +- .../crawlable-catalog/REQ_record.adoc | 2 +- .../REQ_filter-crs-param.adoc | 2 +- .../REQ_filter-param.adoc | 2 +- .../REQ_filter-response.adoc | 2 +- .../requirements/oas30/REQ_oas-common.adoc | 7 -- .../oas30/REQ_oas-conformance.adoc | 2 +- .../requirements/oas30/REQ_oas30.adoc | 7 ++ .../REQ_query-param-ids-definition.adoc | 3 +- .../searchable-catalog_crs/REQ_crs.adoc | 7 -- .../sorting/REQ_get-sortables-success.adoc | 15 +++- 35 files changed, 184 insertions(+), 216 deletions(-) create mode 100644 core/openapi/parameters/ids.yaml delete mode 100644 core/standard/abstract_tests/ATS_class_searchable-catalog_crs.adoc delete mode 100644 core/standard/abstract_tests/searchable-catalog_crs/ATS_crs.adoc delete mode 100644 core/standard/requirements/oas30/REQ_oas-common.adoc create mode 100644 core/standard/requirements/oas30/REQ_oas30.adoc delete mode 100644 core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc diff --git a/core/openapi/ogcapi-records-1-building-blocks.yaml b/core/openapi/ogcapi-records-1-building-blocks.yaml index 001e0aa2..7f426e1f 100644 --- a/core/openapi/ogcapi-records-1-building-blocks.yaml +++ b/core/openapi/ogcapi-records-1-building-blocks.yaml @@ -73,6 +73,16 @@ components: type: string explode: false style: form + ids: + name: ids + in: query + required: false + schema: + type: array + items: + type: string + explode: false + style: form language: name: language in: query diff --git a/core/openapi/ogcapi-records-1-example-ref-buildingblocks-bundle.yaml b/core/openapi/ogcapi-records-1-example-ref-buildingblocks-bundle.yaml index a453050e..8cbd0e5e 100644 --- a/core/openapi/ogcapi-records-1-example-ref-buildingblocks-bundle.yaml +++ b/core/openapi/ogcapi-records-1-example-ref-buildingblocks-bundle.yaml @@ -151,6 +151,7 @@ paths: - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1-building-blocks.yaml#/components/parameters/q' - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1-building-blocks.yaml#/components/parameters/type' - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1-building-blocks.yaml#/components/parameters/externalId' + - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1-building-blocks.yaml#/components/parameters/ids' - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/ogcapi-records-1-building-blocks.yaml#/components/parameters/sortby' responses: '200': diff --git a/core/openapi/ogcapi-records-1-example-ref-schema-repo.yaml b/core/openapi/ogcapi-records-1-example-ref-schema-repo.yaml index 88108aa3..3166a5c1 100644 --- a/core/openapi/ogcapi-records-1-example-ref-schema-repo.yaml +++ b/core/openapi/ogcapi-records-1-example-ref-schema-repo.yaml @@ -150,6 +150,7 @@ paths: - $ref: 'parameters/q.yaml' - $ref: 'parameters/type.yaml' - $ref: 'parameters/externalId.yaml' + - $ref: 'parameters/ids.yaml' - $ref: 'parameters/sortby.yaml' responses: '200': diff --git a/core/openapi/parameters/ids.yaml b/core/openapi/parameters/ids.yaml new file mode 100644 index 00000000..19100b2d --- /dev/null +++ b/core/openapi/parameters/ids.yaml @@ -0,0 +1,13 @@ +--- +name: ids +in: query +description: + The optional ids parameter allows a specified of records to be fetched + from a catalogue using their identifiers. +required: false +schema: + type: array + items: + type: string +explode: false +style: form diff --git a/core/standard/abstract_tests/ATS_class_searchable-catalog_crs.adoc b/core/standard/abstract_tests/ATS_class_searchable-catalog_crs.adoc deleted file mode 100644 index d80930cb..00000000 --- a/core/standard/abstract_tests/ATS_class_searchable-catalog_crs.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[ats_searchable-catalog_crs]] -[cols="1,4",width="90%"] -|=== -2+|*Conformance Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/crs -|Target type |Web API -|Dependency |<> -|Requirements class |<> -|=== - -==== CRS - -include::searchable-catalog_crs/ATS_crs.adoc[] diff --git a/core/standard/abstract_tests/searchable-catalog_crs/ATS_crs.adoc b/core/standard/abstract_tests/searchable-catalog_crs/ATS_crs.adoc deleted file mode 100644 index 50bf3223..00000000 --- a/core/standard/abstract_tests/searchable-catalog_crs/ATS_crs.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[[ats_crs]] -[width="90%",cols="2,6a"] -|=== -^|*Abstract Test {counter:ats-id}* |*/conf/searchable-catalog/crs* -^|Test Purpose |Validate CRS conformance identification. -^|Requirement |<> -^|Test Method |. Construct a path for a conformance page -. Issue an HTTP GET request on the path -. Check that the `+conformsTo+` array contains the value `+http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs+`. -. Check that the server implements http://docs.opengeospatial.org/is/18-058/18-058.html[OGC API - Feature - Part 2: Coordinate Reference Systems by Reference] -|=== - diff --git a/core/standard/annex_ats.adoc b/core/standard/annex_ats.adoc index f247f238..27087c6b 100644 --- a/core/standard/annex_ats.adoc +++ b/core/standard/annex_ats.adoc @@ -1,5 +1,6 @@ [appendix] :appendix-caption: Annex +[[annex_ats]] == Conformance Class Abstract Test Suite (Normative) === Conformance Class: Record Core @@ -50,7 +51,7 @@ include::abstract_tests/ATS_class_oas30.adoc[] include::abstract_tests/ATS_class_record-core-query-parameters.adoc[] -=== Conformance Class: Filtering using the Common Query Language (CQL) +=== Conformance Class: Filtering using the Common Query Language (CQL2) include::abstract_tests/ATS_class_record-filter.adoc[] @@ -62,14 +63,10 @@ include::abstract_tests/ATS_class_sorting.adoc[] include::abstract_tests/ATS_class_searchable-catalog.adoc[] -=== Conformance Class: Searchable Catalog CRS - -include::abstract_tests/ATS_class_searchable-catalog_crs.adoc[] - === Conformance Class: Searchable Catalog Filtering include::abstract_tests/ATS_class_searchable-catalog_filtering.adoc[] === Conformance Class: Searchable Catalog Sorting -include::abstract_tests/ATS_class_searchable-catalog_sorting.adoc[] \ No newline at end of file +include::abstract_tests/ATS_class_searchable-catalog_sorting.adoc[] diff --git a/core/standard/clause_0_front_material.adoc b/core/standard/clause_0_front_material.adoc index 6db1713a..13e26e05 100644 --- a/core/standard/clause_0_front_material.adoc +++ b/core/standard/clause_0_front_material.adoc @@ -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, requirements, domains or communities. +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 of interest. 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. @@ -43,7 +43,7 @@ The search API allows collections of records to be searched using logically conn [cols="25,35,10,20",options="header"] |=== |Resource |Path |HTTP method |Document reference -|Landing page |`/` |GET |<> +|Landing page |`/` |GET |https://docs.ogc.org/is/17-069r3/17-069r3.html#_api_landing_page[API landing page] |Conformance declaration |`/conformance` |GET |<> |Record collections |`/collections` |GET |<> |Record collection |`/collections/{collectionId}` |GET |<> @@ -51,7 +51,7 @@ The search API allows collections of records to be searched using logically conn |Record |`/collections/{collectionId}/items/{recordId}` |GET |<> |=== -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. +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 defined in an OGC API specification whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog that can be searched for records describing resources served by that API. [[keywords]] [big]*ii. Keywords* diff --git a/core/standard/clause_10_security.adoc b/core/standard/clause_10_security.adoc index 7fbe8d7d..1fb6ca6f 100644 --- a/core/standard/clause_10_security.adoc +++ b/core/standard/clause_10_security.adoc @@ -3,4 +3,4 @@ Given the dependencies on <> and <> and OGC API - Features and OGC API - Common, aspects of security are discussed in those specifications. -Metadata record encryption is out of scope for this specification, however communities who wish to implement record encryption are free to do so as needed. +Metadata record encryption is out of scope for this Standard, however communities who wish to implement record encryption are free to do so as needed. diff --git a/core/standard/clause_2_conformance.adoc b/core/standard/clause_2_conformance.adoc index 29d4a0d9..77d60143 100644 --- a/core/standard/clause_2_conformance.adoc +++ b/core/standard/clause_2_conformance.adoc @@ -3,7 +3,7 @@ === Overview -Conformance with this standard shall be checked using the tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to claim conformance, are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. +Conformance with this Standard shall be checked using the tests specified in <> of this document. The framework, concepts, and methodology for testing, and the criteria to claim conformance, are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. The standardization target of the conformance classes: @@ -17,7 +17,7 @@ The standardization target of the conformance classes: * <> * <> * <> -* <> +* <> * <> * <> * <> @@ -26,7 +26,7 @@ The standardization target of the conformance classes: * <> * <> * <> -* <> +* <> is "Web APIs". @@ -37,14 +37,14 @@ The standardization target of the conformance classes: is "Document encoding". -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 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]. +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 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 <> path on the <>. Each Conformance Class has an associated Requirements Class. The Requirements Classes define the functional requirements which will be tested through the associated Conformance Class. +The Conformance Classes implemented by an API are advertised through the <> path on the https://docs.ogc.org/is/17-069r3/17-069r3.html#_api_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 Test. [[building-block-requirements-classes]] === Building blocks -This standard also identifies nine (9) building block requirements classes: +This standard also identifies ten (10) building block requirements classes: * <> * <> @@ -54,6 +54,7 @@ This standard also identifies nine (9) building block requirements classes: * <> * <> * <> +* <> * <> The <> conformance class defines the requirements for the core schema of a catalog record which is a set of properties (<>) that can be used to make any resource discoverable via a catalog. This core set of properties can be extended as required by specific communities of interest and/or use cases. @@ -72,12 +73,14 @@ The <> conformance class defines the requ The <> conformance class defines the requirements for an HTML representation of a standard catalog record. -The <> conformance class defines requirements that allow catalogs associated with a web page or web site to be discovered. +The <<<> conformance class defines the requirements for server that use an http://spec.openapis.org/oas/v3.0.3#openapi-document[OpenAPI 3.0] document to define their API. + +The <> conformance class defines requirements that allow catalogs that conform to this Standard and are associated with a web page or web site to be automatically discovered. [[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: * <> * <> @@ -104,19 +107,20 @@ The <>, <> |_Optional_ |Mandatory |N/A |<> |N/A |_Mandatory_ |_Mandatory_ |<> |N/A |Mandatory |N/A -|<> |N/A_ |_Optional_ |_Optional_ -|<> |N/A |_Optional_ |_Optional_ +|<> |N/A |_Optional_ |_Optional_ +|<> |N/A |_Optional_ |_Optional_ |<> |_Optional_ |_Optional_ |_Optional_ |<> |_Optional_ |_Optional_ |_Optional_ +|<> |N/A |_Optional_ |_Optional_ |=== === Implementations -Implementors of this specification select one or more of the <> they wish to implement and then implement the required building block requirements classes. +Implementors of this Standard select one or more of the <> they wish to implement and then implement the required building block requirements classes. === Conformance testing -Conformance with this standard shall be checked using all the relevant tests +Conformance with this Standard shall be checked using all the relevant tests specified in <> of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the @@ -127,9 +131,9 @@ OGC Compliance Testing web site. [cols="30,70",options="header"] |=== |Conformance class |URI -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog-filtering +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog-filtering |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog-sorting |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog-filtering @@ -141,12 +145,12 @@ OGC Compliance Testing web site. [cols="30,70",options="header"] |=== |Conformance class |URI -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-api +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-api |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/filtering +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/filtering |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30 diff --git a/core/standard/clause_3_references.adoc b/core/standard/clause_3_references.adoc index 0ba1a5f2..56b1686a 100644 --- a/core/standard/clause_3_references.adoc +++ b/core/standard/clause_3_references.adoc @@ -6,33 +6,14 @@ The following normative documents contain provisions that, through reference in * [[rfc3339]] Klyne, G., Newman, C.: IETF RFC 3339, *Date and Time on the Internet: Timestamps*, https://tools.ietf.org/rfc/rfc3339.txt[RFC 3339] * [[rfc3986]] Berners-Lee, T., Fielding, R., Masinter, L.: IETF RFC 3986, *Uniform Resource Identifier (URI): Generic Syntax*, https://tools.ietf.org/html/rfc3986[RFC 3986] * [[rfc3987]] Duerst, M., Suignard, M.: IETF RFC 3987, *Internationalized Resource Identifiers (IRIs)*, https://tools.ietf.org/html/rfc3987[RFC 3987] -* [[rfc4287]] Nottingham, M., Sayre, R.: IETF RFC 4287, *The Atom Syndication Format*, https://tools.ietf.org/html/rfc4287[RFC 4287] * [[rfc6570]] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., Orchard, D.: IETF RFC 6570, *URI Template*, https://tools.ietf.org/html/rfc6570[RFC 6570] -* [[GeoJSON]] IETF RFC 7946: *The GeoJSON Format*, https://tools.ietf.org/rfc/rfc7946.txt[GeoJSON] +* [[rfc7159]] Bray, T.: IETF RFC 7159, *The JavaScript Object Notation (JSON) Data Interchange Format*, https://www.ietf.org/rfc/rfc7159.txt[RFC 7159] +* [[GeoJSON]] Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., Schaub, T.: IETF RFC 7946: *The GeoJSON Format*, https://tools.ietf.org/rfc/rfc7946.txt[RFC 7946] * [[rfc8288]] Nottingham, M.: IETF RFC 8288, *Web Linking*, https://tools.ietf.org/rfc/rfc8288.txt[RFC 8288] - -* [[OACommon]] OGC 19-072: *OGC API - Common Specification*, (Draft) https://github.com/opengeospatial/oapi_common[API Common] +* [[link-template]] Nottingham, M.: IETF, *The Link-Template HTTP Header Field*, https://ietf-wg-httpapi.github.io/link-template/draft-ietf-httpapi-link-template.html[draft-ietf-httpapi-link-template-latest] * [[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] +* [[OAFeat-3]] OGC 19-079: *OGC API - Features - Part 3: Filtering*, https://docs.ogc.org/DRAFTS/19-079r1.html +* [[CQL2]] OGC 21-065: *Common Query Language (CQL2)*, https://docs.ogc.org/DRAFTS/21-065.html +* [[OpenAPI]] Open API Initiative: *OpenAPI Specification 3.0.3*, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.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] -* [[RDF]] W3C, *RDF 1.1 Semantics*, February 2014, https://www.w3.org/TR/rdf11-mt/ -* [[xml]] W3C, *Extensible Markup Language (XML) 1.0 (Fifth Edition)*, November 2008, https://www.w3.org/TR/xml/ -* [[opensearch]] OASIS, https://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part4-opensearch/searchRetrieve-v1.0-os-part4-opensearch.html#_Toc313525766[searchRetrieve: Part 4. APD Binding for OpenSearch Version 1.0] -* OGC: OGC 07-036, Geography Markup Language (GML) Encoding Standard, version 3.2.1, 2007 -* OGC: OGC 10-129r1, OGC® Geography Markup Language (GML) – Extended schemas and encoding rules (GML 3.3), version 3.3, 2012 -* W3C: W3C Recommendation, XML Path Language (XPath), version 2, 2007 -* W3C: W3C Recommendation, XML Linking Language (XLink), version 1, 2001 -* W3C: W3C Working Draft, The app: URI scheme, 2013 -* ISO/IEC: ISO/IEC 19757-3:2006 Information technology – Document Schema Definition Languages (DSDL) – Part 3: Rule-based validation – Schematron, 2006 -* ISO 8601: ISO 8601:2004: Data elements and interchange formats — Information interchange — Representation of dates and times, https://www.iso.org/standard/40874.html, 2004 -* [[link-template]] IETF: https://ietf-wg-httpapi.github.io/link-template/draft-ietf-httpapi-link-template.html[draft-ietf-httpapi-link-template-latest] -* IETF: RFC 2183, 1997 -* IETF: RFC 2387, 1998 -* IETF: RFC 2392, 1998 -[18] IETF: RFC 3986, 2005 -[19] IETF: RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format https://www.ietf.org/rfc/rfc7159.txt, 2014 -* 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 diff --git a/core/standard/clause_4_terms_and_definitions.adoc b/core/standard/clause_4_terms_and_definitions.adoc index 4cb21f2f..0c73791c 100644 --- a/core/standard/clause_4_terms_and_definitions.adoc +++ b/core/standard/clause_4_terms_and_definitions.adoc @@ -1,5 +1,5 @@ == Terms and Definitions -This document uses the terms defined in Sub-clause 5 of https://docs.ogc.org/DRAFTS/19-072.html[OGC API - Common Part 1] (OGC 19-072), which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "shall" (not "must") is the verb form used to indicate a requirement to be strictly followed to conform to this standard. +This document uses the terms defined in Sub-clause 5 of https://docs.ogc.org/DRAFTS/19-072.html[OGC API - Common Part 1] (OGC 19-072), which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "shall" (not "must") is the verb form used to indicate a requirement to be strictly followed to conform to this Standard. For the purposes of this document, the following additional terms and definitions apply. diff --git a/core/standard/clause_5_conventions.adoc b/core/standard/clause_5_conventions.adoc index 688376aa..2d836125 100644 --- a/core/standard/clause_5_conventions.adoc +++ b/core/standard/clause_5_conventions.adoc @@ -4,17 +4,17 @@ The following conventions will be used in this document. Examples of conventions === Identifiers -The normative provisions in this standard are denoted by the URI `http://www.opengis.net/spec/ogcapi-records-1/1.0`. +The normative provisions in this Standard are denoted by the URI `http://www.opengis.net/spec/ogcapi-records-1/1.0`. All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base. === Examples -Most of the examples provided in this standard are encoded in JSON. JSON is chosen because it is widely understood by implementers and easy to include in a text document. This convention should NOT be interpreted as a requirement that JSON must be used. Implementers are free to use any format they desire as long as there is a Conformance Class for that format and the API advertises its support for the associated Conformance Class. +Most of the examples provided in this Standard are encoded in JSON. JSON is chosen because it is widely understood by implementers and easy to include in a text document. This convention should NOT be interpreted as a requirement that JSON must be used. Implementers are free to use any format they desire as long as there is a Conformance Class for that format and the API advertises its support for the associated Conformance Class. === Schema -OpenAPI 3.0 Schema objects are used throughout this standard to define the structure of resources. These schema are typically represented using YAML encoding. This convention is for the ease of the user. It does not prohibit the use of another schema language or encoding. Nor does it indicate that OpenAPI 3.0 Schema objects are required. Implementations should use a schema language and encoding appropriate for the format of the resource. Note that for property values in JSON for which `null` is not explicitly supported/required, server implementations are recommended to drop the property (as opposed to specifying the property with a value of `null`). +OpenAPI 3.0 Schema objects are used throughout this Standard to define the structure of resources. These schema are typically represented using YAML encoding. This convention is for the ease of the user. It does not prohibit the use of another schema language or encoding. Nor does it indicate that OpenAPI 3.0 Schema objects are required. Implementations should use a schema language and encoding appropriate for the format of the resource. Note that for property values in JSON for which `null` is not explicitly supported/required, server implementations are recommended to drop the property (as opposed to specifying the property with a value of `null`). === UML Notation @@ -22,7 +22,7 @@ Diagrams using the Unified Modelling Language (UML) adhere to the following conv * UML elements having a package name of “GML” are those defined in the UML model of GML 3.2.1 * UML elements having a package name of “SWE Common” are those defined in the UML model of SWE Common 2.0 -* UML elements not qualified with a package name, or with “CIS”, are those defined in this standard. +* UML elements not qualified with a package name, or with “CIS”, are those defined in this Standard. Further, in any class where an attribute name or association role name is identical to a name in some superclass the local definition overrides the superclass definition. @@ -40,8 +40,4 @@ UML diagrams and XML code fragments adhere to the namespace conventions shown in |dc |http://purl.org/dc/elements/1.1/ |Dublin core elements |dcat |http://www.w3.org/ns/dcat# |DCAT vocabulary |dct |http://purl.org/dc/terms/ |Dublin core terms -|gml |http://www.opengis.net/gml/3.2 |GML 3.2.1 -|gml33 |http://www.opengis.net/gml/3.3 |GML 3.3 -|os |http://a9.com/-/spec/opensearch/1.1/ |OpenSearch namespace -|xlink |http://www.w3.org/1999/xlink |XLink namespace |==== diff --git a/core/standard/clause_6_overview.adoc b/core/standard/clause_6_overview.adoc index 0ce7b050..d6b32c82 100644 --- a/core/standard/clause_6_overview.adoc +++ b/core/standard/clause_6_overview.adoc @@ -4,20 +4,20 @@ [[records-role]] === Role of OGC API - Records -Historically, catalogs have been used as large repositories of formal metadata like ISO 19115, ISO 19119, FGDC, etc. More recently, catalogs are migrating to a more distributed model where the metadata is closely coupled with the resource that it describes. A current example is STAC which relies on well-defined building blocks that can be integrated in different ways. +Historically, catalogs have been used as large repositories of formal metadata like ISO 19115, ISO 19119, FGDC, etc. More recently, catalogs are migrating to a more distributed model where the metadata is closely coupled with the resource that it describes. A current example is https://stacspec.org/en[STAC] which relies on well-defined building blocks that can be integrated in different ways. -Although OGC API - Records is built upon the legacy of CSW, its role in a modern SDI can be both: a large repository of metadata documents or a distributed catalog, with the ability to provide a static or dynamic capability. +Although OGC API - Records is built upon the legacy of CSW, its role in a modern spatial data infrastructure can be both: a large repository of metadata documents or a distributed catalog, with the ability to provide a static or dynamic capability. -In the modern scenario, the catalog records can be distributed and linked together so that they can be crawled or they can be harvested into a service endpoint to make them searchable. In addition, a searchable catalog can harvest not only a metadata document describing the resource but in some cases the resource itself (e.g. harvesting the collections object from an OGC API). The implications of this are subtle yet important. In the traditional cataloguing approach (e.g. based on CSW) a client could find the record and the record might include binding information to access the resource but that is pretty much it. Using the new approach, a client interacts more intimately with the catalog and the catalog becomes integral to the access to the resource. An example is the cloud native ecosystem: HTTP range requests to Cloud Optimized GeoTIFF (COG) data cannot be used properly unless there is a STAC item telling the client in what ranges the bands exists, thus the catalog becomes an integral component (discovery, evaluation) in the process of accessing a resource. +In the modern scenario, the catalog records can be distributed and linked together so that they can be crawled or they can be harvested into a service endpoint to make them searchable. In addition, a searchable catalog can harvest not only a metadata document describing the resource but in some cases the resource itself (e.g. harvesting the collections object from an OGC API). The implications of this are subtle yet important. In the traditional cataloging approach (e.g. based on CSW) a client could find the record and the record might include binding information to access the resource. Using the new approach, a client interacts more intimately with the catalog and the catalog becomes integral to the access to the resource. An example is the cloud native ecosystem: HTTP range requests to Cloud Optimized GeoTIFF (COG) data cannot be used properly unless there is a STAC item telling the client in what ranges the bands exists, thus the catalog becomes an integral component (discovery, evaluation) in the process of accessing a resource. [[general-overview]] === General The atomic unit of information in a catalog is the _record_. -A _catalog_ is a collection of _records_. The terms **collection of records** and **catalog** are used interchangeably in this specification. +A _catalog_ is a collection of _records_. The terms **collection of records** and **catalog** are used interchangeably in this Standard. -A record provides a summary description (metadata) of a resource that the provider of the resource wishes to make discoverable. The record schema defined in this specification includes a small number of properties that can be used to provide a summary description of any resource. It is anticipated, and encouranged, that this list of properties be extended to enhance the information content of a record as required by specific communities of interest and/or use cases. +A record provides a summary description (metadata) of a resource that the provider of the resource wishes to make discoverable. The record schema defined in this Standard includes a small number of properties that can be used to provide a summary description of any resource. It is anticipated, and encouranged, that this list of properties be extended to enhance the information content of a record as required by specific communities of interest and/or use cases. === Building blocks @@ -33,7 +33,7 @@ Using these building blocks a catalog can be deployed as: * a set of web-accessible records that can be crawled by a search engine crawler, using (for example) a web browser, or by using automated tools * a searchable catalog with records accessible through an API -A special use case of the _searchable catalog_ is the _**local resources catalog**_. The OGC API resource tree has a number of endpoints that provide lists of resources. Examples of such endpoints include the `/collections` and the `/processes` endpoints. One can readily imagine a large OGC API deployment with thousands of collections where the ability to search would enhance the client's interaction with the server. Using the building blocks defined in this specification, these endpoints can be extended to support catalog-like searching using filter expressions that may also include spatial and/or temporal predicates. OGC API endpoints extended in this way behave like a catalog of local resources. +A special use case of the _searchable catalog_ is the _**local resources catalog**_. The OGC API resource tree has a number of endpoints that provide lists of resources. Examples of such endpoints include the `/collections` and the `/processes` endpoints. One can readily imagine a large OGC API deployment with thousands of collections where the ability to search would enhance the client's interaction with the server. Using the building blocks defined in this Specification, these endpoints can be extended to support catalog-like searching using filter expressions that may also include spatial and/or temporal predicates. OGC API endpoints extended in this way behave like a catalog of local resources. [[record-schema-overview]] === Record Schema @@ -47,9 +47,9 @@ The choice of which properties to include in the set of core properties was prim * The http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#17[core catalog 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 Vocabulary (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 properties is readily available for any resource that is being made discoverable by the record. +It is expected that the information necessary to populate this core set of properties is readily available for any resource that is being made discoverable by a record. -It is anticipated that this _core_ set of properties will be extended to describe specific resource types (e.g. datasets, dataset series, Earth observation products, machine models, 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, expected and encouraged by this specification. +It is anticipated that this _core_ set of properties will be extended to describe specific resource types (e.g. datasets, dataset series, Earth observation products, machine models, 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, expected and encouraged by this Specification. Although this document does not mandate any particular encoding for a record, the document defines conformance classes for two encodings: @@ -60,7 +60,7 @@ Other encodings are allowed but are not described in this document. Accessing collections of records deployed as static files is described in the <> clause. -Accessing collections of records through the API defined in this document is described in the <> and <> sections. +Accessing collections of records through the API defined in this document is described in the <> clause. [[sc_record-collection-overview]] === Record collection (catalog) @@ -69,7 +69,7 @@ A record collection or catalog is an object that groups and describes a set of r Depending on the deployment pattern, the collection may provide a link to each individual record of the collection or a link to a search access point for retrieving subsets of records. -The core set of properties that may be used to describe a record collection or catalog include _id_, _type_, _title_, _description_, _extent_ and _links_. A complete definition of a record can be found in clause <>. It should be noted that this list of properties is very similar to the list of core properties defined for a <>. This is intentional since the record collection object can be considered a _record_ that describes a catalog. +The core set of properties that may be used to describe a record collection or catalog include _id_, _type_, _title_, _description_, _extent_ and _links_. A complete definition of a catalog can be found in clause <>. It should be noted that this list of properties is very similar to the list of properties defined for a <>. This is intentional since the record collection object can be considered a _record_ that describes a catalog resource. It is anticipated that this set of properties will be extended to enrich the information content of the collection metadata to suit specific needs. @@ -80,38 +80,38 @@ 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 catalog using a logically connected set of predicates that may include spatial and/or temporal predicates. -The Records API extends http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Core: Part 1] to: +The Records API extends http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] 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 <> so that a facade can be created over legacy services thus allowing them to participate in the new OGC API ecosystem. +. Provide functionality comparable to that of the http://docs.opengeospatial.org/is/12-176r7/12-176r7.html[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: +To facilitate access to records in a catalog, the https://docs.ogc.org/is/17-069r4/17-069r4.html[OGC API - Feature - Part 1: Core] standard has been: -* extended with <> at the `/collections/{collectionId}/items` endpoint, and -* constrained to a single <> (i.e. the <>). +* extended with <> at the `/collections/{collectionId}/items` endpoint, and +* constrained to a single information model (i.e. the <>). -<> summarizes the access paths and relation types defined in this standard. +<> summarizes the access paths and relation types defined in this Standard. [[records-paths]] [#record-api-paths,reftext='{table-caption} {counter:table-num}'] -.Record API Paths +.Records API Paths [width="90%",cols="40,^20,40",options="header"] |=== ^|**Path Template** ^|**Relation** ^|**Resource** 3+^|**Common** -|<> ||Landing page -|<> |`service-desc` or `service-doc` |API Description (optional) -|<> | `conformance` |Conformance Classes -|<> | `data` |Metadata describing the spatial collections available from this API. -|<> |`collection` |Metadata describing the collection which has the unique identifier `{collectionId}` +|https://docs.ogc.org/is/17-069r4/17-069r4.html#_api_landing_page[/] ||Landing page +|https://docs.ogc.org/is/17-069r4/17-069r4.html#_api_definition_2[/api] |`service-desc` or `service-doc` |API Description (optional) +|https://docs.ogc.org/is/17-069r4/17-069r4.html#_declaration_of_conformance_classes[/conformance] | `conformance` |Conformance Classes +|https://docs.ogc.org/is/17-069r4/17-069r4.html#_collections_[/collections] | `data` |Metadata describing the catalogs available from this API. +|<> |`collection` |Metadata describing the collection which has the unique identifier `{catalogId}` 3+^|**Records** -|<> |`items` |Search results based on querying the service for records satisfying 0..n query parameters. -|<> |`item` |Record of metadata which has the unique identifier `{recordId}`. +|<> |`items` |Search results based on querying the service for records satisfying 0..n query parameters. +|<> |`item` |Record of metadata which has the unique identifier `{recordId}`. |=== Where: -* `{collectionId}` = an identifier for a specific record collection (i.e. catalog identifier) +* `{catalogId}` = an identifier for a specific record collection (i.e. catalog identifier) * `{recordId}` = an identifier for a specific record within a collection [[api-behaviour-model-overview]] @@ -125,7 +125,7 @@ Discussion has shown that the API model also assumes underlying service and obje ==== Search -This specification defines three levels of search capability of increasing complexity and capability. +This Specification defines three levels of search capability of increasing complexity and capability. The first or core level of search capability is based on <> and thus supports: @@ -142,33 +142,15 @@ OGC API - Record extends these core search capabilities to include: The 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. https://fix.me[OGC API - Records - Part 2: OpenSearch] defines the requirements for a catalog that supports OpenSearch. -The third level of search capability, defined by the <>, supports complex filter expressions using a rich set of logically connected query predicates. +The third level of search capability, defined by the <> requirements class, supports complex filter expressions using a rich set of logically connected query predicates. [[dependencies-overview]] ==== Dependencies -The OGC API - Records standard is an extension of the https://www.ogc.org/standards/ogcapi-features[OGC API - Features] standard. - -An implementation of OGC API - Records must first satisfy the appropriate Requirements Classes from OGC API - Common and OGC API - Features. <>, identifies the OGC API - Common and OGC API - Features Requirements Classes which are applicable to each section of this Standard. Instructions on when and how to apply these Requirements Classes are provided in each section. - -[#req-mappings,reftext='{table-caption} {counter:table-num}'] -.Required OGC API - Common and OGC API - Features Requirements Classes -[width="90%",cols="2,6"] -|==== -^|*API - Record Section* ^|*OGC API - Common, OGC API - Features Requirements Class* -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/core -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/collections -|<>|<> -|<>|<> -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/oas30 -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/geojson -|<>| http://www.opengis.net/spec/ogcapi_common-1/1.0/req/html -|==== +The API defined in this Standard for accessing records from a searchable catalog is an extension of the https://docs.ogc.org/is/17-069r4/17-069r4.html[OGC API - Features - Part 1: Core Standard]. An implementation of searchable catalog API must first satisfy the appropriate Requirements Classes from https://docs.ogc.org/is/17-069r4/17-069r4.html[OGC API - Features - Part 1: Core]. <>, identifies these requirements. [#records-to-features,reftext='{table-caption} {counter:table-num}'] -.Required OGC API - Features Requirements Classes for Records Access +.Required OGC API - Features - Part 1: Core Requirements Classes for Records Access [width="90%"] |==== |*API - Features Requirements Classes* @@ -189,7 +171,7 @@ An implementation of OGC API - Records must first satisfy the appropriate Requir |==== [#record-to-features,reftext='{table-caption} {counter:table-num}'] -.Required OGC API - Features Requirements Classes for Record Access +.Required OGC API - Features - Part 1: Core Requirements Classes for Record Access [width="90%"] |==== |*API - Features Requirements Classes* diff --git a/core/standard/clause_7_building_blocks.adoc b/core/standard/clause_7_building_blocks.adoc index ed20a164..161071cd 100644 --- a/core/standard/clause_7_building_blocks.adoc +++ b/core/standard/clause_7_building_blocks.adoc @@ -26,8 +26,8 @@ It is anticipated that the schema of a record will be extended to describe speci Although this document does not mandate any particular encoding for a record, this document does define conformance classes for two encodings: -* a <> record encoding, and -* an <> encoding. +* a <> record encoding, and +* an <> encoding. Other encoding are allowed but are not described in this document. @@ -82,7 +82,7 @@ include::recommendations/record-core/PER_additional-properties-record.adoc[] [[sc_record_extensions]] ===== Record extensions -In tables <> and <> this standard defines a set of core properties for describing discoverable resources. It is anticipated that this set of core properties will be extended to suite specific use cases or requirements. For example, a catalog record may be extended to include additional properties from the https://semiceu.github.io/GeoDCAT-AP/releases/[GeoDCAT] vocabulary. The fact that a catalog record has been extended in this way can be advertised using the `conformsTo` member. The `conformsTo` member is a list of identifiers that indicate each extension used in a record. This specification does not define the specific identifiers that are used to identify specific extensions; it simply provides a place where these identifiers can be listed. +In <> and <> this Standard defines a set of core properties for describing discoverable resources. It is anticipated that this set of core properties will be extended to suite specific use cases or requirements. For example, a catalog record may be extended to include additional properties from the https://semiceu.github.io/GeoDCAT-AP/releases/[GeoDCAT] vocabulary. The fact that a catalog record has been extended in this way can be advertised using the `conformsTo` member. The `conformsTo` member is a list of identifiers that indicate each extension used in a record. This Specification does not define the specific identifiers that are used to identify specific extensions; it simply provides a place where these identifiers can be listed. include::recommendations/record-core/REC_record-extensions.adoc[] @@ -103,7 +103,7 @@ Records can have multiple properties that describe the temporal characteristics * Multiple temporal properties are sometimes used to describe different temporal characteristics of the resource(s) the record describes. For example, the time instant or interval when the information in the record is valid (sometimes called "valid time") and the time when the record was recorded in the catalog (sometimes called "transaction time"). Another example is the https://www.ogc.org/standards/om[Observations & Measurements standard], where an observation has multiple temporal properties including "phenomenon time", "result time" and "valid time". -This standard does not place any containts on the number of additional temporal properties that may be added to a record to characterize temporal aspects of the resource being described by a record. This can make it difficult for a naive client to recognize and utilize temporal information stored in the record. For this reason, this standard includes the `time` property in a record. This `time` member is set by the publisher of the record and describes characteristic temporal information (an instant or an internval) associated with the resource described by a record. This `time` member can thus be used by a naive clients without the need to inspect or undestand the schema of an extended record. The value of the `time` member is either `null` (no temporal information) or an object encoding a time instant or interval. +This standard does not place any containts on the number of additional temporal properties that may be added to a record to characterize temporal aspects of the resource being described by a record. This can make it difficult for a naive client to recognize and utilize temporal information stored in the record. For this reason, this Standard includes the `time` property in a record. This `time` member is set by the publisher of the record and describes characteristic temporal information (an instant or an internval) associated with the resource described by a record. This `time` member can thus be used by a naive clients without the need to inspect or undestand the schema of an extended record. The value of the `time` member is either `null` (no temporal information) or an object encoding a time instant or interval. .Properties of the "time" object [cols="20,10a,70a",options="header"] @@ -268,7 +268,7 @@ include::requirements/record-core/REQ_record-license.adoc[] A record must contain a `links` section and may contain a <> section. These sections contain navigation links and/or association links. -Navigation links are meant to encode relationships between catalog entities (i.e. <> and <>). Navigation links in the `links` section can include links to the collection (`rel="collection`) of which a record is a member, alternative representations (`rel="alternate"`) of the record, and -- in the context of an API -- navigation links to previous (`rel="prev"`) or next (`rel="next"`) records in a chain of records. Links in the `links` section may also be used to organize records in a hierarchy (`rel="root"`, `rel="parent"`, `rel="child`). +Navigation links are meant to encode relationships between catalog entities (i.e. <> and <>). Navigation links in the `links` section can include links to the collection (`rel="collection`) of which a record is a member, alternative representations (`rel="alternate"`) of the record, and -- in the context of an API -- navigation links to previous (`rel="prev"`) or next (`rel="next"`) records in a chain of records. Links in the `links` section may also be used to organize records in a hierarchy (`rel="root"`, `rel="parent"`, `rel="child`). include::requirements/record-core/REQ_record-links.adoc[] @@ -292,7 +292,7 @@ In some instances additional context may be desirable or required in order to ac include::recommendations/record-core/REC_record-associations_templated.adoc[] -NOTE: This specification does not define any specific link relations that should be used for links in the `links` or <> sections. Such relationships are typically domain specific and so it is left to communities of interest to standardize the relations that links should use. +NOTE: This Specification does not define any specific link relations that should be used for links in the `links` or <> sections. Such relationships are typically domain specific and so it is left to communities of interest to standardize the relations that links should use. The following provides an example of using association links for related resources of a record, as both traditional links as well as link templates. @@ -320,7 +320,7 @@ Consider the case where a record describing a coverage resource is discovered by Templated links may also be used to bind to resources that may require additional information in order to access the resources. For example, simply knowing the URL of a legacy OGC service such as https://portal.ogc.org/files/?artifact_id=14416[WMS] or https://docs.ogc.org/is/09-025r2/09-025r2.html[WFS] is not sufficient to access resources offered by those services. Additional information in the form of request parameters and values are required in order to have a complete link to a resource. A templated link with variables can provide this additional context. -This specification defines a new schema, https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/linkTemplate.yaml[linkTemplate.yaml], based on the https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json[schema for a link] that includes substitution variables who's values are filled in at runtime prior to resolving the link. +This Specification defines a new schema, https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/linkTemplate.yaml[linkTemplate.yaml], based on the https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[schema for a link] that includes substitution variables who's values are filled in at runtime prior to resolving the link. Information about the substitution variables can be obtained in one of two ways. The `variable` property may be used to encode the definitions of substitution variables in-line in the link. Alternatively, the `varBase` property can be used to specify a base URI to which a variable name may be appended in order to retrieve the definition of the specified substitution variable. @@ -328,7 +328,7 @@ include::requirements/record-core/REQ_templated-link.adoc[] include::recommendations/record-core/REC_templated-link.adoc[]  -::requirements/record-core/REQ_templated-link-header.adoc[] +include::requirements/record-core/REQ_templated-link-header.adoc[]  following example illustrates a link template to a legacy OGC Web service. The example includes both an in-line and referenced dictionaries of substitution variables.  @@ -376,7 +376,7 @@ include::../examples/json/templated-link-ref.json[] ===== Resource timestamps -A <> contains information, encoded in the links and link templates sections, for accessing one or more resources described by the record. Since a resource may have multiple representations there may be multiple links pointing to each represention of a resource. Furthermore, representations of a resource may be created and updated at different times. In order to capture this life cycle information of resource representations, the https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/link.yaml[link schema] is extended with the addition of two properties named `created` and `updated`. The values of these properties are used to indicate the creation and last updated dates of the resource representation pointed to by the link. +A <> contains information, encoded in the links and link templates sections, for accessing one or more resources described by the record. Since a resource may have multiple representations there may be multiple links pointing to each represention of a resource. Furthermore, representations of a resource may be created and updated at different times. In order to capture this life cycle information of resource representations, the https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[link schema] is extended with the addition of two properties named `created` and `updated`. The values of these properties are used to indicate the creation and last updated dates of the resource representation pointed to by the link. [[sc_record_language_handling]] ===== Language handling @@ -393,7 +393,7 @@ A catalog record can include language information about: include::recommendations/record-core/REC_record-lang.adoc[] -The https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/link.yaml[link object] and the https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/linkTemplated.yaml[templated link object] are based on https://docs.ogc.org/is/17-069r4/17-069r4.html#rfc8228[RFC 8288 (Web Linking)] includes a `hreflang` attribute that can be used to state the language of a referenced resource. This can be used to include links to the same record in different languges. +The https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[link object] and the https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/linkTemplate.yaml[templated link object] are based on https://datatracker.ietf.org/doc/html/rfc8288[RFC 8288 (Web Linking)] includes a `hreflang` attribute that can be used to state the language of a referenced resource. This can be used to include links to the same record in different languges. [[minting-language-specific-uris]] A server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs in order to express links to the same record in other languages or to express links to the resource described by record in multiple languages. This document does not mandate any particular approach how such a capability is supported by a server. @@ -404,7 +404,7 @@ Two common approaches are: * an additional path element for each language-specific encoding of a record or resource (this can be expressed, for example, using a language-specific path element like `.../en-ca/...`); -* an additional query parameter (for example, https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/parameter/language.yaml["language"] or "l") that overrides the Accept-Language header of the HTTP request. +* an additional query parameter (for example, https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/parameters/language.yaml["language"] or "l") that overrides the Accept-Language header of the HTTP request. ====================================================================== [NOTE] @@ -430,12 +430,12 @@ 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 <> 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 - Part 1: Core] defines a specific location for the collection resource (path: `/collections/{collectionId}`), OGC API - Records only fixes the location of the collection in the <> 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). Although this document does not mandate any particular encoding for a record collection, two define conformance classes are defined: -* a <> record encoding, and -* an <> encoding. +* a <> record encoding, and +* an <> encoding. Other encodings are allowed but are not described in this document. @@ -469,7 +469,7 @@ Other encodings are allowed but are not described in this document. |rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. |=== -NOTE: The properties _id_, _title_, _description_, _links_, _extent_, _itemsType_ and _crs_ were inherited from http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features]. +NOTE: The properties _id_, _title_, _description_, _links_, _extent_, _itemsType_ and _crs_ were inherited from http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features - Part 1: Core]. include::requirements/record-collection/REQ_mandatory-properties.adoc[] @@ -501,7 +501,7 @@ include::recommendations/record-collection/REC_record-langs.adoc[] ==== Encodings -This specification defines requirements for JSON and HTML encoding of a catalog. See <>. +This Specification defines requirements for JSON and HTML encoding of a catalog. See <>. [[clause-record-core-query-parameters]] === Requirements Class "Record Core Query Parameters" (Building Block) @@ -513,7 +513,7 @@ include::requirements/requirements_class_record-core-query-parameters.adoc[] This conformance class defines a minimum core set of query parameters that shoule be implemented at an searchable catalog endpoint. The <> lists this minimum set of query parameters. -The parameters `bbox`, `datetime`, `limit` and `ids` are inherited from https://docs.opengeospatial.org/is/17-069r4/17-069r4.html[OGC API Features - Part 1: Core]. The remaining parameters are defined in this standard. +The parameters `bbox`, `datetime`, `limit` and `ids` are inherited from https://docs.opengeospatial.org/is/17-069r4/17-069r4.html[OGC API Features - Part 1: Core]. The remaining parameters are defined in this Standard. [#core-query-parameters-table,reftext='{table-caption} {counter:table-num}'] .Table of Core Query Parameters @@ -548,11 +548,11 @@ include::requirements/record-core-query-parameters/REQ_query-param-limit.adoc[] [[core-query-parameters-q]] ===== Parameter q -The `q` parameter is meant to provide a simple, easy-to-implement keyword search capability across one or more text fields in a record. +The `q` parameter provides a simple, easy-to-implement keyword search capability across one or more text fields in a record. include::requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc[] -The specific text fields in a record that are to be searched is not mandated in this standard. +The specific text fields in a record that are to be searched is not mandated in this Standard. include::recommendations/record-core-query-parameters/REC_param-q.adoc[] @@ -574,9 +574,9 @@ represents the query predicate: NOTES: -* The term `anytext` is meant to represent the set of text fields that are searched by the operation. -* The `CONTAINS` operator used above is just an example of an operator that searches a text field(s) for specific search terms. How this operator is implemented and what it is named in the system backing a catalog implementation is beyond the scope of this standard. -* The regular expression `\s+` is meant to represent one or more white spaces. +* The term `anytext` represents the set of text fields that are searched by the operation. +* The `CONTAINS` operator used above is just an example of an operator that searches a text field(s) for specific search terms. How this operator is implemented and what it is named in the system backing a catalog implementation is beyond the scope of this Standard. +* The regular expression `\s+` represents one or more white spaces. [[core-query-parameters-type]] ===== Parameter type @@ -640,7 +640,7 @@ include::recommendations/records-api/REC_html.adoc[] include::recommendations/records-api/REC_json.adoc[] -The requirements specified in the <> sub-clause imply that the encoding of a server response is determined using content negotiation as specified by the HTTP RFC. +The encoding of a server response is determined according to the mechanisms defined in https://www.rfc-editor.org/rfc/rfc2616#section-12[Clause 12] of the https://www.rfc-editor.org/rfc/rfc2616[HTTP 1.1] Standard. The <> sub-clause includes guidance on media types for encodings that are specified in this document. @@ -690,8 +690,8 @@ Any combination of query parameters from the <> -|HTML |<> +|JSON/GeoJSON |<> +|HTML |<> |=== ===== Examples @@ -763,7 +763,7 @@ include::recommendations/sorting/REC_sortables-schema.adoc[] In an OpenAPI 3.0 document, the Sortables resource 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 sortable properties (Sortables.yaml)] +.link:https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/responses/Sortables.yaml[Schema for the list of sortable properties (Sortables.yaml)] [source,YAML] ---- include::../openapi/responses/Sortables.yaml[] @@ -771,7 +771,7 @@ include::../openapi/responses/Sortables.yaml[] ==== Declaring default sort order -This specification does not mandate a specific default sort order for records +This Specification does not mandate a specific default sort order for records fetched from a searchable catalog. However, servers can declare a default sort order. @@ -817,7 +817,7 @@ include::../examples/json/sortables.json[] include::requirements/requirements_class_record-filter.adoc[] -This clause defines the binding to the filter parameters defined in the https://docs.ogc.org/DRAFTS/19-079.html#_requirements_class_filter[OGC API - Features - Part 3: Filtering and the Common Query Language (CQL), Requirements Class "Filter"] clause. +This clause defines the binding to the filtering parameters defined in the https://docs.ogc.org/DRAFTS/19-079r1.html#_requirements_class_filter[OGC API - Features - Part 3: Filtering] and the use of the https://docs.ogc.org/DRAFTS/21-065.html[Common Query Language (CQL2)] as the query language. ==== Records @@ -855,7 +855,7 @@ Links can be added to the following sections in a catalog record: . the <> section, . the <> section. -The schema for links added to the <> and <> sections is based on https://tools.ietf.org/html/rfc8288[RFC 8288] and is described in https://docs.ogc.org/DRAFTS/19-072.html#link-relation-conventions[OGC API - Common - Part 1: Core] and http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[OGC API - Features - Part 1: Core]. +The schema for links added to the <> and <> sections is based on https://tools.ietf.org/html/rfc8288[RFC 8288] and is described in http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[OGC API - Features - Part 1: Core]. Links added directly to the <> section of a catalog record can be added using the following patterns: @@ -1030,7 +1030,7 @@ include::recommendations/autodiscovery/PER_autodiscovery_links.adoc[] include::requirements/requirements_class_json.adoc[] -[[clause-record-encoding]] +[[clause-record-encoding-json]] ===== Record encoding GeoJSON is a commonly used format base on JSON that is simple to understand and well supported by tools and software libraries. Since most Web developers are comfortable with using a JSON-based format supporting GeoJSON is recommended, if record data can be represented in GeoJSON for the intended use. @@ -1070,13 +1070,13 @@ include::requirements/json/REQ_collection-response.adoc[] include::requirements/json/REQ_collection-content.adoc[] [[schema_json_collection]] -.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[Schema for a catalog or record collection in JSON(catalog.yaml)] +.link:https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/catalog.yaml[Schema for a catalog or record collection in JSON(catalog.yaml)] [source,YAML] ---- include::../openapi/schemas/catalog.yaml[] ---- -NOTE: Referenced schemas can be found at http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml[collection.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/confClasses.yaml[confClasses.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/language.yaml[language.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/theme.yaml[theme.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/contact.yaml[contact.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/license.yaml[license.yaml]. +NOTE: Referenced schemas can be found at http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml[collection.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/language.yaml[language.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/theme.yaml[theme.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/contact.yaml[contact.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/license.yaml[license.yaml]. [[requirements-class-html-clause]] ==== Requirements Class HTML (Building Block) @@ -1105,3 +1105,14 @@ include::requirements/html/REQ_content.adoc[] include::recommendations/html/REC_schema-org.adoc[] +[[clause-oas30]] +=== Requirements Class "OpenAPI 3.0" (Building Block) + +==== Basic requirements + +Servers conforming to this requirments class define their API using an +http://spec.openapis.org/oas/v3.0.3#openapi-document[OpenAPI Document]. + +include::requirements/oas30/REQ_oas30.adoc[] + +include::requirements/oas30/REQ_oas-conformance.adoc[] diff --git a/core/standard/clause_8_deployments.adoc b/core/standard/clause_8_deployments.adoc index 52941a01..204ae1ba 100644 --- a/core/standard/clause_8_deployments.adoc +++ b/core/standard/clause_8_deployments.adoc @@ -3,7 +3,7 @@ === Overview -This clause uses the <> defined in this standard to define various catalog deployments. +This clause uses the <> defined in this Standard to define various catalog deployments. [[clause-crawlable-catalog]] === Requirements Class "Crawlable Catalog" (Deployment) @@ -17,18 +17,18 @@ The `Crawlable Catalog` Requirements Class defines the requirements for a catalo The goal of a crawlable catalog is to expose metadata about resources online with as low an entry barrier as possible, thus making those resource more easily discoverable. -A crawlable catalog is a deployment pattern that uses the <> and <> building blocks defined in this standard. It is simply a set of files deployed on the web that encode, usually in HTML or JSON, the <> and <> defined in this standard. The files contain embedded links to enable navigation from one to another. Any HTTP server or cloud storage service, for example, could be used to expose the files of a crawlable catalog. +A crawlable catalog is a deployment pattern that uses the <> and <> building blocks defined in this Standard. It is simply a set of files deployed on the web that encode, usually in HTML or JSON, the <> and <> defined in this Standard. The files contain embedded links to enable navigation from one to another. Any HTTP server or cloud storage service, for example, could be used to expose the files of a crawlable catalog. A crawlable catalog is not searchable and does not respond to query requests. As the name implies, it can only be crawled (or harvested) by following the embedded links; typically by search engines and other active catalogs or browsed using a web browser. However, due to its simplicity, a crawlable catalog is easy to deploy and maintain, and is very reliable. -NOTE: It should be pointed out that a <> can also behave as a crawlable catalog as long as the requirements in this clause are satisfied by the <> implementation. +NOTE: It should be pointed out that a <> can also behave as a crawlable catalog as long as the requirements in this clause are satisfied by the <> implementation. [[crawlable-catalog-record]] ==== Making a resource discoverable include::requirements/crawlable-catalog/REQ_record.adoc[] -Attention is drawn to requirement <> that allows the information content of the record to be enriched as required to describe the resource being made discoverable. +Attention is drawn to requirement <> that allows the information content of the record to be enriched as required to describe the resource being made discoverable. include::requirements/crawlable-catalog/REQ_record-links.adoc[] @@ -52,7 +52,7 @@ include::requirements/crawlable-catalog/REQ_catalog-links.adoc[] [[crawlable-collections]] ==== Grouping catalogs (and other resources) into collections -In order to provide flexibility with regard to how crawlable catalogs can be organized (e.g. a hierarchy) the same catalog object (see: http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[catalog.yaml]) used to organized related collections of records into a catalog may also be used as a common entry point for crawling to multiple, related, sub-collections, catalogs, records and other resources. In this use case, the term _collection_ is used to refer to a http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[catalog object]. +In order to provide flexibility with regard to how crawlable catalogs can be organized (e.g. a hierarchy) the same catalog object (see: https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/catalog.yaml[catalog.yaml]) used to organized related collections of records into a catalog may also be used as a common entry point for crawling to multiple, related, sub-collections, catalogs, records and other resources. In this use case, the term _collection_ is used to refer to a https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/catalog.yaml[catalog object]. include::requirements/crawlable-catalog/REQ_collection.adoc[] @@ -103,10 +103,6 @@ include::requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc include::recommendations/searchable-catalog_filtering/PER_additional-queryables.adoc[] -===== Coordinate reference systems - -include::requirements/searchable-catalog_crs/REQ_crs.adoc[] - [[clause-local-resources-catalog]] === Requirements Class "Local Resources Catalog" (Deployment) @@ -118,7 +114,7 @@ include::requirements/requirements_class_local-resources-catalog.adoc[] This conformance class specifies requirements for a _local resources catalog_. The OGC API defines a number of resource endpoints that provide lists of -sub-resources. These endpoints are referred to as _local resources catalogs_ in this standard because they provide metadata about resources offered locally by an OGC API deployment. +sub-resources. These endpoints are referred to as _local resources catalogs_ in this Standard because they provide metadata about resources offered locally by an OGC API deployment. NOTE: The term _local resources endpoint_ is used to reference to the resource path of the _local resources catalog_. The term _local resources object_ is used to refer to an instance of the object or resource that can be retrieved from the _local resources endpoint_. diff --git a/core/standard/clause_9_media_types.adoc b/core/standard/clause_9_media_types.adoc index 53029e1d..99badc34 100644 --- a/core/standard/clause_9_media_types.adoc +++ b/core/standard/clause_9_media_types.adoc @@ -6,13 +6,13 @@ This standard does not mandate any particular encoding or format. However, it do * <> * <> -None of these encodings are mandatory. An implementer of this standard may choose to implement none of them, selecting different encodings instead. +None of these encodings are mandatory. An implementer of this Standard may choose to implement none of them, selecting different encodings instead. === HTML Encoding Support for HTML is recommended. HTML is the core language of the World Wide Web. An API that supports HTML will support browsing the spatial resources with a web browser and will also enable search engines to crawl and index those resources. === Schema Encoding -Schema structures documented in this standard are defined using OpenAPI 3.0 Schema objects. These are available in YAML format from http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas[http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas] +Schema structures documented in this Standard are defined using OpenAPI 3.0 Schema objects. These are available in YAML format from http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas[http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas] === JSON Encoding Support for JSON is recommended. JSON is a commonly used format that is simple to understand and well supported by numerous tools and software libraries. diff --git a/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc b/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc index 059d6bf5..79ce0683 100644 --- a/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc +++ b/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc @@ -3,6 +3,6 @@ |=== ^|*Permission {counter:per-id}* |*/per/crawlable-catalog/additional-collection-properties* -^|A |A collection MAY contain zero or more of the optional properties listed in <>. -^|B |A collections MAY contain any number of additional properties not listed in <>. The meaning of these additional properties is not specified in this document. +^|A |A collection MAY contain zero or more of the optional properties listed in <>. +^|B |A collections MAY contain any number of additional properties not listed in <>. The meaning of these additional properties is not specified in this document. |=== diff --git a/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc b/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc index 96401700..c8788fda 100644 --- a/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc +++ b/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc @@ -3,5 +3,5 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/filtering/cql2-JSON-encoding* -If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-json[CQL JSON] encoding. +If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/21-065.html#cql2-json[CQL JSON] encoding. |=== diff --git a/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc b/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc index b1d8fcb9..8a4c05e5 100644 --- a/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc +++ b/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc @@ -3,5 +3,5 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/filter/cql2-text-encoding* -If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-text[CQL text] encoding. +If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/21-065.html#cql2-text[CQL text] encoding. |=== diff --git a/core/standard/recommendations/record-filter/REC_json-encoding.adoc b/core/standard/recommendations/record-filter/REC_json-encoding.adoc index 1ffb5252..4a48f4f1 100644 --- a/core/standard/recommendations/record-filter/REC_json-encoding.adoc +++ b/core/standard/recommendations/record-filter/REC_json-encoding.adoc @@ -2,5 +2,5 @@ [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/record-filtering/cql2-JSON-encoding* -^|A |If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-json[CQL JSON] encoding. +^|A |If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/21-065.html#cql2-json[CQL JSON] encoding. |=== diff --git a/core/standard/recommendations/record-filter/REC_text-encoding.adoc b/core/standard/recommendations/record-filter/REC_text-encoding.adoc index aa62f891..df9b2958 100644 --- a/core/standard/recommendations/record-filter/REC_text-encoding.adoc +++ b/core/standard/recommendations/record-filter/REC_text-encoding.adoc @@ -2,5 +2,5 @@ [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/record-filtering/cql2-text-encoding* -^|A |If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-text[CQL text] encoding. +^|A |If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/21-065.html#cql2-text[CQL text] encoding. |=== diff --git a/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc b/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc index 3409359b..e1efe3da 100644 --- a/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc +++ b/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc @@ -1,7 +1,7 @@ -[[per_core_additional-properties]] +[[per_searchable-catalog_additional-properties]] [width="90%",cols="2,6a"] |=== -^|*Permission {counter:per-id}* |*/per/core/additional-properties* +^|*Permission {counter:per-id}* |*/per/searchable-catalog/additional-properties* In addition to the properties listed in <> and <> servers may add any number of additional properties to the schema of a record. |=== diff --git a/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc b/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc index ee9f553c..0399b0ba 100644 --- a/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc +++ b/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc @@ -1,8 +1,8 @@ -[[per_core_additional-conformance]] +[[per_searchable-catalog_additional-conformance]] [width="90%",cols="2,6a"] |=== -^|*Permission {counter:per-id}* |*/per/core/additional-conformance* -2+|Implementation of this conformance MAY, additionally, implement the following requirements: +^|*Permission {counter:per-id}* |*/per/searchable-catalog/additional-conformance* +2+|Implementations of this conformance class MAY, additionally, implement the following requirements: ^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering ^|B |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting ^|C |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json diff --git a/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc b/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc index 1753df04..c3df2379 100644 --- a/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc +++ b/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc @@ -6,6 +6,6 @@ ^|A |A web page SHALL include a link that points to a catalog associated with that page. ^|B |The link SHALL include a `rel` attribute with the value `http://www.opengis.net/def/rel/ogc/1.0/catalog`. ^|C |The link SHALL include a `type` attribute. -^|D |The value of the `type` attribute SHALL indicate the media type of the catalog resource (see: <>, <>. +^|D |The value of the `type` attribute SHALL indicate the media type of the catalog resource (see: <>, <>). ^|E |The link SHALL include a `href` attribute whose value is the URI of the catalog. |=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_record.adoc b/core/standard/requirements/crawlable-catalog/REQ_record.adoc index 0dad0ca4..42ce2d25 100644 --- a/core/standard/requirements/crawlable-catalog/REQ_record.adoc +++ b/core/standard/requirements/crawlable-catalog/REQ_record.adoc @@ -3,5 +3,5 @@ |=== ^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/record* -A <> SHALL be created for each resource to be made discoverable. +A <> SHALL be created for each resource to be made discoverable. |=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc index 7485eeef..85d7ac16 100644 --- a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc @@ -2,7 +2,7 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/filtering/filter-crs-param* -^|Condition |Server implements <> +^|Condition |Server implements https://docs.ogc.org/is/18-058r1/18-058r1.html[OGC API - Features - Part 2: Coordinate Reference Systems by Reference] Implementations of this conformance class SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter-crs` parameter as defined by the <>. |=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc index 7b1df757..b6dfa7a2 100644 --- a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc @@ -3,5 +3,5 @@ |=== ^|*Requirement {counter:req-id}* |*/req/features-filter/filtering/filter-param* -Implementations SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter` parameter as defined by the <> building block. +Implementations SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter` parameter as defined by the <> building block. |=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc index 6c8f5f03..7e373d36 100644 --- a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc @@ -4,7 +4,7 @@ ^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/filtering/filter-response* ^|A |A filter expression SHALL be evaluated for each local resources object at the local resources endpoint. -^|B |All other filtering parameters specified (i.e. zero or more of <>, <>, <>, <>, <> and any <>) SHALL be evaluated for each local resources object at the local resources endpoint. +^|B |All other filtering parameters specified (i.e. zero or more of <>, <>, <>, <>, <> and any <>) SHALL be evaluated for each local resources object at the local resources endpoint. ^|C |If the filter expression AND all other specified filtering parameters (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluate to `TRUE` then the local resources object SHALL be included in the result. ^|D |If the filter expression OR any other specified filtering parameter (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluates to `FALSE` then the local resources object SHALL be excluded from the result. |=== diff --git a/core/standard/requirements/oas30/REQ_oas-common.adoc b/core/standard/requirements/oas30/REQ_oas-common.adoc deleted file mode 100644 index 369c94ab..00000000 --- a/core/standard/requirements/oas30/REQ_oas-common.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_oas30_oas-common]] -[width="90%",cols="2,6"] -|=== -^|*Requirement {counter:req-id}* |*/req/oas30/oas-common* -^|**Extends** |/req/core/api-common -^|A |The API SHALL demonstrate conformance with the following Requirements Class of the OGC API - Common version 1.0 Standard. http://www.opengis.net/spec/ogcapi-common-1/1.0/req/oas30. -|=== diff --git a/core/standard/requirements/oas30/REQ_oas-conformance.adoc b/core/standard/requirements/oas30/REQ_oas-conformance.adoc index 298eea8e..edc7b678 100644 --- a/core/standard/requirements/oas30/REQ_oas-conformance.adoc +++ b/core/standard/requirements/oas30/REQ_oas-conformance.adoc @@ -3,5 +3,5 @@ |=== ^|*Requirement {counter:req-id}* |*/req/oas30/conformance* 2+|The list of Conformance Classes advertised by the API SHALL include: -^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30 +^|A |http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30 |=== diff --git a/core/standard/requirements/oas30/REQ_oas30.adoc b/core/standard/requirements/oas30/REQ_oas30.adoc new file mode 100644 index 00000000..a3ef1eee --- /dev/null +++ b/core/standard/requirements/oas30/REQ_oas30.adoc @@ -0,0 +1,7 @@ +[[req_oas30_oas-common]] +[width="90%",cols="2,6"] +|=== +^|*Requirement {counter:req-id}* |*/req/oas30/oas-common* +^|**Extends** |/req/core/api-common +^|A |The API SHALL demonstrate conformance to the https://docs.ogc.org/is/17-069r4/17-069r4.html#_requirements_class_openapi_3_0[OpenAPI 3.0] requirements class of the https://docs.ogc.org/is/17-069r4/17-069r4.html[OGC API - Feature - Part 1: Core] Standard. +|=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc index a8164649..688f57a8 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/ids-definition* ^|A |A Records API SHALL support the query by Ids (`ids`) parameter for the operation. -^|B |The characteristics of the `ids` parameter SHALL be as defined by requirement http://fix.em[`req/ids/fc-ids-definition`] of the http://fix.me[OGC API - Features - Part X: Title Unknown] standard. The definition is copied here for convenience. NOTE: fix reference/URL +^|B |The following OpenAPI 3.0 schema fragment SHALL define the characteristics of the `ids` parameter: [source,YAML] ---- @@ -15,6 +15,7 @@ schema: items: type: string explode: false +style: form ---- ^|C |An empty list of identifiers is a valid value for the `ids` parameter and indicates that the result set SHALL be empty. diff --git a/core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc b/core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc deleted file mode 100644 index b5016cd4..00000000 --- a/core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_searchable-catalog_crs]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalog/crs* -2+|Implementations of this conformance class SHALL implement the following conformance class from http://docs.opengeospatial.org/is/18-058/18-058.html[OGC API - Feature - Part 2: Coordinate Reference Systems by Reference]: -^|A |http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs -|=== diff --git a/core/standard/requirements/sorting/REQ_get-sortables-success.adoc b/core/standard/requirements/sorting/REQ_get-sortables-success.adoc index 526e12e1..42aeac93 100644 --- a/core/standard/requirements/sorting/REQ_get-sortables-success.adoc +++ b/core/standard/requirements/sorting/REQ_get-sortables-success.adoc @@ -3,13 +3,20 @@ |=== ^|*Requirement {counter:req-id}* |*/req/sorting/get-sortables-success* -^|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: +^|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: * 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 sortable. +* The property `$schema` is `\https://json-schema.org/draft/2019-09/schema` +or `\https://json-schema.org/draft/2020-12/schema`. +* The property `$id` is the URI of the resource without query parameters. +* The `type` is `object` and each property is a queryable. + +^|C |Each property SHALL include a `type` member, except for spatial properties. +^|D |Each spatial property SHALL not include a `type` or `$ref` member. +^|E |Each spatial property SHALL include a `format` member with a string value "geometry", followed by a hyphen, followed by the name of the geometry type in lower case with "any" as the wildcard for any geometry type. I.e., the values for the Simple Feature geometry types are: `geometry-any`, `geometry-point`, `geometry-multipoint`, `geometry-linestring`, `geometry-multilinestring`, `geometry-polygon`, `geometry-multipolygon`, and `geometry-geometrycollection`. +^|F |If included, the `additionalProperties` member SHALL have a value of `false`. |===