diff --git a/core/examples/README.md b/core/examples/README.md index 2b727e5b..fa462108 100644 --- a/core/examples/README.md +++ b/core/examples/README.md @@ -3,5 +3,5 @@ The sub-folders contain examples of responses of implementations of OGC API - Records - Part 1: Core. -* [OpenAPI examples](openapi) * [JSON/GeoJSON examples](json) +* [YAML examples](yaml) diff --git a/core/examples/json/templated-link-ref.json b/core/examples/json/templated-link-ref.json index 998ca5af..5587da0a 100644 --- a/core/examples/json/templated-link-ref.json +++ b/core/examples/json/templated-link-ref.json @@ -3,5 +3,5 @@ "type": "image/png", "title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations", "uriTemplate": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}&bbox={bbox}&layers=stations&width={width}&height={height}&format=image/png", - "varBase": "https://www.someserver.com/variables/" + "varBase": "https://example.org/variables/" } diff --git a/core/standard/20-004.adoc b/core/standard/20-004.adoc index cdb7b7fa..05a993a7 100644 --- a/core/standard/20-004.adoc +++ b/core/standard/20-004.adoc @@ -29,7 +29,7 @@ |Internal reference number of this OGC(R) document: 20-004 |Version: 1.0.0-oab-review.1 |Category: OGC(R) Implementation Standard -|Editors: Panagiotis (Peter) A. Vretanos, Tom Kralidis, Charles Heazel, Angelos Tzotsos +|Editors: Panagiotis (Peter) A. Vretanos, Tom Kralidis, Angelos Tzotsos, Charles Heazel |=== [cols = "^", frame = "none"] diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-bbox.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-bbox.adoc index 026132a3..3698ae77 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-bbox.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-bbox.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_bbox]] +[[ats_record-core-query-parameters_bbox]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/bbox* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/bbox* ^|Test Purpose |Validate bbox query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-datetime.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-datetime.adoc index f1dadb6c..a51c4773 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-datetime.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-datetime.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_datetime]] +[[ats_record-core-query-parameters_datetime]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/datetime* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/datetime* ^|Test Purpose |Validate datetime query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-definition.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-definition.adoc index 0c9ee4e1..0c7579fd 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-definition.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-definition.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_externalIds-definition]] +[[ats_record-core-query-parameters_externalIds-definition]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/externalIds-definition* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/externalIds-definition* ^|Test Purpose |Validate datetime query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-response.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-response.adoc index ec5515f1..20ecba29 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-response.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-externalIds-response.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_externalIds-response]] +[[ats_record-core-query-parameters_externalIds-response]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/externalIds-response* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/externalIds-response* ^|Test Purpose |Validate externalIds query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-definition.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-definition.adoc index 79af8562..47003fa6 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-definition.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-definition.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_ids-definition]] +[[ats_record-core-query-parameters_ids-definition]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/ids-definition* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/ids-definition* ^|Test Purpose |Validate ids query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-response.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-response.adoc index 279aa4c6..f47c9a08 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-response.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-ids-response.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_ids-response]] +[[ats_record-core-query-parameters_ids-response]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/ids-response* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/ids-response* ^|Test Purpose |Validate ids query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-limit.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-limit.adoc index b99b5040..9f677855 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-limit.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-limit.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_limit]] +[[ats_record-core-query-parameters_limit]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/limit* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/limit* ^|Test Purpose |Validate limit query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-definition.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-definition.adoc index a4d888d5..cd74fe5c 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-definition.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-definition.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_q-definition]] +[[ats_record-core-query-parameters_q-definition]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/q-definition* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/q-definition* ^|Test Purpose |Validate q query parameter. -^|Requirement |<> +|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-response.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-response.adoc index 95e946cc..22c1c782 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-response.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-q-response.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_q-response]] +[[ats_record-core-query-parameters_q-response]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/q-response* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/q-response* ^|Test Purpose |Validate q query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-definition.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-definition.adoc index 4d4eb3dd..e497c3c6 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-definition.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-definition.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_type-definition]] +[[ats_record-core-query-parameters_type-definition]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/type-definition* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/type-definition* ^|Test Purpose |Validate type query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-response.adoc b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-response.adoc index ca577767..d57a545d 100644 --- a/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-response.adoc +++ b/core/standard/abstract_tests/record-core-query-parameters/ATS_query-param-type-response.adoc @@ -1,9 +1,9 @@ -[[ats_records-core-query-parameters_type-response]] +[[ats_record-core-query-parameters_type-response]] [width="90%",cols="2,6a"] |=== -^|*Abstract Test {counter:ats-id}* |*/conf/records-core-query-parameters/type-response* +^|*Abstract Test {counter:ats-id}* |*/conf/record-core-query-parameters/type-response* ^|Test Purpose |Validate type query parameter. -^|Requirement |<> +^|Requirement |<> ^|Test Method |. Construct a path for a searchable endpoint . Issue an HTTP GET request on the path . Check that the HTTP response header value is `+200+`. diff --git a/core/standard/clause_0_front_material.adoc b/core/standard/clause_0_front_material.adoc index 9a4e0d68..3f98c6f7 100644 --- a/core/standard/clause_0_front_material.adoc +++ b/core/standard/clause_0_front_material.adoc @@ -6,21 +6,21 @@ This document defines the OGC API for Records. A Record makes a resource discoverable by providing summary information (metadata) about the resource. In this context, resources are things that would be useful to a user or developer, such as features, coverages, tiles / maps, styles, assets, machine models, services, processes, widgets, etc. -OGC API - Records provides a way to browse or search a curated collection of records known as a catalog. This specification envisions deploying a catalog as: +OGC API - Records provides a way to browse or search a curated collection of records known as a catalog. This specification envisions deploying a catalog using one of the following patterns: * a collection of static files, * a collection of records accessed via an API. -A catalog can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing. Such a deployment is amenable to browsing using a web browser or being crawled by a search engine crawler. +A catalog can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing. Such a deployment is amenable to browsing using a web browser, being crawled by a search engine crawler, or traversed by automated tools. -A catalog can also be deployed as an API with well known endpoints for retrieving information about the catalog, retrieving records from the catalog and searching the catalog for sub-sets of records that satisfy user-defined search criteria. +A catalog can also be deployed as an API with well known endpoints for retrieving information about the catalog, retrieving records from the catalog and searching the catalog for subsets of records that satisfy user-defined search criteria (area of interest, temporal extent, keywords, etc.). To enable this kind of flexible deployment of a collection of records, this specification defines the following set of building blocks: * a record, * a collection (of records), * a set of common query parameters -* and a search API. +* a search API. A record is the atomic unit of information in a catalog, It contains descriptive information (metadata) about a resource such as: @@ -32,7 +32,7 @@ A record is the atomic unit of information in a catalog, It contains descriptive * links to access the resource, * etc. -This information is generic and can be used to describe a wide variety of resources. This specification expects and encourages implementations to enrich the information content of a record to suit specific use cases or requirements. +This information is generic and can be used to describe a wide variety of resources. This specification expects and encourages implementations to enrich the information content of a record to suit specific use cases, requirements, domains or communities. A collection of records is itself described by a record that provides descriptive information about the catalog. The collection also provides access to the records of the collection either by explicitly linking to each record that is an item of the collection or by providing a search endpoint that allows the collection of records to be searched. @@ -51,7 +51,7 @@ The search API allows collections of records to be searched using logically conn |Record |`/collections/{collectionId}/items/{recordId}` |GET |<> |=== -A special use case of the catalog deployed as an API is the _local resources catalog_. A local resources catalog is a catalog deployed to make local resources offered by a provider searchable using the catalog information model and API. An example of a local resources catalog is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core]. Adding catalog capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression. Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog. +A special use case of the catalog deployed as an API is the _local resources catalog_. A local resources catalog is a catalog deployed to make local resources offered by a provider searchable using the catalog information model and API. An example of a local resources catalog is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core]. Adding catalog capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression. Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog to search for records describing resources served by that API. [[keywords]] [big]*ii. Keywords* diff --git a/core/standard/clause_2_conformance.adoc b/core/standard/clause_2_conformance.adoc index 90cd0e66..11b39041 100644 --- a/core/standard/clause_2_conformance.adoc +++ b/core/standard/clause_2_conformance.adoc @@ -41,6 +41,8 @@ https://docs.ogc.org/is/19-072/19-072.html[OGC API - Common] provides a common f NOTE: Should we remove this statement about Common? Records is really an extension of Features and so the reference to Features conformance should be sufficient. Features should then reference common ... but it does not currently do so. +NOTE TK: suggest to reference OGC API - Features and open issue on the OGC API - Features issue tracker to update their specification accordingly. + https://docs.opengeospatial.org/is/17-069r4/17-069r4.html[OGC API - Features] provides a common foundation for OGC API standards for feature access. Therefore, this standard should also be viewed as an extension to OGC API - Features. Conformance to this standard requires demonstrated conformance to the applicable Conformance Classes of https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_conformance[OGC API - Features]. The Conformance Classes implemented by an API are advertised through the <> 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. @@ -81,7 +83,7 @@ The <> conformance class defines requirement [[catalog-requirements-classes]] === Catalog deployments -Using the above mentioned building blocks, this standard identifies the following catalog requirements classes: +Using the above-mentioned building blocks, this standard identifies the following catalog requirements classes: * <> * <> @@ -147,7 +149,7 @@ OGC Compliance Testing web site. |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-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 diff --git a/core/standard/clause_4_terms_and_definitions.adoc b/core/standard/clause_4_terms_and_definitions.adoc index c609ef24..4cb21f2f 100644 --- a/core/standard/clause_4_terms_and_definitions.adoc +++ b/core/standard/clause_4_terms_and_definitions.adoc @@ -47,7 +47,7 @@ aggregate of requirements and recommendations of a specification against a singl an asset of interest that may be described by metadata in a catalog for the purpose of discovery and access (i.e. binding) === Searchable catalog endpoint -an endpoint in the OGC API resource tree that has been enhanced to support catalog queries +an endpoint in the OGC API resource tree that designed to support catalog queries NOTE: For <>, the searchable catalog endpoint is at `/items`. For <>, an example of a searchable catalog endpoint might be `/collections` or `/processes`. diff --git a/core/standard/clause_6_overview.adoc b/core/standard/clause_6_overview.adoc index 9403dffa..332b35a2 100644 --- a/core/standard/clause_6_overview.adoc +++ b/core/standard/clause_6_overview.adoc @@ -4,11 +4,11 @@ [[records-role]] === Role of OGC API - Records -Historically, catalogs have been used as large repositories of formal metadata like ISO 19119, ISO 19115, FGDC, etc. More recently, catalogs are migrating to a more distributed model where the metadata is intimately associated 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 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. -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 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 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. [[general-overview]] === General @@ -30,10 +30,10 @@ This standard defines the following building blocks that may be used to deploy a 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 or by using (for example) a web browser +* 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 @@ -49,12 +49,12 @@ The choice of which properties to include in the set of core properties was prim 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 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 suite specific needs is allowed 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, expected and encouraged by this specification. -Although this document does not mandate any particular encoding for a record, the document does define conformance classes for two encodings: +Although this document does not mandate any particular encoding for a record, the document defines conformance classes for two encodings: -* A <> record encoding, -* and an <> encoding. +* A <> record encoding, and +* an <> encoding. Other encodings are allowed but are not described in this document. @@ -67,9 +67,9 @@ Accessing collections of records through the API defined in this document is des A record collection or catalog is an object that groups and describes a set of related <>. The collection resource is the primary access point from which a deployed set of records can be accessed. Having found the collection resource (i.e. the catalog) a client can, by following the appropriate hypermedia controls contained therein, navigate to the records of the collection. -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 sub-sets of records. +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 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. It is anticipated that this set of properties will be extended to enrich the information content of the collection metadata to suit specific needs. @@ -87,8 +87,8 @@ The Records API extends https://github.com/opengeospatial/ogcapi-common[OGC API Collections of records exposed though this OGC API may be accessed through an https://www.ogc.org/standards/ogcapi-features[OGC API - Features API] that has been: -* extended with <> 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 <> (i.e. the <>). <> summarizes the access paths and relation types defined in this standard. @@ -99,11 +99,11 @@ Collections of records exposed though this OGC API may be accessed through an ht |=== ^|**Path Template** ^|**Relation** ^|**Resource** 3+^|**Common** -|<> |none |Landing page +|<> ||Landing page |<> |`service-desc` or `service-doc` |API Description (optional) |<> | `conformance` |Conformance Classes |<> | `data` |Metadata describing the spatial collections available from this API. -|<> | |Metadata describing the collection which has the unique identifier `{collectionId}` +|<> |`collection` |Metadata describing the collection which has the unique identifier `{collectionId}` 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}`. @@ -111,15 +111,15 @@ Collections of records exposed though this OGC API may be accessed through an ht Where: -* {collectionId} = an identifier for a specific record collection (i.e. catalog identifier) -* {recordId} = an identifier for a specific record within a collection +* `{collectionId}` = 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]] ==== API Behaviour Model The Records API is designed to be compatible but not conformant with the http://docs.opengeospatial.org/is/12-176r7/12-176r7.html[OGC Catalogue Service for the Web (CSW)]. This allows OGC API - Records implementations and CSW implementations to co-exist in a single processing environment. -The https://www.opengeospatial.org/standards/cat[OGC Catalogue Service standard version 3] provides an abstract core model of metadata (data about data) describing a number of different information types (datasets, services, styles, processes, etc.) on which the classic operations GetCapabilities, DescribeRecord, GetRecords, and GetRecordById can be explained naturally. This model consists of a 1..n catalog collections residing in a CSW backend repository. It holds service metadata describing service qualities (identification, contact, operations, filtering capabilities, etc.). At its heart, a catalog may provide discovery services to any number of metadata repositories. The core catalog model is based on an extension of Dublin Core (CSW Record). Application profiles can be developed to target specific metadata information models (such as ISO 19115/19139, etc.). +The https://www.opengeospatial.org/standards/cat[OGC Catalogue Service standard version 3] provides an abstract core model of metadata (data about data) describing a number of different information types (datasets, services, styles, processes, etc.) on which the classic operations (GetCapabilities, DescribeRecord, GetRecords, and GetRecordById) can be explained naturally. This model consists of a 1..n catalog collections residing in a CSW backend repository. It holds service metadata describing service qualities (identification, contact, operations, filtering capabilities, etc.). In principle, a catalog may provide discovery services to any number of metadata repositories. The core catalog model is based on an extension of Dublin Core (CSW Record). Application profiles can be developed to target specific metadata information models (such as ISO 19115/19139, etc.). Discussion has shown that the API model also assumes underlying service and object descriptions, so a convergence seems possible. In any case, it will be advantageous to have a similar "mental model" of the server store organization on hand to explain the various functionalities introduced below. @@ -130,15 +130,15 @@ This specification defines three levels of search capability of increasing compl The first or core level of search capability is based on <> and thus supports: * bounding box searches, -* time instant or time period searches, -* and equality predicates (i.e. _property_=_value_). +* time instant or time period searches, and +* equality predicates (i.e. _property_=_value_). OGC API - Record extends these core search capabilities to include: * keyword searches, * searches based on the type of resource, -* searches based on one or more record identifiers, -* and searches based on one or more external identifiers of a resource. +* searches based on one or more record identifiers, and +* searches based on one or more external identifiers of a resource. 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. @@ -149,6 +149,8 @@ The third level of search capability, defined by the <>, 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}'] diff --git a/core/standard/clause_7_building_blocks.adoc b/core/standard/clause_7_building_blocks.adoc index e3ed3c76..ed20a164 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. @@ -43,10 +43,10 @@ Other encoding are allowed but are not described in this document. [cols="20,5,55,20",options="header"] |=== |Property |Requirement |Description |GeoJSON key -|recordId |**required** |A unique record identifier assigned by the server. |id -|created |optional |The date this record was created in the server. |properties.created -|updated |optional |The most recent date on which the record was changed. |properties.updated -|conformsTo |optional |The extensions/conformance classes used in this record. |conformsTo +|recordId |**required** |A unique record identifier assigned by the server. |`id` +|created |optional |The date this record was created in the server. |`properties.created` +|updated |optional |The most recent date on which the record was changed. |`properties.updated` +|conformsTo |optional |The extensions/conformance classes used in this record. |`conformsTo` |=== [#core-properties-resource-table,reftext='{table-caption} {counter:table-num}'] @@ -54,22 +54,22 @@ Other encoding are allowed but are not described in this document. [cols="20,5,55,20",options="header"] |=== |Property |Requirement |Description |GeoJSON key -|geometry |**required** |A geometry associated with the resource that is used for discovery. Can be null if there is no associated geometry. |geometry -|time |**required** |The temporal extent of the resource. Can be null if there is no associated temporal extent. |time -|type |**required** |The nature or genre of the resource. |properties.type -|title |**required** |A human-readable name given to the resource. |properties.title -|description |optional |A free-text description of the resource. |properties.description -|keywords |optional |A list of free-form keywords or tags associated with the resource. |properties.keywords -|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this record. |properties.language -|languages |optional |The list of other languages in which this record is available. |properties.languages -|resourceLanguages |optional |The list of languages in which the resource described by this record can be retrieved. |properties.resourceLanguages -|externalIds |optional |One or more identifiers for the resource assigned by an external entity. |properties.externalIds -|themes |optional |A knowledge organization system used to classify the resource. |properties.themes -|formats |optional |A list of available distributions for the resource. |properties.formats -|contacts |optional |A list of contacts qualified by their role(s) in association to the record or resource. |properties.contacts -|license |optional |The legal provisions under which the resource is made available. |properties.license -|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. |properties.rights -|links |**required** |A list of links related to this record. +|geometry |**required** |A geometry associated with the resource that is used for discovery. Can be null if there is no associated geometry. |`geometry` +|time |**required** |The temporal extent of the resource. Can be null if there is no associated temporal extent. |`time` +|type |**required** |The nature or genre of the resource. |`properties.type` +|title |**required** |A human-readable name given to the resource. |`properties.title` +|description |optional |A free-text description of the resource. |`properties.description` +|keywords |optional |A list of free-form keywords or tags associated with the resource. |`properties.keywords` +|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this record. |`properties.language` +|languages |optional |The list of other languages in which this record is available. |`properties.languages` +|resourceLanguages |optional |The list of languages in which the resource described by this record can be retrieved. |`properties.resourceLanguages` +|externalIds |optional |One or more identifiers for the resource assigned by an external entity. |`properties.externalIds` +|themes |optional |A knowledge organization system used to classify the resource. |`properties.themes` +|formats |optional |A list of available distributions for the resource. |`properties.formats` +|contacts |optional |A list of contacts qualified by their role(s) in association to the record or resource. |`properties.contacts` +|license |optional |The legal provisions under which the resource is made available. |`properties.license` +|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. |`properties.rights` +|links |**required** |A list of links related to this record.|`links` |=== include::requirements/record-core/REQ_mandatory-properties-record.adoc[] @@ -109,9 +109,9 @@ This standard does not place any containts on the number of additional temporal [cols="20,10a,70a",options="header"] |=== |Property |Type |Description -|date |string |An instant with a granularity of a date. See below for more details about instants. -|timestamp |string |An instant with the granularity of a timestamp. See below for more details about instants. -|interval |[ string ] |An interval, described by an array of the two instants (start and end). See below for more details about intervals. +|`date` |string |An instant with a granularity of a date. See below for more details about instants. +|`timestamp` |string |An instant with the granularity of a timestamp. See below for more details about instants. +|`interval` |[ string ] |An interval, described by an array of the two instants (start and end). See below for more details about intervals. |=== Including both an instant and an interval is valid, if both values intersect. In this case, clients should use the interval property and may use the date or timestamp property to determine the temporal characteristics of the resource being described by the record. @@ -140,7 +140,9 @@ NOTE: This Standard only provides guidance how to represent record data in JSON. ==== [source,json,linenumbers] ---- -"time" : { "date": "1969-07-20" } +"time" : { + "date": "1969-07-20" +} ---- ==== @@ -149,7 +151,9 @@ NOTE: This Standard only provides guidance how to represent record data in JSON. ==== [source,json,linenumbers] ---- -"time" : { "timestamp": "1969-07-20T20:17:40Z" } +"time" : { + "timestamp": "1969-07-20T20:17:40Z" +} ---- ==== @@ -163,14 +167,19 @@ include::recommendations/record-core/PER_temporal_comparison.adoc[] An interval is described by start and end instants. Both start and end instants are included in the interval, i.e., the interval is closed. -The end of unbounded intervals are represented by a double-dot string ("..") for the start/end. This follows the convention of ISO 8601-2 for an open start or end. +The end of unbounded intervals are represented by a double-dot string (`..`) for the start/end. This follows the convention of ISO 8601-2 for an open start or end. [#ex-time-3,reftext='{listing-caption} {counter:listing-num}'] .An interval with dates ==== [source,json,linenumbers] ---- -"time" : { "interval": [ "1969-07-16", "1969-07-24" ] } +"time" : { + "interval": [ + "1969-07-16", + "1969-07-24" + ] +} ---- ==== @@ -179,7 +188,12 @@ The end of unbounded intervals are represented by a double-dot string ("..") for ==== [source,json,linenumbers] ---- -"time" : { "interval": [ "1969-07-16T05:32:00Z", "1969-07-24T16:50:35Z" ] } +"time" : { + "interval": [ + "1969-07-16T05:32:00Z", + "1969-07-24T16:50:35Z" + ] +} ---- ==== @@ -188,7 +202,12 @@ The end of unbounded intervals are represented by a double-dot string ("..") for ==== [source,json,linenumbers] ---- -"time" : { "interval": [ "2014-04-24T10:50:18Z", ".." ] } +"time" : { + "interval": [ + "2014-04-24T10:50:18Z", + ".." + ] +} ---- ==== @@ -207,7 +226,7 @@ include::requirements/record-core/REQ_time-zone.adoc[] [[sc_keywords_and_themes]] ===== Keywords and Themes -A record allows for one `properties.keywords` and zero to many `properties.themes` properties. Keywords are free form terms or tags associated with the resource(s) that the record describes. Themes are concepts associated with the resource(s) that a record describes taken from one or more formal knowledge organization systems or schemes. The list of knowledge organization systems or schemes used in a <> or <> catalog can be determined by inspecting the server's OpenAPI document or, if the server implements CQL2, by exposing a queryable (e.g. named `scheme`) and enumerating the list of schemes used in the queryable's schema definition. +A record allows for one `properties.keywords` and one to many `properties.themes` properties. Keywords are free form terms or tags associated with the resource(s) that the record describes. Themes are concepts associated with the resource(s) that a record describes taken from one or more formal knowledge organization systems or schemes. The list of knowledge organization systems or schemes used in a <> or <> catalog can be determined by inspecting the server's OpenAPI document or, if the server implements CQL2, by exposing a queryable (e.g. named `scheme`) and enumerating the list of schemes used in the queryable's schema definition. include::recommendations/record-core/REC_record-keywords-themes.adoc[] @@ -253,7 +272,7 @@ Navigation links are meant to encode relationships between catalog entities (i.e include::requirements/record-core/REQ_record-links.adoc[] -include::recommendations/record-core/REQ_links.adoc[] +include::recommendations/record-core/REC_links.adoc[] Links in the `links` section may also encode canoncial URIs for record properties such as `type` and `license`. @@ -333,7 +352,7 @@ include::../examples/json/templated-link-ref.json[] CLIENT SERVER | | | GET variables/bbox HTTP/1.1 | - | Host: www.someserver.com | + | Host: example.org | | Accept: application/json | |---------------------------------------------------------->| | | @@ -367,8 +386,8 @@ A <> contains information, encoded in the links and link A catalog record can include language information about: * the resource that the record describes, -* the language used for text values in the current record representation, -* and alternate languages in which the current record can be represented. +* the language used for text values in the current record representation, and +* alternate languages in which the current record can be represented. ====== Language of the record @@ -411,14 +430,14 @@ 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] 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, this document does define conformance classes for two encodings: +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 encoding are allowed but are not described in this document. +Other encodings are allowed but are not described in this document. [[record-collection-schema]] ==== Record collection schema @@ -502,7 +521,7 @@ The parameters `bbox`, `datetime`, `limit` and `ids` are inherited from https:// |=== |Parameter name |Description |https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_bbox[bbox] |A bounding box. If the spatial extent of the record intersects the specified bounding box then the record shall be presented in the response document. -|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_datetime[datetime] |A time instance or time period. If the temporal extent of the record intersects the specified data/time value then the record shall be presented in the response document. +|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_datetime[datetime] |A time instance or time period. If the temporal extent of the record intersects the specified date/time value then the record shall be presented in the response document. |https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_limit[limit] |The number of records to be presented in a response document. |<> |A comma-separated list of search terms. If any server-chosen text field in the record contains 1 or more of the terms listed then this records shall appear in the response set. |<> |An equality predicate consistent of a comma-separated list of resource types. Only records of the listed type shall appear in the resource set. @@ -884,16 +903,16 @@ The following examples illustrate each of these linking patterns: { "title" : "A related record", "href" : "https://example.org/related-record-path/rec15" - } + } ], "license": { "title" : "CC BY 2.0", "href" : "https://creativecommons.org/licenses/by/2.0/" - }, + }, "enclosure": { "title": "GeoPackage of Feature Data", - "href" : "https://www.someserver.com/collections/MyCollection/items?f=application/geopackage+vnd.sqlite3&bbox={bbox}", - "varBase": "https://www.someserver.com/variables" + "href" : "https:/example.org/collections/MyCollection/items?f=application/geopackage+vnd.sqlite3&bbox={bbox}", +  "varBase": "https://example.org/variables/ }, ... } @@ -975,13 +994,13 @@ The use of keywords from a controlled voacbulary is encoded in a record using th Using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering], a server would need to expose two https://docs.ogc.org/DRAFTS/19-079r1.html#queryables[queryables], `scheme` and `concept` for the purpose of filtering using keywords from a specific controlled vocabulary. Using these queryables, the following filter could be expressed: ---- -https://www.someserver.com/collections/myCatalog/items?filter-lang=cql2-text&filter=scheme%3D%27https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode%27%20and%20concept%3D%27spectral%27%2C%0Ahoelper%27 +https://example.org/collections/myCatalog/items?filter-lang=cql2-text&filter=scheme%3D%27https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode%27%20and%20concept%3D%27spectral%27%2C%0Ahoelper%27 ---- An alternative approach that does rely on using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering] and https://docs.ogc.org/DRAFTS/21-065.html[CQL2] would rely on the server defining a set of https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameters_for_filtering_on_feature_properties[query parameters] in the server's https://docs.ogc.org/is/17-069r4/17-069r4.html#_api_definition[API description document], again named `scheme` and `concept`, that would allow the following filter to be expressed: ---- -https://www.someserver.com/collections/myCatalog/items?scheme=https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode&concept=spectral,hoelper +https://example.org/collections/myCatalog/items?scheme=https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode&concept=spectral,hoelper ---- [[clause-autodiscovery]] @@ -1074,7 +1093,7 @@ be read by machines, such as JSON or XML, have two issues: * The data is not discoverable using the most common mechanism for discovering information, that is the search engines of the Web; -* The data can not be viewed directly in a browser - additional tools are required to view the data. +* The data cannot be viewed directly in a browser (additional tools are required to view the data). Therefore, sharing data on the Web should include publication in HTML. To be consistent with the Web, it should be done in a way that enables users and search engines to access all data. diff --git a/core/standard/clause_8_deployments.adoc b/core/standard/clause_8_deployments.adoc index 7ab0abf0..52941a01 100644 --- a/core/standard/clause_8_deployments.adoc +++ b/core/standard/clause_8_deployments.adoc @@ -101,7 +101,7 @@ This conformance class specifies requirements and recommendations for supporting include::requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc[] -include::recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc[] +include::recommendations/searchable-catalog_filtering/PER_additional-queryables.adoc[] ===== Coordinate reference systems @@ -148,13 +148,13 @@ As an example of a local resources endpoint, consider the `/collections` endpoin [cols="25,25,25,25",options="header"] |=== |`/collections` property |Requirement |Core Property |Requirement -|id |M |id |M -|title |O |title |M -|description |O |description |M -|itemType |O |-- |-- -|extent |O |extent |O -|links |M |links |O -|crs |O |-- |-- +|id |**required** |id |**required** +|title |optional |title |**required** +|description |optional |description |**required** +|itemType |optional |-- |-- +|extent |optional |extent |optional +|links |**required** |links |optional +|crs |optional |-- |-- |=== It is evident that there is significant overlap of the properties of each resource. This standard defines the following requirements and recommendations with regard to information content of a local resources object such as the collection object that is retrievable from the `/collections` endpoint. diff --git a/core/standard/clause_9_media_types.adoc b/core/standard/clause_9_media_types.adoc index 524dc1b7..53029e1d 100644 --- a/core/standard/clause_9_media_types.adoc +++ b/core/standard/clause_9_media_types.adoc @@ -24,7 +24,7 @@ GeoJSON provides a simple way of representing OGC Records in JSON and is support ==== Media types -A description of the MIME-types is mandatory for any OGC standard which involves data encodings. The list of suitable MIME-types for the API - Records standard in provided in <>. +A description of the MIME types is mandatory for any OGC standard which involves data encodings. The list of suitable MIME types for the API - Records standard in provided in <>. [#media-types-table,reftext='{table-caption} {counter:table-num}'] .API - Records MIME Types diff --git a/core/standard/recommendations/html/REC_schema-org.adoc b/core/standard/recommendations/html/REC_schema-org.adoc index 193a0206..c160d8fb 100644 --- a/core/standard/recommendations/html/REC_schema-org.adoc +++ b/core/standard/recommendations/html/REC_schema-org.adoc @@ -2,5 +2,5 @@ [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/html/schema-org* -^|A |A `200`-response with the media type `text/html`, SHOULD include <> annotations. +^|A |A `200` response with the media type `text/html`, SHOULD include <> annotations. |=== diff --git a/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc b/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc index b9a9e2ac..25b8d8d4 100644 --- a/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc +++ b/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc @@ -1,7 +1,7 @@ -[[rec_records-core-query-parameters_additional-query-parameters]] +[[rec_record-core-query-parameters_additional-query-parameters]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/additional-query-parameters* +^|*Recommendation {counter:rec-id}* |*/rec/record-core-query-parameters/additional-query-parameters* ^|A |If any additional property (see <>) is expected to be useful for applications using at a searchable catalog endpoint, a parameter with the name of that property SHOULD be supported. ^|B |If the parameter has a simple value (e.g. a string or integer) then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc b/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc index 7e2f0d97..ab0a6835 100644 --- a/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc +++ b/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc @@ -1,7 +1,7 @@ -[[rec_records-core-query-parameters_param-q]] +[[rec_record-core-query-parameters_param-q]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/param-q* +^|*Recommendation {counter:rec-id}* |*/rec/record-core-query-parameters/param-q* The `q` operator SHOULD, at least, be applied to the following core properties: diff --git a/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc b/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc index 542c607c..670f4b50 100644 --- a/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc +++ b/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc @@ -1,6 +1,6 @@ -[[rec_records-core-query-parameters_param-type-definition]] +[[rec_record-core-query-parameters_param-type-definition]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/param-type-definition* +^|*Recommendation {counter:rec-id}* |*/rec/record-core-query-parameters/param-type-definition* ^|A |The definition of the `type` parameter SHOULD be extended to enumerate the list of known record or resource types. |=== diff --git a/core/standard/recommendations/record-core/REQ_links.adoc b/core/standard/recommendations/record-core/REC_links.adoc similarity index 100% rename from core/standard/recommendations/record-core/REQ_links.adoc rename to core/standard/recommendations/record-core/REC_links.adoc diff --git a/core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc b/core/standard/recommendations/searchable-catalog_filtering/PER_additional-queryables.adoc similarity index 100% rename from core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc rename to core/standard/recommendations/searchable-catalog_filtering/PER_additional-queryables.adoc diff --git a/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc b/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc index 4664554b..b9b0f184 100644 --- a/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc +++ b/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/itemType* -^|A |The _itemType_ member of the _collection_ SHALL be an array whose elements enumerate the types of resources referenced by this collection. +^|A |The `itemType` member of the collection SHALL be an array whose elements enumerate the types of resources referenced by this collection. ^|B |The value `record` SHALL be used to indicate that this collection includes references to <>. ^|C |The value `catalog` SHALL be used to indicate that this collection includes references to <>. ^|D |The value `collection` SHALL be used to indicate that this collection includes references to other <>. diff --git a/core/standard/requirements/html/REQ_content.adoc b/core/standard/requirements/html/REQ_content.adoc index 7457010f..3995cd44 100644 --- a/core/standard/requirements/html/REQ_content.adoc +++ b/core/standard/requirements/html/REQ_content.adoc @@ -2,7 +2,7 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/html/content* -^|A |Every `200`-response of the server with the media type `text/html` SHALL be a link:https://www.w3.org/TR/html5/[HTML 5 document] that includes the following information in the HTML body: +^|A |Every `200` response of the server with the media type `text/html` SHALL be a link:https://www.w3.org/TR/html5/[HTML 5 document] that includes the following information in the HTML body: * all information identified in the schemas of the link:http://spec.openapis.org/oas/v3.0.3#responseObject[Response Object] in the HTML ``, and * all links in HTML `` elements in the HTML ``. diff --git a/core/standard/requirements/html/REQ_definition.adoc b/core/standard/requirements/html/REQ_definition.adoc index 228eb03d..5a1e8bb2 100644 --- a/core/standard/requirements/html/REQ_definition.adoc +++ b/core/standard/requirements/html/REQ_definition.adoc @@ -2,5 +2,5 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/html/definition* -^|A |Every `200`-response of an operation of the server SHALL support the media type `text/html`. +^|A |Every `200` response of an operation of the server SHALL support the media type `text/html`. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc index d4fb88c1..7d993334 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_bbox]] +[[req_record-core-query-parameters_bbox]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/bbox* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/bbox* ^|A |A searchable endpoint SHALL support the Bounding Box Search (`bbox`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_bbox[OGC API - Features - Part 1: Core]. ^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_bbox[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc index 6307fee9..5dfaf8c7 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_datetime]] +[[req_record-core-query-parameters_datetime]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/datetime* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/datetime* ^|A |A searchable endpoint SHALL support a Temporal Searching (`datetime`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_datetime[OGC API - Features - Part 1: Core]. ^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_datetim[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-definition.adoc index 68743a17..090df41f 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-definition.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_externalIds-definition]] +[[req_record-core-query-parameters_externalIds-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/externalIds-definition* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/externalIds-definition* ^|A |A searchable endpoint SHALL support search by External Identifiers (`externalIds`) parameter for the operation. ^|B |The `externalIds` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-response.adoc index 57070fdd..a649b177 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalIds-response.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_externalIds-response]] +[[req_record-core-query-parameters_externalIds-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/externalIds-response* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/externalIds-response* Only records that have an external identifier, as indicated by the values of the `externalIds` core queryable, equal to one of the listed values specified using the `externalIds` parameter SHALL be in the result set. |=== 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 b5996e9c..a8164649 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 @@ -1,9 +1,9 @@ -[[req_records-core-query-parameters_ids-definition]] +[[req_record-core-query-parameters_ids-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-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. +^|*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 [source,YAML] ---- diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc index b35bb10f..1dc2383f 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_ids-response]] +[[req_record-core-query-parameters_ids-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/ids-response* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/ids-response* Only records whose identifier match one of the identifiers specified using `ids` parameter SHALL be in the results set. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc index 4e061ef3..ddee4390 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_limit]] +[[req_record-core-query-parameters_limit]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/limit* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/limit* ^|A |A searchable endpoint SHALL support a Paging (`limit`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_limit[OGC API - Features - Part 1: Core]. ^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_limit[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc index 33ca3ab6..96dcb140 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_q-definition]] +[[req_record-core-query-parameters_q-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/q-definition* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/q-definition* ^|A |A searchable endpoint SHALL support the Text Search (`q`) parameter for the operation. ^|B |The `q` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc index eb9a0484..8720b904 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_q-response]] +[[req_record-core-query-parameters_q-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/q-response* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/q-response* ^|A |If a single search term is specified, then only records that contain that search term in one or more of the searched text fields SHALL be in the result set. ^|B |For multiple search terms that are comma separated (logical OR), only records that contain one or more the specified search terms in one or more of the searched text fields SHALL be in the result set. diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc index e2c781ed..852216d0 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_type-definition]] +[[req_record-core-query-parameters_type-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/type-definition* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/type-definition* ^|A |A searchable endpoint SHALL support the search by Type (`type`) parameter for the operation. ^|B |The `type` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc index 6c5b70ed..20e43eef 100644 --- a/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc @@ -1,7 +1,7 @@ -[[req_records-core-query-parameters_type-response]] +[[req_record-core-query-parameters_type-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/type-response* +^|*Requirement {counter:req-id}* |*/req/record-core-query-parameters/type-response* Only records whose type, as indicated by the value of the `type` core queryable, is equal to one of the listed values specified using the `type` parameter SHALL be in the result set. |===