I. Abstract
The OGC API family of Standards is being developed to make it easy for anyone to provide geospatial data over the web. These Standards build upon the legacy of the OGC Web Service Standards (WMS, WFS, WCS, WPS, CSW, etc.), but define resource-centric APIs that take advantage of modern web development practices.
This document defines the OGC API — Records — Part 1: Core Standard. In this document “Records API” refers to the OGC API — Records — Part 1: Core Standard.
The content of 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, notebooks etc.
An implementation of the OGC API — Records Standard provides a way to browse or search a curated collection of records known as a catalog. The Records API Standard 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, being crawled by a search engine crawler, or traversed by automated tools.
A catalog can also be deployed as an implementation of a Web API consisting of 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, the Records API Standard defines the following set of common components:
a record,
a catalog (a collection of records),
a set of common query parameters,
the requirements and characteristics for implementation instances of a Records search API (hereafter termed the “search API”).
A record is the atomic unit of information in a catalog. It contains descriptive information (metadata) about a resource such as:
a title,
a human readable description of the resource,
the nature or genre of the resource,
keywords associated with the resource,
information about the publisher or provider of the resource,
links to access the resource,
etc.
This information is generic and can be used to describe a wide variety of resources. The Records API Standard 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 i.e., of the collection or by providing a search endpoint that allows the collection of records to be searched.
An implementation of a search API allows collections of records to be searched using logically connected spatial, temporal and scalar predicates. This Standard uses the OGC API — Features — Part 1: Core Standard for specifying requirements of the core of the Records search API. Additional parts from the OGC API — Features suite of standards can also be implemented to enhance the capabilities of the search API. The following table lists the endpoints of the core OGC API — Records API that allow a collection of records to be searched:
Table 1 — Overview of resources, applicable HTTP methods and links to the document sections
Resource | Path | HTTP method | Document reference |
---|---|---|---|
Landing page | / | GET | API landing page |
Conformance declaration | /conformance | GET | Conformance |
Record collections | /collections | GET | Record collections |
Record collection | /collections/{collectionId} | GET | Record collection |
Records | /collections/{collectionId}/items | GET | Records access |
Record | /collections/{collectionId}/items/{recordId} | GET | Record Core |
A special use case of a catalog deployed as an implementation of a Web API is the local resources catalog. A local resources catalog is a catalog deployed as an implementation of a Web API that makes local resources offered by a provider searchable using the catalog information model and accessed via the API. An example of a local resources catalog is the /collections endpoint of OGC API — Common — Part 2: Geospatial data or OGC API — Features — Part 1: Core. Adding catalog capabilities to this endpoint enables a client to search for collections that satisfy a specified filter expression. Any API endpoint defined in an OGC API Standard whose function is to provide descriptive metadata about other sub-resources accessible via the API can be extended to behave as a local resources catalog. The /collections endpoint is an examples of such an endpoint. The /collections endpoint provides metadata about the collections that a server offers. One can well imagine the benefits of being able to search for a specific subset of collection descriptions on a server that offers thousands of data collections.
II. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, OGC API, catalog, record, records, resource, metadata, discovery, CSW, API, GeoJSON, HTML, schema.org, JSON-LD
III. Preface
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
IV. Security considerations
Given the dependencies on the OGC API — Common and OGC API — Features Standard, aspects of security are discussed in those Standards.
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.
V. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- CubeWerx Inc.
- Meteorological Service of Canada
- Open Source Geospatial Foundation
- Geonovum
VI. Submitters
All questions regarding this submission should be directed to the editor or the submitters:
Name | Affiliation |
Panagiotis (Peter) A. Vretanos (editor) | CubeWerx Inc. |
Tom Kralidis (editor) | Meteorological Service of Canada |
Angelos Tzotsos (editor) | Open Source Geospatial Foundation |
Charles Heazel (editor) | HeazelTech |
Linda van den Brink | Geonovum |
VII. Acknowledgements
This specification acknowledges and remembers Douglas Nebert. As part of USGS and FGDC, Doug was internationally recognized as a champion of metadata, discovery and interoperability. He was one of the editors of the OGC Catalogue Services specification and a longtime champion of spatial data infrastructure initiatives including the US data.gov efforts, GEOSS and beyond. Doug’s vision and expertise will always be remembered and appreciated by the specification editors and community.
1. Scope
The OGC Records API Standard specifies requirements classes for a set of common components that can be assembled in various ways to deploy a collection of related descriptive information (metadata) about resources called a catalog. The atomic unit of information in a catalog is the record.
This Standard specifies the information content of a record. A record contains summary descriptive information (metadata) about a resource that a provider wishes to make discoverable. A record represents resource characteristics that can be presented for evaluation and further processing by both humans and software. Examples of resources include a data collection, a service, a process, a style, an Earth observation asset, a machine learning model, a code list and so on.
Records are organized into collections called catalogs. The Records API Standard describes how catalogs can be crawled or searched. Crawling a collection of records involves following embedded links from one record in a catalog to the next. Searching a collection of records involves specifying query predicates that define a subset of records.
2. Conformance
2.1. 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.
The standardization target of the conformance classes:
is “Document model.”
The standardization target of the conformance classes:
is “Web APIs.”
The standardization target of the conformance classes:
is “Document encoding.”
The Conformance Classes implemented in an API are advertised through the /conformance path on the 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.
2.2. Common components
This standard also identifies ten (11) requirements classes for common components:
These common components are not intended to be implemented independently but rather implemented as components of one or more catalog deployment types.
The Record Core conformance class defines the requirements for the core schema of a catalog record which is a set of properties (core 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.
The Record Collection conformance class defines requirements for the metadata used to describe a collection of related records referred to as a catalog in this Standard.
The Record query parameters conformance class defines a minimum set of query parameters that all queryable catalogs should provide.
The Profile query parameter conformance class add support for the profile parameter which allows a client to request one or more variations of a resource representation (e.g., requesting a GeoJSON document that is a catalog record).
The Records API conformance class defines the requirements for an API implementation for searching catalogs based on logically connected predicates that can include spatial and/or temporal predicates. The Records API Standard is based on OGC API — Feature — Part 1: Core with extensions specific to OGC API — Records. OGC API — Features provides a common foundation for other OGC API Standards for feature access. Therefore, this conformance class should be viewed as an extension to OGC API — Features. Conformance to this class requires demonstrated conformance to the applicable Conformance Classes define in the of OGC API — Features Standard.
The Sorting conformance class defines the requirements to support sorting of records in a query response.
The Filtering conformance class defines the requirements to support record filtering using CQL2.
The JSON conformance class defines the requirements for a JSON representation of a catalog object and a GeoJSON (see RFC 7946) representation of a standard catalog record.
The HTML conformance class defines the requirements for an HTML representation of a standard catalog record.
The OpenAPI 3.0 conformance class defines the requirements for server that use an OpenAPI 3.0 document to define their API.
The Autodiscovery 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.
2.3. Catalog deployments
Using the above-mentioned common components, this Standard identifies the following catalog requirements classes:
Each of the top-level requirements classes, Crawlable Catalog, Searchable Catalog and Local Resources Catalog represent an implementable catalog composed of aggregations of the common components described above.
The Crawlable Catalog conformance class defines the core requirements for a catalog composed of a collection of web-accessible files. The files of a crawlable catalog may be static web pages or dynamically generated but regardless, they exist at a fixed URL and can be retrieved without the use of query parameters.
The Searchable Catalog, Searchable Catalog — Sorting, Searchable Catalog — Filtering conformance classes define the requirements for a catalog composed of a collection of records that is searchable via an API.
The Local Resources Catalog, Local Resources Catalog — Query Parameters, Local Resources Catalog — Sorting, Local Resources Catalog — Filtering conformance classes define the requirements for a local resources catalog which is a catalog composed of a list of resources offered by an OGC API deployment. The /collections endpoint is an example of a local resources catalog but other endpoints may exist in an OGC API deployment as well.
Table 2 — Required common components by catalog deployment type
Common Component | Deployment Type | ||
---|---|---|---|
Crawlable | Searchable | Local Resources catalog | |
Record Core | Mandatory | Mandatory | Mandatory |
Record collection | Mandatory | Mandatory | Mandatory |
Record query parameters | N/A | Mandatory | Optional |
Profile query parameter | N/A | Optional | Optional |
Records API | N/A | Mandatory | N/A |
Sorting | N/A | Optional | Optional |
Filtering | N/A | Optional | Optional |
JSON | Optional | Optional | Optional |
HTML | Optional | Optional | Optional |
OpenAPI 3.0 | N/A | Optional | Optional |
2.4. Implementations
Implementors of this Standard select one or more of the catalog deployment requirements classes they wish to implement and then implement the required common component requirements classes.
2.5. Conformance testing
Conformance with this Standard shall be checked using all the relevant tests specified in Annex A 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 OGC Compliance Testing web site.
Table 3 — Catalog Deployment Conformance class URIs
Table 4 — Common Component Conformance class URIs
3. Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee: IETF RFC 2616, Hypertext Transfer Protocol — HTTP/1.1. RFC Publisher (1999). https://www.rfc-editor.org/info/rfc2616.
E. Rescorla: IETF RFC 2818, HTTP Over TLS. RFC Publisher (2000). https://www.rfc-editor.org/info/rfc2818.
G. Klyne, C. Newman: IETF RFC 3339, Date and Time on the Internet: Timestamps. RFC Publisher (2002). https://www.rfc-editor.org/info/rfc3339.
T. Berners-Lee, R. Fielding, L. Masinter: IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax. RFC Publisher (2005). https://www.rfc-editor.org/info/rfc3986.
M. Duerst, M. Suignard: IETF RFC 3987, Internationalized Resource Identifiers (IRIs). RFC Publisher (2005). https://www.rfc-editor.org/info/rfc3987.
J. Gregorio, R. Fielding, M. Hadley, M. Nottingham, D. Orchard: IETF RFC 6570, URI Template. RFC Publisher (2012). https://www.rfc-editor.org/info/rfc6570.
T. Bray (ed.): IETF RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format. RFC Publisher (2014). https://www.rfc-editor.org/info/rfc7159.
H. Butler, M. Daly, A. Doyle, S. Gillies, S. Hagen, T. Schaub: IETF RFC 7946, The GeoJSON Format. RFC Publisher (2016). https://www.rfc-editor.org/info/rfc7946.
M. Nottingham: IETF RFC 8288, Web Linking. RFC Publisher (2017). https://www.rfc-editor.org/info/rfc8288.
Clemens Portele, Panagiotis (Peter) A. Vretanos, Charles Heazel: OGC 17-069r4, OGC API — Features — Part 1: Core corrigendum. Open Geospatial Consortium (2022). http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.1.
Panagiotis (Peter) A. Vretanos, Clemens Portele: OGC 19-079r2, OGC API — Features — Part 3: Filtering. Open Geospatial Consortium (2024). http://www.opengis.net/doc/IS/ogcapi-features-3/1.0.
Panagiotis (Peter) A. Vretanos, Clemens Portele: OGC 21-065r2, Common Query Language (CQL2). Open Geospatial Consortium (2024). http://www.opengis.net/doc/IS/cql2/1.0.
Open API Initiative: OpenAPI Specification 3.0.3, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
WHATWG: HTML, Living Standard [online, viewed 2020-03-16]. Available at https://html.spec.whatwg.org/
Schema.org: https://schema.org/docs/schemas.html
Nottingham, M.: IETF, The Link-Template HTTP Header Field, draft-ietf-httpapi-link-template-latest
4. Terms and definitions
This document uses the terms defined in OGC Policy Directive 49, 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 document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.
This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.
For the purposes of this document, the following additional terms and definitions apply.
a collection of related records
set of related tests, all within a single conformance test class (OGC 08-131)
Note 1 to entry: When no ambiguity is possible, the word test may be omitted. i.e., conformance test module is the same as conformance module. Conformance modules may be nested in a hierarchical way.
set of conformance test modules that must be applied to receive a single certificate of conformance (OGC 08-131)
Note 1 to entry: When no ambiguity is possible, the word test may be omitted, so conformance test class may be called a conformance class.
collection of data, published or curated by a single agent, and available for access or download in one or more serializations or formats (DCAT)
a set of components implemented to execute the runtime functions of a catalog
EXAMPLE: a crawlable catalog deployment composed of static, web-accessible files
EXAMPLE: a searchable catalog deployment composed of an API that can be used to dynamically search a collection of catalog records
represents an accessible form of a dataset (DCAT)
EXAMPLE: a downloadable file, an RSS feed or a web service that provides the data
set of code (e.g., Java and CTL) that provides runtime tests for the assertions defined by the ATS. Test data required to do the tests are part of the ETS (OGC 08-134)
the path from which a catalog of local resources can be retrieved (e.g., /collections)
an instance of the document or resource that is retrieved from a local resources endpoint
an instance of an object that provides summary information about a discoverable local resource retrieved from a local resources catalog (e.g., /collections{/collectionID})
a collection of resources defined by the set of OGC API Standards that are hierarchically organized and exposed by implementations of the OGC API Standards through a root node that is common to all OGC APIs
atomic unit of information of a catalog that is used to provide information (i.e., metadata) about a particular resource that the publisher of that resources wishes to make discoverable
expression in the content of a document conveying that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others, or that a certain course of action is preferred but not necessarily required, or that (in the negative form) a certain possibility or course of action is deprecated but not prohibited (OGC 08-131)
expression in the content of a document conveying criteria to be fulfilled if compliance with the document is to be claimed and from which no deviation is permitted (OGC 08-131)
aggregate of all requirement modules that must all be satisfied to satisfy a conformance test class (OGC 08-131)
aggregate of requirements and recommendations of a specification against a single standardization target type (OGC 08-131)
an asset of interest that may be described by metadata (i.e., a record) in a catalog for the purpose of discovery and access (i.e., binding)
an endpoint in the OGC API resource tree that is designed to support catalog queries
Note 1 to entry: For searchable catalogs, the searchable catalog endpoint is at /items. For local resources catalogs, an example of a searchable catalog endpoint might be /collections or /processes.
entity to which some requirements of a standard apply (OGC 08-131)
Note 1 to entry: The standardization target is the entity which may receive a certificate of conformance for a requirements class.
5. Conventions
The following conventions will be used in this document. Examples of conventions are symbols, abbreviations, use of XML schema, use of JSON schema, or special notes regarding how to read the document.
5.1. Identifiers
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.
5.2. Use of HTTPS
For simplicity, this document in general only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS and simply is a shorthand notation for “HTTP or HTTPS.” In fact, most servers are expected to use HTTPS, not HTTP.
5.3. Link relations
To express relationships between resources, RFC 8288 (Web Linking) is used.
The following IANA registered link relation types are used in this document.
alternate: Refers to a substitute for this context.
collection: The target IRI points to a resource which represents the collection resource for the context IRI.
describes: Refers to a resource that is described by this context (i.e., the record).
icon: Refers to an icon representing this context.
item: Refers to a resource that is a member of the collection represented by this context.
license: Refers to a license associated with this context.
next: Indicates that the link’s context is a part of a series, and that the next in the series is the link target.
prev, previous: Indicates that the link’s context is a part of a series, and that the previous in the series is the link target.
self: Conveys an identifier for this context.
service-desc: Identifies service description for this context that is primarily intended for consumption by machines. API definitions are considered service descriptions.
service-doc: Identifies service documentation for this context that is primarily intended for human consumption.
In addition, the following link relation types are used for which no applicable registered link relation type could be identified.
catalog: Refers to a resource that is a catalog associated with this context.
child: Indicates that the link’s context is part of a hierarchy, and that a child resource in the hierarchy is the link target.
conformance: Refers to a resource that identifies the specifications that this context conforms to.
items: Refers to a resource that is comprised of members of the collection represented by this context.
parent: Indicates that the link’s context is part of a hierarchy, and that the parent resource in the hierarchy is the link target.
root: Indicates that the link’s context is part of a hierarchy, and that the root resource of the hierarchy is the link target.
http://www.opengis.net/def/rel/ogc/1.0/sortables: Refers to a resource, for this context, that provides a list of properties that may be used to create a sortby expression.
http://www.opengis.net/def/rel/ogc/1.0/queryables: Refers to a resource, for this context, that provides a list of properties that may be used to create a filter expression.
http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog: Refers to a resource, for this context, that points to an associated catalog.
Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. For example, an enclosure link could reference a bulk download of a collection. Or a related link on a record could reference a related record.
5.4. Profile URIs
The following profile URIs are defined and used in this document.
http://www.opengis.net/def/profile/OGC/0/ogc-catalog: Refers to a profile of a base resource type (e.g., application/json) that is a catalog.
http://www.opengis.net/def/profile/OGC/0/ogc-record: Refers to a profile of a base resource type (e.g., application/geo+json) that is a record of a catalg.
5.5. Examples
Most of the examples provided in this Standard are encoded in JSON. JSON was 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 deployed API advertises its support for the associated Conformance Class.
5.6. Schemas
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).
6. Overview
6.1. Role of catalogs
Historically, catalogs have been used as large repositories of formal metadata such as 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 SpatioTemporal Asset Catalogs (STAC) which relies on well-defined common components that can be integrated in different ways.
Although OGC API — Records is built upon the legacy of the OGC Catalog Service Web (CSW) Standard, which was primarily focused on accessing a large repository of metadata documents, this Standard also supports other catalog deployment patterns such as a catalog composed of a distributed set of static records.
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 accessing 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 i.e., telling the client in what ranges the bands exists. Therefore the catalog becomes an integral component (discovery, evaluation) in the process of accessing a resource.
6.2. Records and catalogs
The atomic unit of information in a catalog is the record.
A catalog is a collection of related 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 a 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 encouraged, 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.
6.3. Common components
This Standard defines the following common components that may be used to deploy a catalog.
The core schema of a record.
The definition of a collection resource that groups and describes a set of related records (i.e., a catalog).
The definition of a core set of query parameters for searchable catalogs.
An API that allows a catalog to be searched using logically connected predicates that can include spatial and/or temporal predicates.
Using these common components 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; or
a searchable catalog with records accessible through an API endpoint.
A special use case of the searchable catalog is the local resources catalog. The OGC API resource tree has several endpoints that provide lists of resources. Examples of such endpoints include the /collections and the /processes endpoints. One can readily imagine a large deployment of APIs implementing OGC API building blocks with thousands of collections where the ability to search would enhance the client’s interaction with the server. Using the common components defined in this Standard, these endpoints can be extended to support catalog-like searching using filter expressions that may also include spatial and/or temporal predicates. Implementations of OGC API endpoints extended in this way behave like a catalog of local resources.
6.4. Record Schema
The core set of record properties that may be used to describe a resource include the id, type, title, description and geometry. A complete definition of a record can be found in clause Core properties.
The choice of which properties to include in the set of core properties was primarily informed by the following record models:
The core catalog schema from the OGC® Catalogue Services 3.0 suite of standards; and
The Data Catalog Vocabulary (DCAT) version 2 and the GeoDCAT-AP version 3.0.0 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 a record.
The expectation is 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.). The core can also be 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 Standard does not mandate any particular encoding for a record or a catalog, it does define conformance classes for two encodings:
Other encodings are allowed but are not described in this Standard.
Accessing a catalog deployed as static files is described in the Crawlable records deployment clause.
Accessing a catalog through an implementations of the Records API is described in the Records access clause.
6.5. Record collection (catalog)
A record collection or catalog is an object that groups and describes a set of related records. The catalog is the primary access point from which a deployed set of records can be accessed. Having found a 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 catalog 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 catalog include id, type, title, description, extent and links. A complete definition of a catalog can be found in clause Record collection. It should be noted that this list of properties is very similar to the list of properties defined for a catalog record. This is intentional since the catalog can be considered a record that describes a related set of records.
It is anticipated that this set of properties will be extended to enrich the information content of the collection metadata to suit specific needs.
6.6. Records API
6.6.1. Overview
An implementation of the Records API Standard enables retrieving a subset of records from a catalog using a logically connected set of predicates that may include spatial and/or temporal predicates.
The Records API extends the OGC API — Features — Part 1: Core Standard to:
Provide API patterns and encodings to facilitate further lowering the barrier to finding the existence of spatial resources on the Web; and
Provide functionality comparable to that of the 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 Standards ecosystem.
To facilitate access to records in a catalog, the OGC API — Feature — Part 1: Core Standard has been:
Extended with additional parameters at the /collections/{collectionId}/items endpoint, and
Constrained to a single information model (i.e., the record).
Table 5 summarizes the access paths and relation types defined in this Standard.
Table 5 — Records API Paths
Path Template | Relation | Resource |
---|---|---|
Common | ||
/ | Landing page | |
/api | service-desc or service-doc | API Description (optional) |
/conformance | conformance | Conformance Classes |
/collections | data | Metadata describing the catalogs available from this API implementation instance. |
/collections/{catalogId} | collection | Metadata describing a catalog which has the unique identifier {catalogId} |
Records | ||
/collections/{catalogId}/items | items | Search results based on querying the service for records satisfying 0..n query parameters. |
/collections/{catalogId}/items/{recordId} | item | Record of metadata which has the unique identifier {recordId}. |
Where:
{catalogId} = An identifier for a specific catalog; and
{recordId} = An identifier for a specific record within a collection.
6.6.2. API Behaviour Model
The Records API Standard is designed to be compatible but not conformant with the OGC Catalogue Service for the Web (CSW) Standard. This allows OGC API — Records implementations and CSW implementations to co-exist in a single processing environment.
The 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 1 .. n catalog collections residing in a CSW backend repository. The model 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 Records 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.
6.6.3. Search
This Standard defines three levels of search capability of increasing complexity and capability.
The first or core level of search capability is based on OGC API — Features and thus supports:
bounding box searches,
time instant or time period searches, and
equality predicates (i.e., property=value).
The Records API Standard 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.
The second level of search capability extends the search API so that it is compatible with the 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. OGC API — Records — Part 2: OpenSearch will define the requirements for a catalog that supports OpenSearch.
The third level of search capability, defined by the Filtering requirements class, supports complex filter expressions using a rich set of logically connected query predicates.
6.6.4. Dependencies
The search API requirements and conformance classes defined in this Standard for accessing records from a searchable catalog is an extension of the OGC API — Features — Part 1: Core Standard. An implementation of a searchable catalog API must first satisfy the appropriate Requirements Classes from OGC API — Features — Part 1: Core. [req-mappings], identifies these requirements.
Table 6 — Required OGC API — Features — Part 1: Core Requirements Classes for Records Access
Table 7 — Required OGC API — Features — Part 1: Core Requirements Classes for Record Access
API — Features Requirements Classes |
http://www.opengis.net/spec/ogcapi_features-1/1.0/req/core/f-op |
http://www.opengis.net/spec/ogcapi_features-1/1.0/req/core/f-success |
7. Common Components
7.1. Overview
This clause specifies requirements classes that define common components that can be used to define various catalog deployments.
7.2. Requirements Class “Record Core” (Common Component)
7.2.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
---|---|
Target type | Document model |
Conformance class | Conformance class A.1: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core |
Normative statements | Requirement 1: /req/record-core/mandatory-properties-record Requirement 2: /req/record-core/time-instant Requirement 3: /req/record-core/time-interval Requirement 4: /req/record-core/time-instant-interval Requirement 5: /req/record-core/time-zone Requirement 6: /req/record-core/contact Requirement 7: /req/record-core/license Requirement 8: /req/record-core/links Requirement 9: /req/record-core/templated-link Requirement 10: /req/record-core/templated-link-header Requirement 92: /req/record-core/default-mediatype |
The Record Requirements Class defines the requirements for a catalog record which is the atomic unit of information of a catalog.
It is expected that the information necessary to populate the fields/properties of a catalog record is readily available for any resource that is being registered in the catalog.
The expectation is that the schema of a record will be extended to describe specific resource types (e.g., datasets, services, etc.) as well as also extended by information communities wishing to enrich the information content of the record to suit their needs.
Although this Standard does not mandate any particular encoding for a record, this document does define conformance classes for two encodings:
Other encodings are allowed but are not described in this document.
7.2.2. Core properties
Table 8 and Table 9 define the set of properties, called the core properties, that may be included in a record.
Table 8 — Core properties related to the catalog record
Table 9 — Core properties related to the resource
Property | Requirement | Description | GeoJSON key |
---|---|---|---|
type | optional | The nature or genre of the resource described by this record. | properties.type |
title | optional | A human-readable name given to the resource described by this record. | properties.title |
description | optional | A free-text description of the resource described by this record. | properties.description |
geometry | optional | A spatial extent associated with the resource described by this record. Can be null if there is no associated spatial extent. | geometry |
time | optional | A temporal extent associated with the resource described by this record. Can be null if there is no associated temporal extent. | time |
keywords | optional | A list of free-form keywords or tags associated with the resource described by this record. | properties.keywords |
themes | optional | A knowledge organization system used to classify the resource described by this resource. | properties.themes |
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, assigned by an external entity, for the resource described by this record. | properties.externalIds |
formats | optional | A list of available distributions for the resource described by this record. | properties.formats |
contacts | optional | A list of contacts qualified by their role(s) in association to the record or the resource described by this record. | properties.contacts |
license | optional | The legal provisions under which the resource described by this record 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 |
Identifier | /req/record-core/mandatory-properties-record |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | Each record in a response SHALL contain all the mandatory properties listed in Table 8. |
B | The identifier of a record (id) cannot be NULL or the empty string. |
7.2.3. Record extensions
In Table 8 and Table 9 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 suit specific use cases or requirements. For example, a catalog record may be extended to include additional properties from the GeoDCAT vocabulary. The fact that a catalog record has been extended in this way can be advertised using the conformsTo property. The conformsTo property is a list of identifiers that indicate each extension used in a record. This Standard does not define the specific identifiers that are used to identify specific extensions; it simply provides a place where these identifiers can be listed.
Identifier | /rec/record-core/extensions |
---|---|
A | If the core record is extended with additional properties, the requirements of the extension SHOULD be formally published. |
B | The formal publication SHOULD define an identifier that can be included in the conformsTo list to allow clients to identify that the record has been extended according to the requirements defined in the publication. |
C | The identifier SHOULD be an active identifier (e.g., an URL) that resolves to this publication or eventually leads to it through intermediate resources. |
D | The formal publication SHOULD include requirements about any formal vocabularies that SHOULD be used to populate core and extension record properties. |
In the case where all the records of a catalog use the same set of extensions, and to prevent unnecessary duplication, there is also a conformsTo property at the catalog level that may be used to declare which extensions are used in all records of the catalog.
NOTE: Extensions listed at the catalog and record levels are cumulative.
7.2.4. Type
In order to facilitate the ability to discover resources of a particular type(s), this Standard makes the following recommendations:
Identifier | /rec/record-core/type |
---|---|
A | A record SHOULD include the type property to indicate the nature or genre of the resource that the record is describing. |
B | The list of codes that can occur in records of a catalog for the property type SHOULD use a formal, controlled vocabulary defined by an organization (e.g., ISO), or a community of interest/domain (e.g., WMO). |
C | The list of codes that can occur in records of a catalog for the property type SHOULD be listed as enum values in the API definition of the record schema. |
In addition, links to external resources describing the record type vocabulary used to populate the type property are recommended, as described in Associations and Links.
7.2.5. Title and description
In order to facilitate the discovery of resources utilizing keyword or free-text searches, this Standard makes the following recommendation:
Identifier | /rec/record-core/record-title |
---|---|
A | A record SHOULD include the title property to provide a human-readable name for the resource that the record describes and also to provide a target of possible text searches of the catalog. |
Identifier | /rec/record-core/record-description |
---|---|
A | A record SHOULD include the description property to provide a free-text description of the resource that the record describes. |
7.2.6. Spatial information
The spatial characteristic of the resource described by a record is specified using the optional geometry property.
For example, the JSON requirements class makes the geometry member mandatory because the record encoding (i.e., GeoJSON) requires that the geometry member be mandatory.
7.2.7. Temporal information
7.2.7.1. Overview
Many records have a geometry property that provides information about the primary spatial characteristics of the resource described by the record. Records often also have temporal information. In most cases time is either an instant (e.g., an event) or an interval (e.g., an activity or a temporal validity). In OGC API Records the temporal property is reflected in the datetime parameter which supports temporal filtering.
This Standard added support for the most common temporal case: Associating a resource with a single temporal instant or interval in the Gregorian calendar. More complex cases and other temporal coordinate reference systems are out-of-scope for this Standard and might be specified in future extensions.
Records can have multiple properties that describe the temporal characteristics of the resource(s) that the record describes.
In many records all temporal properties are instants (represented by a date or a timestamp) and intervals are described using two temporal instants, one for the start and one for the end.
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 Observations & Measurements standard, where an observation has multiple temporal properties including “phenomenon time,” “result time,” and “valid time.”
This Standard does not place any constraints 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.
Identifier | /rec/record-core/time |
---|---|
A | A record SHOULD include a time property that indicates the temporal aspect of the resource that the record describes. |
B | If temporal information about the resource is not available then the time property SHOULD, even though it is optional, still be included in the record and its value SHOULD be set to null. |
This time property is set by the publisher of the record and describes characteristic temporal information (an instant or an interval) associated with the resource described by a record. This time property can thus be used by naive clients without the need to inspect or understand the schema of an extended record. If included in the record, the value of the time property is either null (no temporal information) or an object encoding a time instant or interval.
Table 10 — Properties of the “time” object
Property | Type | Description |
---|---|---|
date | string | An instant with the 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. |
If both values interest, including both an instant and an interval is valid. 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.
The “time” object may be extended with additional properties. Clients processing a “time” object must be prepared to parse additional properties. Clients should ignore properties that they do not understand. For example, in cases where the “time” property neither includes an “instant” nor “interval”, a client may process the record as a record without temporal information.
NOTE: The data publisher decides how additional temporal properties are encoded in a record. The schema for the time property does not imply a recommendation that temporal properties reuse the same schema. For example, it is expected that a date-valued record properties will in most cases be represented as a string with an RFC 3339 date value.
7.2.7.2. Instants
An instant is a value that conforms to RFC 3339 (Date and Time on the Internet: Timestamps) and is consistent with one of the following production rules of the ISO 8601 profile specified in the RFC:
full-date (e.g., "1969-07-20")
date-time (e.g., "1969-07-20T20:17:40Z")
Conceptually, an instant is a “temporal entity with zero extent or duration” [Time Ontology in OWL]. In practice, the temporal position of an instant is described using data types where each value has some duration or granularity. The value should be described with a granularity that is sufficient for the intended use of the data.
In the case of a timestamp the granularity is a second or smaller. All timestamps must be in the time zone UTC (“Z”).
In the case of a date the granularity is a day and dates as instants will be used when a granularity of a day independent of its timezone is sufficient for the intended use of the data. If that is not the case and, for example, the timezone is important for the intended use, the temporal information should be provided as an interval with start and end timestamps.
NOTE 1: This Standard only provides guidance as to how record data is represented in JSON. It is out-of-scope for this Standard to provide guidance how to cast record data to other data types. The Common Query Language (CQL2) standard uses the same model of instants and intervals as used here and includes additional guidance on how to compare values.
Example 1 — A date
"time" : {
"date": "1969-07-20"
}
Example 2 — A timestamp
"time" : {
"timestamp": "1969-07-20T20:17:40Z"
}
Dates and timestamps are the initial range of instant values. The range may be extended in the future to support additional use cases. Clients processing values of time must be prepared to receive other values. Clients may ignore values that they do not understand.
Identifier | /req/record-core/time-instant |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the time object in a record includes a date member, the value SHALL conform to RFC 3339 (Date and Time on the Internet: Timestamps) and match the production rule full-date. |
B | If the time object in a record includes a timestamp member, the value SHALL conform to RFC 3339 (Date and Time on the Internet: Timestamps) and match the production rule date-time. |
NOTE 2: date and timestamp are different datatypes and so comparing them will require a cast. This Standard does not prescribe how types are cast. The evaluation of comparison expressions that involve date and timestamp values will, therefore, be system dependent.
7.2.7.3. Intervals
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 is represented by a double-dot string (..) for the start/end. This follows the convention of ISO 8601-2 for an open start or end.
Example 1 — An interval with dates
"time" : {
"interval": [
"1969-07-16",
"1969-07-24"
]
}
Example 2 — An interval with timestamps
"time" : {
"interval": [
"1969-07-16T05:32:00Z",
"1969-07-24T16:50:35Z"
]
}
Example 3 — An half-bounded interval
"time" : {
"interval": [
"2014-04-24T10:50:18Z",
".."
]
}
The options described above are the initial range of interval values — the granularity is either days or (sub-)seconds and interval ends may be unbounded. The value range may be extended in the future to support additional use cases. Clients processing values of time must be prepared to receive other values. Clients may ignore values that they do not understand.
Identifier | /req/record-core/time-interval |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the time object in a record includes an interval member, each array i.e., SHALL be a string that is a double-dot (“..”) or conforms to RFC 3339 (Date and Time on the Internet: Timestamps) and match one of the following production rules: full-date (a date) or date-time (a timestamp). |
B | If the start is a date, the end SHALL be a date, too, or “..”. |
C | If the start is a timestamp, the end SHALL be a timestamp, too, or “..”. |
7.2.7.4. Instants and intervals
Identifier | /req/record-core/time-instant-interval |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the time object in a record includes both a date and a timestamp member, the full-date parts SHALL be identical. |
B | If the time object in a record includes both a timestamp and an interval member with start/end dates, the interval SHALL contain the date of the timestamp. |
C | If the time object in a record includes both a timestamp and an interval member with start/end timestamps, the interval SHALL contain the timestamp. |
D | If the time object in a record includes both a date and an interval member with start/end dates, the interval SHALL contain the date. |
E | If the time object in a record includes both a date and an interval member with start/end timestamps, the interval SHALL include timestamps on the date. |
7.2.7.5. Time zones
Identifier | /req/record-core/time-zone |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | Timestamps in the time member in a record SHALL use UTC (“Z”) as the time zone. |
7.2.8. Keywords and Themes
A record allows for one keywords and one to many 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 searchable or local resources 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.
Identifier | /rec/record-core/keywords-themes |
---|---|
A | Implementations SHOULD use the keywords property to provide free-form terms or tags associated with the resource(s) described by the current record. |
B | Implementations SHOULD use the themes property to enumerate 1..n concepts, and their respective knowledge organization system/controlled vocabulary, associated with the resource(s) described by the current record. |
The following provides an example of using keywords for free form terms (e.g., tags) as well as themes to articulate terms from formal vocabularies or classification systems.
{
.
.
.
"keywords": [
"total",
"ozone",
"level 1.0",
"column",
"dobson",
"brewer",
"saoz"
],
"themes": [
{
"concepts": [
{
"id": "dobson",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_dobson"
},
{
"id": "brewer",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_brewer"
},
{
"id": "vassey",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_vassey"
},
{
"id": "pion",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_pion"
},
{
"id": "microtops",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_microtops"
},
{
"id": "spectral",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_spectral"
},
{
"id": "hoelper",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_hoelper"
},
{
"id": "saoz",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_saoz"
},
{
"id": "filter",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_filter"
}
],
"scheme": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode"
},
{
"concepts": [
{
"id": "atmosphericComposition",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_atmosphericComposition"
},
{
"id": "pollution",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_pollution"
},
{
"id": "observationPlatform",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_observationPlatform"
},
{
"id": "rocketSounding",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_rocketSounding"
}
],
"scheme": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode"
}
]
.
.
.
}
Listing 1 — Keywords and themes Example
7.2.9. Formats
The formats property indicates the list of available distribution formats for the resource that a record describes. These can include both physical and digital distribution formats.
The following example illustrates a resources that is a available is several formats.
"formats": [
{ "name": "TK50" },
{ "name": "GRIB", "mediaType": "application/x-grib" },
{ "mediaType": "application/zip"}
]
Listing 2 — Formats Example
Identifier | /rec/record-core/format |
---|---|
A | The value of the mediaType property should be taken from the list of IANA media types. |
7.2.10. Language handling
7.2.10.1. Overview
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.
7.2.10.2. Language of the record
Identifier | /rec/record-core/langs |
---|---|
A | The language used to express text values in a record SHOULD be specified using the language property of the record. |
B | The list of other languages in which a record may be retrieved SHOULD be specified in the record using the languages property. |
C | If one or more language-specific links are included in the links section of a record (path: links) pointing to alternate language representations of this record, the language used as the hreflang value SHOULD be one of the languages listed as the value of the languages property of the record. |
The link object and the templated link object are based on RFC 8288 (Web Linking) which 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 languages.
A server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs 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 approach how such a capability is supported by a server.
NOTE 1: 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/…); and
An additional query parameter (for example, “language” or “l”) that overrides the Accept-Language header of the HTTP request.
NOTE 2: There is no provision in the record schema to allow a response containing text fields simultaneously presented in multiple languages (e.g., multiple titles in different languages). To obtain a record in multiple languages would require multiple requests to the server each negotiating to a desired language.
7.2.10.3. Language of the resource
Identifier | /rec/record-core/resource-langs |
---|---|
A | If there are one or more languages associated with the resource that a catalog record describes, those languages SHOULD be listed in the record using the resourceLanguages property. |
7.2.11. Contacts
Identifier | /req/record-core/contact |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the contacts property is present and the logo property is included in the contact object then the link relation SHALL be icon and the media type SHALL be an image media type. |
B | If the contacts property is included and the links property is included in the contact object then the link relation about SHOULD be used for each listed link and the media type SHALL indicate the content type of the link (e.g., text/html for a company’s web page versus text/vcard for a virtual contact file). |
Identifier | /rec/record-core/contact |
---|---|
A | A contact country property SHOULD use ISO 3166-1 notation. |
7.2.12. License
A record may have one license property. If present, the value of this property should be a code, convenient for filtering records.
Identifier | /req/record-core/license |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the resource is being made available under a common license then a SPDX license identifier SHALL be used as the value of the license property. |
B | If the resource is being made available under:
|
Statement | then the value of the license property SHALL be the value other and one or more links (relation: license) SHALL be included in the links section of the record pointing to the file(s) that contain the text of the licenses. |
NOTE: There is also the case of a resource that is private or unpublished and is thus unlicensed. In this case do not register such a resource in the catalog in the first place since there is no point in making such a resource discoverable.
7.2.13. Associations and Links
A record must contain a links section and may contain a linkTemplates section. These sections contain navigation links and/or association links.
Navigation links are meant to encode relationships between catalog entities (i.e., collections and records). Navigation links in the links section can include links to the collection (relation: collection) of which a record is a member, alternative representations (relation: alternate) of the record, and — in the context of an API — navigation links to previous (relation: prev or previous) or next (relation: next) records in a chain of records. Links in the links section may also be used to organize records in a hierarchy (relation: root, relation: parent, relation: child).
Identifier | /req/record-core/links |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | Each record SHALL, if it is a member of a catalog, include a link (relation: collection) pointing to the catalog of which this record is a member. |
B | Only a single link (relation: collection) SHALL be included in a record. This implies that a record can only be a member of a single catalog. |
Identifier | /rec/record-core/links |
---|---|
A | Each record SHOULD include one or more links (relation: describes) pointing to the resource(s) that this record describes. |
B | Each record SHOULD include a link (relation: self) to itself. |
C | Each record SHOULD, if they exist, include typed links (relation: alternate) to each alternative representation of this record. |
NOTE 1: The term “typed link” means a link that specifies a value for the type attribute.
Links in the links section may also encode canonical URIs for record properties such as type and license.
Identifier | /rec/record-core/links-type |
---|---|
A | If there is a cannonical URI for the value of the type property of a record, a link (relation: type) to that canonical URI SHOULD be included in the links section of the record. |
Identifier | /rec/record-core/links_iana |
---|---|
A | Links relations for links in the links or linkTermplates sections SHOULD be taked from the official IANA Link Relation Types registry. |
Association links point to the resource(s) being described by a record. Such links allow binding to a resource once it has been discovered by searching a catalog. Depending on how the target resource of a record is represented and how it may be accessed, there may be one or more association links. For example, if the target resource is an Earth observation imagery file, links may point to the individually accessible bands of the image file.
Association links are also meant to point to other records related to the containing record. For example, consider a record that describes a set of vector features and another record that describes a rendering style for that feature set. These two records may, in their respective links sections point to each other to encode this “styles”/“styled-by” relationship.
Finally, association links are meant to point to other resources external to the catalog that are related to the containing record or the resource(s) that the record describes.
Identifier | /rec/record-core/associations_relate |
---|---|
A | Implementations SHOULD use links in the links sections to represent associations to other internal or external resources related to the current record or the resource the record is describing. |
In some instances, additional context may be desirable or required to access (or bind to) the resource(s) being described by a record. This is the case when, for example, access to the resource is through a service interface that requires mandatory parameters to be provided. An implementation of the OGC Web Map Service (WMS) Standard is an example of such a service. It may also be the case that efficient access to the resource would be facilitated by providing additional context. Accessing data from a large data repository such as a data cube would be more efficient if the context of the query used to discover the resource (e.g., bbox, datetime) were passed down to the link used to access the data.
Identifier | /rec/record-core/associations-templated |
---|---|
A | If access to the resource(s) requires or would be facilitated by additional context (e.g., a bounding box) then templated links SHOULD be used. |
NOTE 2: This Standard does not define any specific link relations that should be used for links in the links or linkTemplates 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 example uses links and link templates to point to resources related to a record. The describes links can be used to retrieve the resources described by the record. Other links, such as enclosure, can be used to retrieve the same information in archived formats.
{
.
.
.
"links": [
{
"rel": "collection",
"href": "https://woudc.org/data/dataset_info.php"
},
{
"rel": "describes",
"title": "OGC Web Map Service (WMS)",
"href": "https://geo.woudc.org/ows?service=WMS&request=GetCapabilities"
},
{
"rel": "describes",
"title": "OGC Web Feature Service (WFS)",
"href": "https://geo.woudc.org/ows?service=WFS&request=GetCapabilities"
},
{
"rel": "preview",
"type": "image/png",
"title": "Total Ozone Preview Image",
"href": "https://woudc.org/data/preview.png"
},
{
"rel": "enclosure",
"type": "text/html",
"title": "Web Accessible Folder (WAF)",
"href": "https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1",
"created": "2015-01-23T00:00:00Z",
"updated": "2015-01-23T00:00:00Z"
},
{
"rel": "enclosure",
"type": "application/zip",
"title": "Static dataset archive file",
"href": "https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip",
"created": "2015-01-23T00:00:00Z",
"updated": "2015-01-23T00:00:00Z"
},
{
"rel": "search",
"type": "text/html",
"title": "Data Search / Download User Interface",
"href": "https://woudc.org/data/explore.php?dataset=totalozone"
},
{
"rel": "license",
"href": "https://woudc.org/about/data-policy.php"
}
],
"linkTemplates": [
{
"rel": "describes",
"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={format}",
"variables": {
"bbox": {
"description": "...",
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"minItems": 4,
"maxItems": 4
},
"crs": {
"description": "...",
"type": "string",
"enum": [
"EPSG:4326",
"EPSG:3857"
]
},
"width": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"height": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"format": {
"type": "string",
"enum": [
"application/vnd.google-earth.kml+xml",
"application/vnd.google-earth.kmz",
"image/png",
"image/jpeg",
"image/gif",
"image/png; mode=8bit",
"application/x-pdf",
"image/svg+xml",
"image/tiff"
]
}
}
},
{
"rel": "describes",
"title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations",
"uriTemplate": "https://geo.woudc.org/ows?service=WFS&version=1.1.0&request=GetFeature&typeName=woudc:totalozone&maxFeatures={maxFeatures}&outputFormat={outputFormat}",
"variables": {
"maxFeatures": {
"type": "number",
"default": 10
},
"outputFormat": {
"type": "string",
"enum": [
"text/xml; subtype=gml/3.1.1",
"text/xml; subtype=gml/2.1.2; driver=ogr",
"application/json; subtype=geojson",
"application/vnd.google-earth.kml+xml",
"application/vnd.shp",
"text/plain",
"text/csv"
],
"default": "text/xml; subtype=gml/2.1.2; driver=ogr"
}
}
}
]
}
Listing 3 — Example of Links and Link-Templates in a Record
The following example shows links and link-templates specified in the HTTP header of a response.
Link-Template: <https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}&bbox={bbox}&layers=stations&width={width}&height={height}&format={format}>; rel="describes"; title="World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations"; varBase="https://geo.woudc.org/variables
Link-Template: <https://geo.woudc.org/ows?service=WFS&version=1.1.0&request=GetFeature&typeName=woudc:totalozone&maxFeatures={maxFeatures}&outputFormat={outputFormat}; rel="describes"; title="World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations"; varBase="https://geo.woudc.org/variables
Link: <https://woudc.org/data/dataset_info.php>; rel="collection"
Link: <https://geo.woudc.org/ows?service=WMS&request=GetCapabilities>; rel="describes"; title="OGC Web Map Service (WMS)"
Link: <https://geo.woudc.org/ows?service=WFS&request=GetCapabilities>; rel="describes"; title="OGC Web Feature Service (WFS)"
Link: <https://woudc.org/data/preview.png>; rel="preview"; type="image/png"; title="Total Ozone Preview Image"
Link: <https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1>; rel="enclosure"; type="text/html", title="Web Accessible Folder (WAF)"; created="2015-01-23T00:00:00Z"; updated="2015-01-23T00:00:00Z"
Link: <https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip>; rel="enclosure"; type="application/zip", title="Static dataset archive file"; created="2015-01-23T00:00:00Z"; updated="2015-01-23T00:00:00Z"
Link: <https://woudc.org/data/explore.php?dataset=totalozone">; rel="search"; type="text/html"; title="Data Search / Download User Interface"
Link: <https://woudc.org/about/data-policy.php>; rel="license"
Listing 4 — Example of Links and Link-Templates in HTTP Headers
NOTE 3: Care should be exercised when there is a large number of links that need to be presented. In such cases, it would be prudent to avoid encoding all the links in the HTTP header and instead including them in the body of the response in the link and/or link templates sections.
7.2.14. Templated links with variables
The OGC API — Records Standard uses links to express associations between resources including links that bind to the resource(s) being described by a record. In some situations, a static link does not adequately express all the information necessary to retrieve the referenced resource OR does not allow for the resource to be retrieved in an efficient manner.
Consider the case where a record describing a coverage resource is discovered by searching the catalog using a spatial constraint (e.g., a bbox). Further consider that the found record contains a link to retrieve the coverage. Using a static link would only allow for retrieval of the entire coverage or a subset unrelated to the user’s original catalog query. Using a templated link, however, would allow the context of the catalog query (i.e., the bbox) to be passed to the retrieval link as a substitution variable. The templated link with all substitution variables resolved would thus retrieve the subset of the coverage that corresponds to the spatial constraint used to discover the record in the first place which presumably represents the area of interest.
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 instance such as for WMS or WFS implementations is not sufficient to access resources offered by those services. Additional information in the form of request parameters and values is required in order to have a complete link to a resource. A templated link with variables can provide this additional context.
This Standard defines a new schema, linkTemplate.yaml, based on the 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 to retrieve the definition of the specified substitution variable.
Identifier | /req/record-core/templated-link |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | A templated link SHALL be defined by the following schema fragment:
--- |
B | The uriTemplate member SHALL supply the templated link URI. |
C | Substitution variables in the templated link URI SHALL have the form {variable name}. |
Identifier | /rec/record-core/templated-link |
---|---|
A | A dictionary of substitution variable definitions SHOULD be defined for templated links. |
B | The dictionary MAY either be specified in-line in the link using the variables member or substitution variable definitions MAY be retrieved by appending the name of the variable to a base URI specified using the varBase member. |
Identifier | /req/record-core/templated-link-header |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | A templated link that appears in a HTTP header SHALL be encoded according to The Link-Template HTTP Header Field specification. |
The 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.
{
"rel": "describes",
"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={format}",
"variables": {
"bbox": {
"description": "...",
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"minItems": 4,
"maxItems": 4
},
"crs": {
"description": "...",
"type": "string",
"enum": [
"EPSG:4326",
"EPSG:3857"
]
},
"width": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"height": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"format": {
"type": "string",
"enum": [
"application/vnd.google-earth.kml+xml",
"application/vnd.google-earth.kmz",
"image/png",
"image/jpeg",
"image/gif",
"image/png; mode=8bit",
"application/x-pdf",
"image/svg+xml",
"image/tiff"
]
}
}
}
Listing 6 — Templated link with in-line dictionary of substitution variables:
{
"rel": "item",
"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": "variables.json"
}
Listing 7 — Templated link with varBase URI for retrieving substitution variable definitions:
CLIENT SERVER
| |
| GET variables/bbox HTTP/1.1 |
| Host: example.org |
| Accept: application/json |
|---------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "bbox": { |
| "description": "...", |
| "type": "array", |
| "items": { |
| "type": "number", |
| "format": "double" |
| }, |
| "minItems": 4, |
| "maxItems": 4 |
| } |
| } |
|<----------------------------------------------------------|
Listing 8 — Using varBase to retrieve the definition of the variable bbox
7.2.15. Resource timestamps
A record 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 representation 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 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.
7.2.16. Record encodings
This Standard defines requirements classes for JSON and HTML encoding of a record. See Encodings.
7.3. Requirements Class “Record Collection” (Common Component)
7.3.1. Overview
The Record Collection requirements class defines the requirements for a record collection.
A record collection is an object that provides information about and access to a set of related records. Such a collection of records is also referred to as a catalog.
The schema for the catalog is an extension of the collection schema defined in OGC API — Features Standard.
While 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 catalog in the Records API conformance class. Otherwise, the catalog 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 Standard does not mandate any particular encoding for a catalog, two conformance classes are defined:
Other encodings are allowed but are not described in this document.
7.3.2. Catalog schema
Table 11 defines the set of properties that may be used to describe a catalog.
Table 11 — Catalog properties
Property | Requirement | Description |
---|---|---|
id | required | A unique identifier for this catalog. |
created | optional | The date this collection was created. |
updated | optional | The more recent date on which this collection was changed. |
conformsTo | optional | The extensions/conformance classes used in this catalog object. |
type | required | Fixed value of “Collection”. |
itemType | optional | Fixed value of “record”, “catalog” or both. |
title | optional | A human-readable name given to this catalog. |
description | optional | A free-text description of this catalog. |
extent | optional | The spatiotemporal coverage of this catalog. |
crs | optional | A list of coordinate reference systems used for spatiotemporal values. |
keywords | optional | A list of free-form keywords or tags associated with this collection. |
themes | optional | A knowledge organization system used to classify this collection. |
language | optional | The language used for textual values (i.e., titles, descriptions, etc.) of this collection object. |
languages | optional | The list of other languages in which this collection object is available. |
recordLanguages | optional | The list of languages in which records from the collection can be represented. |
contacts | optional | A list of contacts qualified by their role(s). |
license | optional | The legal provisions under which this collection is made available. |
rights | optional | A statement that concerns all rights not addressed by the license such as a copyright statement. |
recordsArrayName | optional | The name of the array property in the catalog used to encode records in-line. The default value is records. |
records | optional | An array of records encoded in-line in the catalog. |
links | required | A list of links related to this catalog. |
linkTemplates | optional | A list of link templates related to this catalog. |
schemes | optional | A list of schemes related to this catalog. |
NOTE: The properties id, itemType, title, description, extent, crs and links are inherited from OGC API — Features — Part 1: Core. |
Identifier | /req/record-collection/mandatory-properties-collection |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | A catalog SHALL include all the mandatory properties listed in Table 11. |
7.3.3. Catalog extensions
In Clause 7.3.2 this Standard defines a set of core properties for describing a catalog. It is anticipated that this set of properties will be extended to suit specific use cases or requirements. The conformsTo property is a list of identifiers that indicate each extension used in the description of the catalog. This Standard 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 the case where all the records of a catalog use the same set of extensions, and to prevent unnecessary duplication, the conformsTo property of the catalog can also be used to declare which extensions are used that apply to all records.
See Record extensions.
7.3.4. i.e., type
A catalog can include references to records, other catalogs or both. A catalog can also contain an array of catalog records.
Identifier | /req/record-collection/itemType |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | If a catalog homogeneously references or contains records then, its itemType property SHALL be a string with the fixed value of record. |
B | If a catalog homogeneously references other catalogs then, its itemType property SHALL be a string with the fixed value of catalog. |
C | If a catalog references or contains records and references other catalogs then, its itemType property SHALL be an array of strings whose elements enumerate the types of resources referenced/contained by this catalog (i.e., record and catalog). |
7.3.5. Title and description
In order to facilitate the discovery of resources utilizing keyword or free-text searches, this Standard makes the following recommendation:
Identifier | /rec/record-core/catalog-title |
---|---|
A | A catalog SHOULD include the title property. |
Identifier | /rec/record-core/catalog-description |
---|---|
A | A catalog SHOULD include the description property. |
7.3.6. Keywords and Themes
Identifier | /rec/record-collection/keywords-themes |
---|---|
A | Implementations SHOULD use the keywords property to provide free-form terms or tags associated with this catalog. |
B | Implementations SHOULD use the themes property to enumerate 1..n concepts, and their respective knowledge organization system/controlled vocabulary, associated with the catalog. |
See Keywords and Themes.
7.3.7. Language handling
Identifier | /rec/record-collection/langs |
---|---|
A | The language used to express text values in a catalog SHOULD be specified using the language property. |
B | The list of other languages in which the catalog may be retrieved SHOULD be specified using the languages property. |
C | If one or more language-specific links are included in the links section of a catalog (path: links) pointing to alternate language representations of this catalog, the language used as the hreflang value SHOULD be one of the languages listed as the value of the languages property of the catalog. |
Identifier | /rec/record-collection/record-langs |
---|---|
A | The languages in which the records of the catalog can be represented SHOULD be listed using the recordLanguages property. |
See Language handling.
7.3.8. Contacts
Identifier | /req/record-collection/contact |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | See requirement /req/record-core/contact. |
7.3.9. License
Identifier | /req/record-collection/license |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | See requirement /req/record-core/license. Replace all instances of the term resource with the term catalog. |
7.3.10. Records and RecordsArrayName
7.3.10.1. Overview
Thus a catalog may simultaneously include links to individual records, a link to an API endpoint for accessing records and also include records encoded in-line in the catalog.
7.3.10.2. Referencing individual catalog records
Identifier | /req/record-collection/links-record |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | A link (relation: item) SHALL be included in the links section of the catalog for each individually referenced record that is a member of this catalog. |
A crawlable catalog is an example of catalog where the records can be individually accessed via links (relation: item) in the catalog’s links section.
7.3.10.3. Referencing records accessible via an API
Identifier | /req/record-collection/links-records |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | A link (relation: items) SHALL be included in the links section of the catalog pointing to an endpoint for accessing the records of this catalog via an API. |
A searchable catalog is an example of a catalog where the records are accessed from an API endpoint identified using a link (relation: items) in the catalog’s links section.
7.3.10.4. Encoding records in-line
Identifier | /req/record-collection/records |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | Records encoded in-line in the catalog SHALL be encoded using an array property named records. |
A local-resources-catalog is an example of a catalog where its records are encoded in-line in the catalog. In the case of a local resources catalog, however, the name of the array property containing the records is typically named something other than “records”.
Identifier | /req/record-collection/records-array-name |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | If the name of the in-line records array property in the catalog is changed to something other than records then that name SHALL be indicated in the catalog using a property named recordsArrayName. |
For example, a local resources catalog at the /collections endpoint uses an array property named collections to encode the records of the catalog and so the value of the recordsArrayName property in this case would be:
"recordsArrayName": "collections"
"collections": [
{... record describing a collection ... },
{... record describing a collection ... },
.
.
.
]
Listing 9
Similarly, a local resources catalog at the /processes endpoint uses an array named processes to encode the records of the catalog and so the value of the recordsArrayName property would be:
"recordsArrayName": "processes"
"processes": [
{ ... record describing a process ... },
{ ... record describing a process ... },
.
.
.
]
Listing 10
7.3.11. Other catalogs
7.3.11.1. Overview
Related catalogs may be organized as:
an unorganized set of related catalogs,
as a series of related catalogs (e.g., for paging),
as a hierarchy of related catalogs.
7.3.12. Links
Identifier | /req/record-collection/links |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | The catalog SHALL include a link (relation: self) that points to itself. |
B | The catalog SHALL include one link (relation: alternate) for each alternative representation of itself. |
7.3.14. Schemes
In various places in a catalog or catalog record property values can be qualified by an authority, scheme or namespace. Typically such schemes are represented as a URI. In order to alleviate the need to keep repeating such long URI strings, the schemes mechanism can be used to assign a short identified to each scheme and that identified can, instead, be used to qualify the value.
Consider the value atmosphericComposition that is qualified with the schema https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode. Rather than, for example, specifying this value as https//wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode:atmosphericComposition in an expression, the value categoryCode can be associated with the URI https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode and the value can be specified as categoryCode:atmosphericComposition. The schemes mechanism provides the means to associated the identifier categoryCode with the URI https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode as shown in the following JSON fragment:
"schemes": [
.
.
.
{
"scheme-id": "categoryCode",
"namespace" : "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode"
},
.
.
.
]
Listing 11
Once defined in the schemes section of a catalog, the identifier categoryCode can be used wherever the long namespace https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode would normally be used.
7.3.15. Encodings
This Standard defines requirements for JSON and HTML encoding of a catalog. See Encodings.
7.4. Requirements Class “Record Core Query Parameters” (Common Component)
7.4.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
---|---|
Target type | Web API |
Conformance class | Conformance class A.4: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters |
Normative statements | Requirement 23: /req/record-core-query-parameters/bbox Requirement 24: /req/record-core-query-parameters/datetime Requirement 25: /req/record-core-query-parameters/limit Requirement 26: /req/record-core-query-parameters/q-definition Requirement 27: /req/record-core-query-parameters/q-response Requirement 28: /req/record-core-query-parameters/type-definition Requirement 29: /req/record-core-query-parameters/type-response Requirement 30: /req/record-core-query-parameters/ids-definition Requirement 31: /req/record-core-query-parameters/ids-response Requirement 32: /req/record-core-query-parameters/externalIds-definition Requirement 33: /req/record-core-query-parameters/externalIds-response |
The Record Core Query Parameters requirements class defines a minimum set of query parameters that should be implemented at a searchable catalog endpoint. Table 12 lists this set of query parameters.
The parameters bbox, datetime, limit and ids are inherited from OGC API Features — Part 1: Core. The remaining parameters are defined in this Standard.
Table 12 — Core query parameters
Parameter name | Description |
---|---|
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. |
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. |
limit | The number of records to be presented in a response document. |
q | 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 record shall appear in the response set. |
type | An equality predicate consisting of a comma-separated list of resource types. Only records of the listed type shall appear in the response set. |
ids | An equality predicate consisting of a comma-separated list of record identifiers. Only records with the specified identifiers shall appear in the response set. |
externalIds | An equality predicate consisting of a comma-separated list of external resource identifiers. Only records with the specified external identifiers shall appear in the response set. |
prop=value | Equality predicates with any queryable not already listed in this table. |
7.4.2. Query parameters
7.4.2.1. Parameter bbox
Identifier | /req/record-core-query-parameters/bbox |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | A searchable endpoint SHALL support the Bounding Box Search (bbox) parameter as defined in the OGC API — Features — Part 1: Core Standard. |
B | All references to the term “features” in the OGC API — Features — Part 1: Core Standard SHALL be replaced by the term “records” or “local resources” as the context may indicate. |
7.4.2.2. Parameter datetime
Identifier | /req/record-core-query-parameters/datetime |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | A searchable endpoint SHALL support a Temporal Searching (datetime) parameter as defined in the OGC API — Features — Part 1: Core Standard. |
B | All references to the term “features” in the OGC API — Features — Part 1: Core Standard SHALL be replaced by the term “records” or “local resources” as the context may indicate. |
7.4.2.3. Parameter limit
Identifier | /req/record-core-query-parameters/limit |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | A searchable endpoint SHALL support a Paging (limit) parameter as defined in the OGC API — Features — Part 1: Core Standard. |
B | All references to the term “features” in the OGC API — Features — Part 1: Core Standard SHALL be replaced by the term “records” or “local resources” as the context may indicate. |
7.4.2.4. Parameter q
The q parameter provides a simple, easy-to-implement keyword search capability across one or more text fields in a record.
Identifier | /req/record-core-query-parameters/q-definition |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
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):
--- |
C | Search terms that may appear together (logical OR) in a record SHALL be separated by literal commas. |
D | Search terms that must appear together, and in the order specified, in a record SHALL be separated by one or more white space characters. |
E | Keyword searches using the q parameter SHALL be case insensitive. |
F | The specific set of text keys/fields/properties of a record to which the q operator is applied SHALL be left to the discretion of the implementation. |
The specific text fields in a record that are to be searched is not mandated in this Standard.
Identifier | /rec/record-core-query-parameters/param-q |
---|---|
A | The q operator SHOULD, at least, be applied to the following core properties:
|
Identifier | /req/record-core-query-parameters/q-response |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
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. |
C | For multiple search terms that are white space separated, only records that contain all the search terms specified, in the order specified and separated by any number of white spaces in one or more of the searched text fields SHALL be in the result set. |
For example, the following q parameter specification:
q=ocean,climate%20%09change,desalination
Listing 13
represents the query predicate:
(anytext CONTAINS 'ocean') OR
(anytext CONTAINS 'climate\s+change') OR
(anytext CONTAINS 'desalination')`
Listing 14
NOTES:
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.
7.4.2.5. Parameter type
Identifier | /req/record-core-query-parameters/type-definition |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
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): |
Statement |
--- |
Identifier | /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. |
Identifier | /req/record-core-query-parameters/type-response |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | 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. |
7.4.2.6. Parameter ids
Identifier | /req/record-core-query-parameters/ids-definition |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | A Records API implementation SHALL support the query by Ids (ids) parameter for the operation. |
B | The following OpenAPI 3.0 schema fragment SHALL define the characteristics of the ids parameter:
--- |
Identifier | /req/record-core-query-parameters/ids-response |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | Only records whose identifier match one of the identifiers specified using ids parameter SHALL be in the results set. |
7.4.2.7. Parameter externalIds
Identifier | /req/record-core-query-parameters/externalIds-definition |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
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):
--- |
Identifier | /req/record-core-query-parameters/externalIds-response |
---|---|
Included in | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
A | Only records that have an external identifier that matches one of the values listed using the externalIds parameter SHALL be in the result set. |
B | If the search value is qualified with a scheme then both the scheme and the value of the record’s external identifier SHALL match in order for the record to be in the result set. |
C | If the search value is not qualified with a scheme then only the value of the record’s external identifier SHALL match in order for the record to be in the result set. |
D | If the search value is only the scheme then the scheme component of the record’s external identified SHALL match in order for the record to be in the result set. |
7.4.2.8. Additional query parameters
This Standard defines the following URL query parameters based on the set of core properties to support record selection based on the resource type and/or an external identifier associated with the resource.
Identifier | /rec/record-core-query-parameters/additional-query-parameters |
---|---|
A | If any additional property (see additional record properties) 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):
name: <name of property> |
C | If the parameter is an array of simple values then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment):
name: <name of property> |
D | The schema property SHOULD be the same as the definition of the property from which the parameter is derived (see additional record properties). |
7.5. Requirements Class “Records API” (Common Component)
7.5.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
---|---|
Target type | Web API |
Conformance class | Conformance class A.3: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/records-api |
Prerequisites | http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core Records Core Query Parameters Record Collection Record Core |
Normative statements | Requirement 34: /req/records-api/features-api Requirement 35: /req/records-api/resource-name-mapping Requirement 36: /req/records-api/catalog-response Requirement 37: /req/records-api/catalogs-response Requirement 38: /req/records-api/records-op Requirement 39: /req/records-api/mandatory-params Requirement 40: /req/records-api/query-params Requirement 41: /req/records-api/record-op Requirement 42: /req/records-api/record-response |
Identifier | /req/records-api/features-api |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | Implementations of this requirements class SHALL implement the Core requirements class of OGC API — Features — Part 1: Core. |
The core requirements for an API that enables searching a catalog are defined by the OGC API — Features — Part 1: Core Standard.
Identifier | /req/records-api/resource-name-mapping |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | Each reference to features or feature in the narrative text of OGC API — Features — Part 1: Core Standard SHALL be replaced by the terms records or record when interpreting an OGC API — Features — Part 1: Core requirement for the Records API. |
NOTE: This requirement does not imply that the terms features or feature in the schemas or code examples of OGC API — Features — Part 1: Core should be replaced by the terms records or record. For example, the GeoJSON encoding of a record and the GeoJSON encoding of a feature both include a top-level field named type whose value is fixed to Feature as defined in the GeoJSON specification. This requirement does not imply that the value Feature should be changed to Record in this Standard since such a change would invalidate the GeoJSON document.
7.5.2. Encodings
While this Standard does not specify any mandatory response encoding, support for the following encodings is recommended.
Identifier | /rec/records-api/html |
---|---|
A | To support browsing the catalog and its records with a web browser and to enable search engines to crawl and index the catalog, implementations SHOULD consider supporting a HTML encoding. |
Identifier | /rec/records-api/json |
---|---|
A | If the records can be represented for the intended use in GeoJSON, implementations SHOULD consider supporting GeoJSON as an encoding for records and catalogs (i.e., record collections). |
B | If a catalog (i.e., record collection) can be represented for the intended use in JSON, implementations SHOULD consider supporting JSON as an encoding for a catalog (i.e., record collection). |
The encoding of a server response is determined according to the mechanisms defined in Clause 12 of the HTTP 1.1 Standard.
The Media Types sub-clause includes guidance on media types for encodings that are specified in this document.
Note that any server that supports multiple encodings will have to support a mechanism to mint encoding specific URIs for resources to express links, for example, to alternate representations of the same resource. This document does not mandate any particular approach as to how this is supported by the server.
As clients simply need to dereference the URI of the link, the implementation details and the mechanism as to how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate (“hack”) URIs in the browser address bar, can study the API definition document (e.g., the OpenAPI definition).
NOTE: Two common approaches are:
An additional path for each encoding of each resource (this can be expressed, for example, using format specific suffixes like “.html”);
An additional query parameter (for example, “accept” or “f”) that overrides the Accept header of the HTTP request.
7.5.3. Record collection response
Identifier | /req/records-api/catalog-response |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | For an operation that selects a collection object, the body of the response SHALL contain a description of the catalog based upon the following schema fragment which extends the collection.yaml schema defined in the OGC API — Features — Part 1: Core standard:
--- |
B | The collection SHALL homogeneously reference records. |
C | The value of the itemType property SHALL be a string with a fixed value of record. |
7.5.4. Record collections response
Identifier | /req/records-api/catalogs-response |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | For an operation that selects a list of collection objects, only collections where the itemType property (JSONPath: $.collections[*].itemType) is a string with the value record SHALL be considered to be catalogs. |
B | The schema of each catalog in the response SHALL be based upon the schema defined in the /req/records-api/catalog-response requirement. |
7.5.5. Records access
7.5.5.1. Operation
Identifier | /req/records-api/records-op |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | For every catalog identified in the collections response (path: /collections), the server SHALL support the HTTP GET operation at the path /collections/{collectionId}/items. |
B | The parameter collectionId is each id property in the collections response (JSONPath: $.collections[*].id) where the itemsType property (JSONPath: $.collections[*].itemType) is a string with the value record. |
Identifier | /req/records-api/mandatory-params |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | An implementation of the Records API SHALL support the parameters listed in Table 12 at the /collections/{collectionId}/items endpoint. |
B | The parameter collectionId is each id property in the collections response (JSONPath: $.collections[*].id) where the value of the itemType (JSONPath $.collections[*].itemType) is record. id is a local identifier of the record. |
7.5.5.2. Response
Identifier | /req/records-api/query-params |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | Only records satisfying all the predicates specified by the included query parameters and additional query parameters SHALL be in the result set. |
B | The implied logical operation between query parameters/additional query parameters SHALL be “AND”. |
7.5.5.3. Response encoding
Table 13 lists specific requirements based on the negotiated representation of the response.
Table 13 — Negotiated representation of response
Representation | Requirements |
---|---|
JSON/GeoJSON | Requirements Class JSON |
HTML | Requirements Class HTML |
7.5.5.4. Examples
The following is an example of a response to an OGC API — Records query operation (path: /collections/{collectionId}/items). This example shows a JSON response and the response container is a GeoJSON feature collection. Specific records are not presented in this example to illustrate the structure of the response container in GeoJSON.
{
"type": "FeatureCollection",
"timeStamp": "2021-03-06T07:10:00Z",
"numberReturned": 10,
"numberMatched": 347,
"features": [
{ ... record ... },
{ ... record ... },
{ ... record ... },
{ ... record ... },
{ ... record ... },
.
.
.
],
"links": [
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat?f=json...",
"rel": "collection",
"type": "application/geo+json",
"title": "Link to the containing collection in JSON"
},
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat?f=html...",
"rel": "collection",
"type": "text/html",
"title": "Link to the containing collection in HTML"
},
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat/items?f=json&...",
"rel": "self",
"type": "application/geo+json",
"title": "Link to this response"
},
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat/items?f=html&...",
"rel": "alternate",
"type": "text/html",
"title": "Link to this response in HTML"
},
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat/items?f=json&startIndex=20&limit=10...",
"rel": "next",
"type": "application/geo+json",
"title": "Link to the next set of records in GeoJSON"
},
{
"href": "https://www.someserver.com/ogcapi/collections/tepcat/items?f=html&startIndex=20&limit=10...",
"rel": "next",
"type": "text/html",
"title": "Link to the next set of records in HTML"
}
]
}
Listing 21 — Records Example in GeoJSON
The following is an example of a single catalog record encoded in GeoJSON. Such a record might appear in the features array of a query response or it may be the response when a specific, single record is accessed (path: /collections/{collectionId}/items/{recordId}).
{
"id": "urn:x-wmo:md:int.wmo.wis::https://geo.woudc.org/def/data/ozone/total-column-ozone/totalozone",
"type": "Feature",
"time": {
"interval": [
"1924-08-17T00:00:00Z",
".."
],
"resolution": "P1D"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-180,
-90
],
[
-180,
90
],
[
180,
90
],
[
180,
-90
],
[
-180,
-90
]
]
]
},
"conformsTo": [
"http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core"
],
"properties": {
"created": "2021-02-08T00:00:00Z",
"updated": "2021-02-08T00:00:00Z",
"type": "dataset",
"title": "Total Ozone - daily observations",
"description": "A measurement of the total amount of atmospheric ozone in a given column from the surface to the edge of the atmosphere. Ground based instruments such as spectrophotometers and ozonemeters are used to measure results daily",
"keywords": [
"total",
"ozone",
"level 1.0",
"column",
"dobson",
"brewer",
"saoz"
],
"language": {
"code": "en-CA",
"name": "English (Canada)"
},
"languages": [
{
"code": "en-CA",
"name": "English (Canada)"
},
{
"code": "fr-CA",
"name": "French (Canada)"
}
],
"externalIds": [
{
"scheme": "WMO:WIS",
"value": "urn:x-wmo:md:int.wmo.wis::https://geo.woudc.org/def/data/ozone/total-column-ozone/totalozone"
}
],
"contacts": [
{
"name": "World Ozone and Ultraviolet Radiation Data Centre",
"links": [
{
"href": "https://woudc.org",
"rel": "about",
"type": "text/html"
}
],
"contactInstructions": "SEE PAGE: https://woudc.org/contact.php",
"roles": [
"publisher"
]
}
],
"themes": [
{
"concepts": [
{
"id": "dobson",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_dobson"
},
{
"id": "brewer",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_brewer"
},
{
"id": "vassey",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_vassey"
},
{
"id": "pion",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_pion"
},
{
"id": "microtops",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_microtops"
},
{
"id": "spectral",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_spectral"
},
{
"id": "hoelper",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_hoelper"
},
{
"id": "saoz",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_saoz"
},
{
"id": "filter",
"url": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode_filter"
}
],
"scheme": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode"
},
{
"concepts": [
{
"id": "atmosphericComposition",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_atmosphericComposition"
},
{
"id": "pollution",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_pollution"
},
{
"id": "observationPlatform",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_observationPlatform"
},
{
"id": "rocketSounding",
"url": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode_rocketSounding"
}
],
"scheme": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode"
}
],
"formats": [
{
"name": "TEXT",
"mediaType": "text/plain"
},
{
"name": "CSV",
"mediaType": "text/csv"
},
{
"name": "GML2",
"mediaType": "text/xml; subtype=gml/2.1.2"
},
{
"name": "GML3",
"mediaType": "text/xml; subtype=gml/3.1.1"
},
{
"name": "SHAPEFILE",
"mediaType": "application/vnd.shp"
},
{
"name": "KML",
"mediaType": "application/vnd.google-earth.kml+xml"
},
{
"name": "KMZ",
"mediaType": "application/vnd.google-earth.kmz"
},
{
"name": "GeoJSON",
"mediaType": "application/geo+json"
},
{
"name": "PNG",
"mediaType": "image/png"
},
{
"name": "JPEG",
"mediaType": "image/jpeg"
},
{
"name": "GIF",
"mediaType": "image/gif"
},
{
"name": "PDF",
"mediaType": "application/x-pdf"
},
{
"name": "SVG",
"mediaType": "image/svg+xml"
},
{
"name": "TIFF",
"mediaType": "image/tiff"
}
],
"license": "other"
},
"linkTemplates": [
{
"rel": "describes",
"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={format}",
"variables": {
"bbox": {
"description": "...",
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"minItems": 4,
"maxItems": 4
},
"crs": {
"description": "...",
"type": "string",
"enum": [
"EPSG:4326",
"EPSG:3857"
]
},
"width": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"height": {
"description": "...",
"type": "number",
"format": "integer",
"minimum": 600,
"maximum": 5000
},
"format": {
"type": "string",
"enum": [
"application/vnd.google-earth.kml+xml",
"application/vnd.google-earth.kmz",
"image/png",
"image/jpeg",
"image/gif",
"image/png; mode=8bit",
"application/x-pdf",
"image/svg+xml",
"image/tiff"
]
}
}
},
{
"rel": "describes",
"title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations",
"uriTemplate": "https://geo.woudc.org/ows?service=WFS&version=1.1.0&request=GetFeature&typeName=woudc:totalozone&maxFeatures={maxFeatures}&outputFormat={outputFormat}",
"variables": {
"maxFeatures": {
"type": "number",
"default": 10
},
"outputFormat": {
"type": "string",
"enum": [
"text/xml; subtype=gml/3.1.1",
"text/xml; subtype=gml/2.1.2; driver=ogr",
"application/json; subtype=geojson",
"application/vnd.google-earth.kml+xml",
"application/vnd.shp",
"text/plain",
"text/csv"
],
"default": "text/xml; subtype=gml/2.1.2; driver=ogr"
}
}
}
],
"links": [
{
"rel": "collection",
"href": "https://woudc.org/data/dataset_info.php"
},
{
"rel": "describes",
"title": "OGC Web Map Service (WMS)",
"href": "https://geo.woudc.org/ows?service=WMS&request=GetCapabilities"
},
{
"rel": "describes",
"title": "OGC Web Feature Service (WFS)",
"href": "https://geo.woudc.org/ows?service=WFS&request=GetCapabilities"
},
{
"rel": "preview",
"type": "image/png",
"title": "Total Ozone Preview Image",
"href": "https://woudc.org/data/preview.png"
},
{
"rel": "enclosure",
"type": "text/html",
"title": "Web Accessible Folder (WAF)",
"href": "https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1",
"created": "2015-01-23T00:00:00Z",
"updated": "2015-01-23T00:00:00Z"
},
{
"rel": "enclosure",
"type": "application/zip",
"title": "Static dataset archive file",
"href": "https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip",
"created": "2015-01-23T00:00:00Z",
"updated": "2015-01-23T00:00:00Z"
},
{
"rel": "search",
"type": "text/html",
"title": "Data Search / Download User Interface",
"href": "https://woudc.org/data/explore.php?dataset=totalozone"
},
{
"rel": "license",
"href": "https://woudc.org/about/data-policy.php"
}
]
}
Listing 22 — Record Example in GeoJSON
7.5.6. Record access
7.5.6.1. Operation
Identifier | /req/records-api/record-op |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | For every record in a catalog the server SHALL support the HTTP GET operation at the /collection/{collectionId}/items/{recordId} path. |
B | The parameter collectionId is each id property in the collections response (JSONPath: $.collections[*].id) where the value of the itemType (JSONPath $.collections[*].itemType) is record. id is a local identifier of the record. |
7.5.6.2. Response
Identifier | /req/records-api/record-response |
---|---|
Included in | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
A | The body of the response SHALL contain a record based on the following schema:
--- |
B | The links section of the record SHALL contain the following links:
|
C | All links SHALL include the rel parameter. |
NOTE: The term “typed link” means a link that specifies a value for the type attribute.
7.6. Requirements Class “Sorting” (Common Component)
7.6.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
---|---|
Target type | Document model |
Conformance class | Conformance class A.7: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting |
Normative statements | Requirement 43: /req/sorting/sortby-param Requirement 44: /req/sorting/sortby-response Requirement 45: /req/sorting/get-sortables-op Requirement 46: /req/sorting/get-sortables-success Requirement 47: /req/sorting/defaultSortOrder-definition |
The Sorting Requirements Class defines the requirements for specifying how records in a response should be ordered for presentation.
7.6.2. Parameter sortby
Identifier | /req/sorting/sortby-param |
---|---|
Included in | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
A | At the searchable catalog endpoint, the operation SHALL support a parameter sortby with the following characteristics (using an OpenAPI Specification 3.0 fragment):
name: sortby |
B | The default sort order SHALL be ascending (i.e., +). |
NOTE 1: The core definition of the sortby parameter only defines a single directive that controls the sort order of the corresponding property. It is anticipated extensions would add additional search facets such as directives for:
Handling missing values,
Specifying a high value indicating that the corresponding property be sorted as if it were the highest possible value,
Specifying a low value indicating that the corresponding property be sorted as if it were the lowest possible value,
Allowing records to be omitted from the result set based on their sort order,
Specify a fixed value and a fixed value that sorts the corresponding property as if it were the specified fixed value.
Identifier | /req/sorting/sortby-response |
---|---|
Included in | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
A | If the sortby parameter is specified, then the records in a response SHALL be ordered by the keys and sort directions (i.e., ascending or descending) specified. |
B | The specific set of keys that may be used for sorting SHALL be specified by the /collections/{collectionId}/sortables resource. |
Identifier | /req/sorting/get-sortables-op |
---|---|
Included in | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
A | For every catalog, the server SHALL support the HTTP GET operation at the sortables endpoint and the media type application/schema+json. |
B | The sortables resource SHALL be referenced from the catalog with a link with the link relation type http://www.opengis.net/def/rel/ogc/1.0/sortables. |
Identifier | /req/sorting/get-sortables-success |
---|---|
Included in | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
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:
|
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. In other words, 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. |
The response is returned as a JSON Schema document that describes a single JSON object where each property is a sortable. Note that the sortables schema does not specify a schema of any object that can be retrieved from a Records API endpoint. JSON Schema is used for the sortables to have a consistent approach for describing schema information and JSON Schema is/will be used in other parts of OGC API — Features suite of standards to describe schemas for GeoJSON feature content including in OpenAPI documents.
NOTE 2: The OGC Features API Standards Working Group has a schema harmonization task that could lead to a future OGC API Standard that will deprecate the approach for the sortables resource specified in this document.
To support clients, providing additional detail about the meaning of the sortables is recommended:
Identifier | /rec/sorting/sortables-schema |
---|---|
A | Each property SHOULD have a human readable title (title) and where necessary a description (description). |
B | Each property SHOULD have a single type (type). |
In an OpenAPI 3.0 document, the Sortables resource has the following schema:
---
description:
A list of properties by which the server response may be sorted.
content:
application/json:
schema:
type: object
description:
A JSON Schema document that defines all the sortables.
text/html:
schema:
type: string
Listing 25 — Schema for the list of sortable properties (Sortables.yaml)
7.6.3. Declaring default sort order
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.
Identifier | /req/sorting/defaultSortOrder-definition |
---|---|
Included in | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
A | The information model of a catalog SHALL include the defaultSortOrder member with the following characteristics (using an OpenAPI Specification 3.0 fragment):
--- |
B | Each object in the array SHALL include the properties field containing the name of the sortable and direction indicating the direction of sorting |
C | If the value of the direction property is asc this SHALL indicate that the sort order is ascending. |
D | If the value of the direction property is desc this SHALL indicate that the sort order is descending. |
E | If the defaultSortOrder member is not present in the response, then no sorting information SHALL be assumed. |
7.6.4. Sorting by relevance (informative)
A common practice is to sort search results by relevance.
This capability is accomodated in this Standard by using synthetic sortables. That is, using a sortable that is derived or synthesized by the server.
A server implementing relevance ranking might include, in its list of sortables, a sortable named relevance that is dynamically computed for each result in a result set. How exactly the value of the relevance score is computed is left to the server’s discretion. The value of the synthetic relevance sortable could, for example, be between 0 and 10 with zero indicating least relevance and 10 indicating most relevance. A sortBy clause specified on a request specifying a descending sort by the relevance property would present search results from most to least relevant.
7.6.5. Examples
{
.
.
.
"defaultSortOrder": [
{
"field": "updated",
"direction": "desc"
},
{
"field": "area",
"direction": "desc"
}
],
.
.
.
}
Listing 27 — Default Sort Order Example
The following examples assume the following set of sortables retrieved from the servers /collection/{catalogId}/sortables endpoint:
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "https://data.example.com/collections/abc/sortables",
"type": "object",
"properties": {
"id": {
"title": "Record Identifier",
"description": "A unique record identifier assigned by the server.",
"type": "string"
},
"updated": {
"title": "Updated",
"description": "The more recent date on which the resource was changed.",
"type": "string",
"format": "date"
},
"area": {
"title": "Spatial area of the resource",
"description": "This is a synthetic sortable that the server computes on the fly based on the spatial extent of the resource. Resources without spatial extent have zero area.",
"type": "number"
},
"relevance": {
"title": "Relevance of the result",
"description": "This is a synthetic sortable that the server computes on the fly to assign a relevance score to each result with respect to the query parameters specified in the original request. How exactly the relevance score is computed is up to the discretion of the server.",
"type": "number",
"minimum": 0,
"maximum": 10
},
"extent": {
"title": "Spatio-Temporal Extent",
"description": "The spatio-temporal coverage of the resource.",
"type": "object"
}
}
}
Listing 28 — List of sortables
.../collections/mycat/items?...&sortby=%2Dupdated,%2Bid&...
Listing 29 — sortby Example of descending sort by updated date and ascending sort of record identifier.
.../collections/mycat/items?...&sortby=%2Bextent&...
Listing 30 — sortby Example of an ascending sort by extent (i.e., smallest area first)
.../collections/mycat/items?...&sortby=%2Drelevance&...
Listing 31 — sortby Example of a descending sort by relevance (i.e., most relevant first)
7.7. Requirements Class “Filtering” (Common Component)
7.7.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |
---|---|
Target type | Web API |
Prerequisite | OGC API — Features — Part 3: Filtering and the Common Query Language (CQL) |
Normative statements | Requirement 48: /req/features-filter/filter-param Requirement 49: /req/record-filter/filter-lang-param Requirement 50: /req/record-filter/filter-crs-param Requirement 51: /req/record-filter/response |
This clause defines the binding to the filtering parameters defined in the OGC API — Features — Part 3: Filtering and the use of the Common Query Language (CQL2) as the query language.
7.7.2. Records filtering
7.7.2.1. Operation
As specified in the Records Access clause, records are accessed using the HTTP GET method via the /collections/{collectionId}/items path. The following additional requirements bind the parameters filter, filter-lang and filter-crs to the GET operation on this path.
Identifier | /req/features-filter/filter-param |
---|---|
Included in | Requirements class 6: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |
A | The HTTP GET operation SHALL support the filter parameter as defined in Parameter filter. |
B | For searchable catalogs, the path for which this parameter is supported SHALL be /collections/{collectionId}/items. |
C | For local resources catalogs, the path for which this parameter is supported SHALL be whichever path is being extended for catalog-like search capabilities (e.g., /collections). |
Identifier | /req/record-filter/filter-lang-param |
---|---|
Included in | Requirements class 6: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |
A | The HTTP GET operation SHALL support the filter-lang parameter as defined in Parameter filter-lang. |
B | For searchable catalogs, the path for which this parameter is supported SHALL be /collections/{collectionId}/items. |
C | For local resources catalogs, the path for which this parameter is supported SHALL be whichever path is being extended for catalog-like search capabilities (e.g., /collections). |
Identifier | /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 CQL text encoding. |
Identifier | /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 CQL JSON encoding. |
Identifier | /req/record-filter/filter-crs-param |
---|---|
Included in | Requirements class 6: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |
Condition | Server implements OGC API — Features — Part 2: Coordinate Reference Systems by Reference |
A | The HTTP GET operation SHALL support the filter-crs parameter as defined in Parameter filter-crs. |
B | For searchable catalogs, the path for which this parameter is supported SHALL be /collections/{collectionId}/items. |
C | For local resources catalogs, the path for which this parameter is supported SHALL be whichever path is being extended for catalog-like search capabilities (e.g., /collections). |
7.7.2.2. Response
Identifier | /req/record-filter/response |
---|---|
Included in | Requirements class 6: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |
A | A filter expression SHALL be evaluated for each record of a collection. |
B | All other filtering parameters specified (i.e., zero or more of bbox, datetime, q, type, externalIds and any additional query parameters) SHALL be evaluated for each record of a collection. |
C | If the filter expression AND all other specified filtering parameters (i.e., zero or more of bbox, datetime, q, type, externalIds and any additional query parameters) evaluate to TRUE then the record SHALL be included in the result set. |
D | If the filter expression OR any other specified filtering parameter (i.e., zero or more of bbox, datetime, q, type, externalIds and any additional query parameters) evaluates to FALSE then the record SHALL be excluded from the result set. |
7.7.3. Filtering on links
7.7.3.1. Overview
Links can be added to a catalog record in various ways. This clause describes the various linking patterns and describes how to use CQL to filter based on links.
7.7.3.2. Linking patterns in records
Links can be added to the following sections in a catalog record:
the links section,
the linkTemplates section,
the properties section.
The schema for links added to the links and linkTemplates sections is based on RFC 8288 and is described in the OGC API — Features — Part 1: Core Standard.
Links added directly to the properties section of a catalog record can be added using the following patterns:
The link relation is the key for an array of links with a schema similar to that used in the links section but omitting the rel key.
The link relation is the key for an array of href values.
The link relation is the key for an an href value.
The following examples illustrate each of these linking patterns:
{
...,
"properties": {
...,
"links":
[
...,
{
"rel" : "alternate",
"title" : "This records as XML.",
"href" : "https://example.org/collections/mycat/items/rec01.xml"
},
{
"rel": "next",
"title": "The next record in this result set.",
"href" : "https://example.org/collections/mycat/items/rec02"
},
...
],
...
}
}
Listing 32 — Adding links to the links section
{
...,
"properties": {
...,
"related": [
{
"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:/example.org/collections/MyCollection/items?f=application/geopackage+vnd.sqlite3&bbox={bbox}",
"varBase": "https://example.org/variables/"
},
...
}
}
Listing 33 — Adding links to the properties section
{
...,
"properties": {
...,
"related": ["https://example.org/related-record-path/rec15"],
"license": "https://creativecommons.org/licenses/by/2.0/",
...
}
}
Listing 34 — Adding links to the properties section
7.7.3.3. Examples
7.7.3.3.1. CQL filters on links
The following example illustrates how to filter links that may appear in a catalog record.
links[rel='license'].title LIKE 'CC%'
Listing 35 — Filtering links in the links section
properties.related[*].href LIKE '%/rec15' AND properties.license.title LIKE 'CC%'
Listing 36 — Filtering links in the properties section
properties.related LIKE '%/rec15' AND properties.license LIKE 'https://creativecommons.org/licenses/%'
Listing 37 — Filtering links in the properties section
7.7.3.3.2. Filtering by keyword from a controlled vocabulary
The following example illustrates how to use OGC API — Feature — Part 3: Filtering and CQL2 to query by keywords from a specific controlled vocabulary.
The use of keywords from a controlled vocabulary is encoded in a record using the themes property. Consider a record that has the following themes property:
"themes": [
{
"concepts": [
"dobson",
"brewer",
"vassey",
"pion",
"microtops",
"spectral",
"hoelper",
"saoz",
"filter"
],
"scheme": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode"
},
{
"concepts": [
"atmosphericComposition",
"pollution",
"observationPlatform",
"rocketSounding"
],
"scheme": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode"
}
],
Listing 38
Using an implementation of the OGC API — Feature — Part 3: Filtering Standard, a server would need to expose two 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://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
Listing 39
An alternative approach that does rely on using OGC API — Feature — Part 3: Filtering and CQL2 would rely on the server defining a set of query parameters in the server’s API description document, again named scheme and concept, that would allow the following filter to be expressed:
https://example.org/collections/myCatalog/items?scheme=https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode&concept=spectral,hoelper
Listing 40
7.8. Requirements Class “Autodiscovery” (Common Component)
7.8.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/autodiscovery |
---|---|
Target type | Web API |
Conformance class | Conformance class A.11: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/autodiscovery |
Prerequisite | Record Collection |
Normative statement | Requirement 52: /req/autodiscovery/links |
The purpose of autodiscovery is, knowing the location of a web page, to find the addresses(s) of that page’s associated catalog(s). For example, a client could retrieve the landing page of an OGC API deployment, find the location of the site’s searchable catalog by locating the link relation type that has the value http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog in the landing page and then, using that catalog, search for resources offered by the site.
7.8.2. Autodiscovery links
Identifier | /req/autodiscovery/links |
---|---|
Included in | Requirements class 7: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/autodiscovery |
A | A web page SHALL include one or more links (relation: http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog) that point to a crawlable catalog, searchable catalogs or local resource catalog associated with the page. |
B | The value of the href member SHALL point to the access endpoint of the corresponding catalog. |
NOTE:
For a crawlable catalog the access endpoint is the URL of the catalog.
For a searchable catalog the access endpoint is the URL of the /collections/{catalogId}/items endpoint.
For a local resource catalog the access endpoint is the URL of the local resources endpoint (e.g., /processes).
7.9. Encodings
7.9.1. Overview
This Standard defines two requirements classes, HTML and JSON for encoding resources defined in this Standard.
HTML is the core language of the World Wide Web. An API that supports HTML supports browsing resources with a web browser and also enables search engines to crawl and index those resources.
JSON is a language-independent file format that uses human-readable text to store and transmit data objects consisting of key-value pairs and arrays. It is a commonly used data format in machine-to-machine communication including that between web applications and servers. It is well supported by numerous tools and software libraries.
“GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON). It defines several types of JSON objects and the way they are combined to represent data about geographic features, their properties, and their spatial extents. GeoJSON uses a geographic coordinate reference system, World Geodetic System 1984, and units of decimal degrees.” IETF RFC 7946
GeoJSON provides a simple way of representing records in JSON and is supported by numerous geospatial tools and software libraries. It is best used for content which has a spatial extent that can be used with the World Geodetic System 1984 Coordinate Reference System.
7.9.2. Requirements Class JSON (Common Component)
7.9.2.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
---|---|
Target type | Document encoding |
Conformance class | Conformance class A.9: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json |
Prerequisites | IETF RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format JSON Schema GeoJSON |
Normative statements | Requirement 58: /req/json/catalog-content Requirement 57: /req/json/collection-response Requirement 53: /req/json/conformance Requirement 55: /req/json/record-content Requirement 54: /req/json/record-response |
Identifier | /req/json/conformance |
---|---|
Included in | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
A | The conformsTo array SHALL contain the value http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json. |
NOTE: The location of the conformsTo array depends on the type of catalog being deployed. In the case of the searchable or local resources catalog, the conformsTo array can be found in the conformance page (path: /conformance) of the OGC API deployment or in the catalog. In the case of a crawlable catalog, the conformsTo array is found in the catalog.
7.9.2.2. Record encoding
GeoJSON is a commonly used format based 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. The caveat is, if record data can be represented in GeoJSON for the intended use.
The following requirements apply when:
The Records API endpoint advertises conformance to the JSON Conformance Class; and
The client negotiates that the content of the server’s response be GeoJSON.
Identifier | /req/json/record-response |
---|---|
Included in | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
A | 200-responses of the server SHALL support the following media type:
|
B | The geometry member SHALL be present and SHALL store a geometry, for the purpose of discovery, of the resource being described by the record. This can be the actual geometry of the resource or some other representation of the space that the resource occupies. |
C | The extent member SHALL include the bounding extent of the resource being described by the record. If the server chooses to use the bounding box of the resource as the geometry of the resource, then the geometry and extent values may be the same. |
Identifier | /req/json/record-content |
---|---|
Included in | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
A | Every 200-response with the media type application/geo+json SHALL be
|
B | The schema of records in all responses with the media type application/geo+json SHALL validate against the OpenAPI 3.0 schema document recordGeoJSON.yaml. |
C | The links specified in the requirements /req/core/rc-links and /req/core/record-links SHALL be added in an extension property (foreign member) with the name links. |
D | The response SHALL include, in the links section, a profile link (href: http://www.opengis.net/def/profile/OGC/0/ogc-catalog, relation: profile). |
Identifier | /req/json/record-content-profile |
---|---|
Condition | The negotiated profile is http://www.opengis.net/def/profile/OGC/0/ogc-record. |
A | Every 200-response with the media type application/geo+json SHALL be
|
B | The schema of records in all responses SHALL validate against the OpenAPI 3.0 schema document recordGeoJSON.yaml. |
C | The links specified in the requirements /req/core/rc-links and /req/core/record-links SHALL be added in an extension property (foreign member) with the name links. |
D | The response SHALL include, in the links section, a profile link (href: http://www.opengis.net/def/profile/OGC/0/ogc-catalog, relation: profile). |
NOTE 1: It should be noted that the recordGeoJSON.yaml schema makes the geometry member mandatory because the GeoJSON RFC requires that the geometry member be present. If a resource described by a JSON-encoded record does not have any spatial characteristics, the values of the geometry member can be null as per the GeoJSON RFC.
Identifier | /rec/json/header-profile-link |
---|---|
A | A server SHOULD include a profile link (href: http://www.opengis.net/def/profile/OGC/0/ogc-catalog, relation: profile) in the response HTTP headers (see RFC 6906, The ‘profile’ Link Relation Type). |
---
type: object
required:
- id
- type
- geometry
- properties
properties:
id:
type:
- string
- integer
description:
A unique identifier of the catalog record.
type:
type: string
const: Feature
time:
oneOf:
- type: null
- $ref: 'time.yaml'
geometry:
oneOf:
- type: null
- $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml'
conformsTo:
type: array
description:
The extensions/conformance classes used in this record.
items:
type: string
properties:
oneOf:
- type: null
- allOf:
- type: object
- $ref: 'recordCommonProperties.yaml'
links:
type: array
items:
$ref: 'link.yaml'
linkTemplates:
type: array
items:
$ref: 'linkTemplate.yaml'
Listing 41 — Schema for a catalog record encoded as GeoJSON (recordGeoJSON.yaml)
---
type: object
properties:
created:
type: string
description:
The date this record was created in the server.
format: date-time
updated:
type: string
description:
The most recent date on which the record was changed.
format: date-time
type:
type: string
description:
The nature or genre of the resource. The value
should be a code, convenient for filtering
records. Where available, a link to the canonical
URI of the record type resource will be added to
the 'links' property.
title:
type: string
description:
A human-readable name given to the resource.
description:
type: string
description:
A free-text account of the resource.
keywords:
type: array
description:
The topic or topics of the resource. Typically
represented using free-form keywords, tags, key
phrases, or classification codes.
items:
type: string
themes:
type: array
description:
A knowledge organization system used to classify
the resource.
minItems: 1
items:
$ref: 'theme.yaml'
language:
description:
The language used for textual values in this
record representation.
$ref: 'language.yaml'
languages:
type: array
description:
This list of languages in which this record is
available.
items:
$ref: 'language.yaml'
resourceLanguages:
type: array
description:
The list of languages in which the resource
described by this record is available.
items:
$ref: 'language.yaml'
externalIds:
type: array
description:
An identifier for the resource assigned by an
external (to the catalog) entity.
items:
type: object
properties:
scheme:
type: string
description:
A reference to an authority or identifier
for a knowledge organization system from
which the external identifier was obtained.
It is recommended that the identifier be a
resolvable URI.
value:
type: string
description: The value of the identifier.
required:
- value
formats:
type: array
description:
A list of available distributions of the resource.
items:
$ref: 'format.yaml'
contacts:
type: array
description:
A list of contacts qualified by their role(s) in
association to the record or the resource described
by the record.
items:
$ref: 'contact.yaml'
license:
$ref: 'license.yaml'
rights:
type: string
description:
A statement that concerns all rights not addressed
by the license such as a copyright statement.
Listing 42 — Common record properties schema (recordCommonProperties.yaml)
NOTE 2: Referenced schemas can be found at:
NOTE 3: This standard does not define a normative schema for a record encoding that is not GeoJSON. However, this informative schema is offered as an example of what a plain JSON record schema might look like.
7.9.2.3. Catalog encoding
JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays (or other serializable values). JSON is a commonly used data encoding with diverse uses in electronic data interchange, including that of web applications with servers. Therefore, the recommendation is to use the JSON encoding if the catalog (i.e., a collection of record) data can be represented in JSON for the intended use.
The following requirements apply when:
The Records API endpoint advertises conformance to the JSON Conformance Class; and
The client negotiates that the content of the server’s response be JSON.
Identifier | /req/json/collection-response |
---|---|
Included in | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
A | 200-responses of the server SHALL support the following media type:
|
Identifier | /req/json/catalog-content |
---|---|
Included in | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
A | The schema of all responses with the media type application/ogc-catalog+json SHALL validate against the OpenAPI 3.0 schema document catalog.yaml. |
Identifier | /req/json/catalog-content-profile |
---|---|
Condition | The negotiated profile is http://www.opengis.net/def/profile/OGC/0/ogc-catalog. |
A | The schema of all responses with the media type application/json SHALL validate against the OpenAPI 3.0 schema document catalog.yaml. |
B | The response SHALL include, in the links section, a profile link (href: http://www.opengis.net/def/profile/OGC/0/ogc-catalog, relation: profile). |
See also recommendation: /rec/json/header-profile-link.
---
allOf:
- $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml'
- $ref: 'catalogCommonProperties.yaml'
- type: object
properties:
itemType:
description:
If this catalog is a homogenous collection
of records then itemType is a string of fixed
value of record.
If this catalog is a homogenous collection
of other catalogs then itemType is a string of
fixed value of catalog.
If this catalog is a heterogenous collection
of records and catalogs then itemType is a array
indicated that item types of the members of this
collections (i.e. record and/or catalog).
oneOf:
- type: string
enum:
- record
- catalog
- type: array
items:
type: string
enum:
- record
- catalog
Listing 43 — Schema for a catalog encoded as JSON(catalog.yaml)
NOTE: Referenced schemas can be found at:
7.9.3. Requirements Class HTML (Common Component)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html |
---|---|
Target type | Document encoding |
Conformance class | Conformance class A.8: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html |
Prerequisite | http://www.w3.org/TR/html5/ |
Normative statements | Requirement 60: /req/html/conformance Requirement 61: /req/html/definition Requirement 62: /req/html/content |
Identifier | /req/html/conformance |
---|---|
Included in | Requirements class 9: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html |
A | The conformsTo array SHALL contain the value http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html. |
NOTE: The location of the conformsTo array depends on the type of catalog being deployed. In the case of the searchable or local resources catalog, the conformsTo array can be found in the conformance page (path: /conformance) of the OGC API deployment or in the catalog. In the case of a crawlable catalog, the conformsTo array is found in the catalog.
Catalog information that is only accessible in formats primarily intended to 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, the Web search engines; and
the data cannot be viewed directly in a browser (additional tools are required to view the data).
Therefore, sharing catalog 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.
This is discussed in detail in Best Practice 2: Make your spatial data indexable by search engines SDWBP. The Records API Standard therefore recommends supporting HTML as an encoding.
Identifier | /req/html/definition |
---|---|
Included in | Requirements class 9: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html |
A | Every 200 response of an operation of the server SHALL support the media type text/html. |
Identifier | /req/html/content |
---|---|
Included in | Requirements class 9: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html |
A | Every 200 response of the server with the media type text/html SHALL be a HTML 5 document that includes the following information in the HTML body:
|
Identifier | /rec/html/schema-org |
---|---|
A | A 200 response with the media type text/html, SHOULD include Schema.org annotations. |
7.10. Requirements Class “OpenAPI 3.0” (Common Component)
7.10.1. Basic requirements
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/oas30 |
---|---|
Target type | Web API |
Conformance class | Conformance class A.10: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30 |
Prerequisite | OpenAPI Specification 3.0 |
Normative statements | Requirement 63: /req/oas30/oas-common Requirement 64: /req/oas30/conformance |
Servers conforming to this requirements class define their API using an OpenAPI Document.
Identifier | /req/oas30/oas-common |
---|---|
Included in | Requirements class 10: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/oas30 |
A | The API implementation SHALL demonstrate conformance to the OpenAPI 3.0 requirements class of the OGC API — Feature — Part 1: Core Standard. |
Identifier | /req/oas30/conformance |
---|---|
Included in | Requirements class 10: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/oas30 |
A | The conformsTo array found in the conformance path (path: /conformance) SHALL contain the value http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30. |
8. Catalog deployments
8.1. Overview
This clause uses the common components defined in this Standard to define various catalog deployments.
8.2. Requirements Class “Crawlable Catalog” (Deployment)
8.2.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
---|---|
Target type | Web API |
Conformance class | Conformance class A.12: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog |
Prerequisites | Record Core Record Collection |
Normative statements | Requirement 65: /req/crawlable-catalog/record Requirement 66: /req/crawlable-catalog/record-location Requirement 67: /req/crawlable-catalog/catalog Requirement 68: /req/crawlable-catalog/location Requirement 69: /req/crawlable-catalog/conformance |
The Crawlable Catalog Requirements Class defines the requirements for a catalog composed of static, web-accessible files.
The goal of a crawlable catalog is to expose metadata about resources online with as low an entry barrier as possible, thus making those resources more easily discoverable.
A crawlable catalog is a deployment pattern that uses the collection and record common components defined in this Standard. It is simply a set of files deployed on the web, usually encoded as HTML or JSON, that conform to the collection and record schemas 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 searchable catalog can also behave as a crawlable catalog as long as the requirements in this clause are satisfied by the searchable catalog implementation.
8.2.2. Making a resource discoverable
Identifier | /req/crawlable-catalog/record |
---|---|
Included in | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
A | A record SHALL be created for each resource to be made discoverable. |
Attention is drawn to requirement /per/record-core/additional-properties-record that allows the information content of the record to be enriched as required to describe the resource being made discoverable.
Identifier | /req/crawlable-catalog/record-location |
---|---|
Included in | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
A | The record file SHALL be placed in a web-accessible location. |
NOTE: This Standard is primarily concerned with making resources discoverable on the open Web that sits on top of the public Internet. However, the same requirement applies in more restricted contexts such as a company Intranet or within classified networks. In other words, the record should be placed in a location that is accessible to the intended audience.
Identifier | /rec/crawlable-catalog/record-file-name |
---|---|
A | The name of the record file SHOULD be {id}.json where {id} is the identifier of the record. |
Identifier | /rec/crawlable-catalog/record-file-location |
---|---|
A | The record file SHOULD be located close to the resource(s) that the record describes. |
For example, the record file could be placed in the same web-accessible directory or object store as the resource(s) that the record describes.
8.2.3. Grouping a collection of records into a catalog
Identifier | /req/crawlable-catalog/catalog |
---|---|
Included in | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
A | A collection of related records, called a catalog, SHALL be described by a Record Collection object. |
Identifier | /req/crawlable-catalog/location |
---|---|
Included in | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
A | The catalog SHALL be placed in a web-accessible location. |
NOTE: This Standard is primarily concerned with making resources discoverable on the open Web that sits on top of the public Internet. However, the same requirement applies in more restricted contexts such as a company Intranet or within classified networks. In other words, the catalog should be placed in a location that is accessible to the intended audience.
Identifier | /req/crawlable-catalog/conformance |
---|---|
Included in | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
A | The conformsTo array found in the catalog SHALL contain the value http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog. |
8.2.4. Organizing crawlable catalogs
In order to provide flexibility with regard to how crawlable catalogs can be organized (e.g., series, hierarchy, etc.) a catalog can also provide information about and access to related catalogs. As such, the Record Collection object can be used as a common entry point for crawling to multiple related catalogs, sub-catalogs, records and other resources.
The relationships among catalogs and records are expressed as links in the links section of the catalog and the links section of the record.
See “Other catalogs” and Records.
8.3. Requirements Class “Searchable Catalog” (Deployment)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
---|---|
Target type | Web API |
Conformance class | Conformance class A.17: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog |
Prerequisite | Records API |
Normative statements | Requirement 70: /req/searchable-catalog/common Requirement 71: /req/searchable-catalog/conformance Requirement 72: /req/searchable-catalog/mandatory-catalog-properties Requirement 73: /req/searchable-catalog/mandatory-record-properties |
8.3.1. Overview
The Searchable Catalog Requirements Class defines the requirements for a catalog that is searchable through an API. A searchable catalog is an implementation of the OGC API — Features — Part 1: Core Standard that uses a defined information model. In the case of the OGC API — Records Standard, that information model is the Record.
Identifier | /req/searchable-catalog/common |
---|---|
Included in | Requirements class 12: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
Statement | Implementations of this requirements class SHALL implement the following common components: |
A | |
B | |
C | |
D |
Identifier | /req/searchable-catalog/conformance |
---|---|
Included in | Requirements class 12: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of a searchable catalog SHALL declare the following conformance classes in the conformance declaration: |
C | A server that supports JSON responses SHALL declare the following conformance classes in the conformance declaration: |
D | A server that supports HTML responses SHALL declare the following conformance classes in the conformance declaration: |
E | A server that supports a server description document using OpenAPI 3.0 SHALL declare the following conformance classes in the conformance declaration: |
F | A server that supports autodiscovery SHALL declare the following conformance classes in the conformance declaration: |
Identifier | /req/searchable-catalog/mandatory-catalog-properties |
---|---|
Included in | Requirements class 12: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
A | The information model describing a searchable catalog SHALL contain all the mandatory properties listed in Table 11. |
Identifier | /req/searchable-catalog/mandatory-record-properties |
---|---|
Included in | Requirements class 12: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
A | Each record accessibles via a searchable catalog SHALL include all the mandatory properties listed in Table 8 and Table 9. |
8.3.2. Requirements Class “Searchable Catalog — Filtering” (Deployment)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering |
---|---|
Target type | Web API |
Conformance class | Conformance class A.18: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog/filtering |
Prerequisites | Searchable Catalog Filtering |
Normative statements | Requirement 74: /req/searchable-catalog/filtering Requirement 75: /req/searchable-catalog/filtering-conformance Requirement 76: /req/searchable-catalog/mandatory-queryables |
This requirements class specifies requirements and recommendations for supporting advanced filtering at searchable catalog endpoints. Advanced filter expressions can only reference properties from an advertised set of queryables.
Identifier | /req/searchable-catalog/filtering |
---|---|
Included in | Requirements class 13: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering |
Statement | Implementations that offer enhanced filtering SHALL implement the following requirements class at the searchable catalog enpoint of /collections/{collectionId}/items where the itemType property of the collection with id {collectionId} (JSONPath: $.collections[*].itemType) is a string with the value record. |
A |
Identifier | /req/searchable-catalog/filtering-conformance |
---|---|
Included in | Requirements class 13: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of this requirements class SHALL declare the following conformance classes in the conformance declaration: |
Identifier | /req/searchable-catalog/mandatory-queryables |
---|---|
Included in | Requirements class 13: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering |
A | The list of queryables SHALL include all the mandatory properties listed in Table 8 and Table 9. |
8.3.3. Requirements Class “Searchable Catalog — Sorting” (Deployment)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/sorting |
---|---|
Target type | Web API |
Conformance class | Conformance class A.19: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog/sorting |
Prerequisites | Searchable Catalog Sorting |
Normative statements | Requirement 77: /req/searchable-catalog/sorting Requirement 78: /req/searchable-catalog/sorting-conformance |
The Searchable Catalog — Sorting requirements class specifies requirements for supporting sorting of responses at searchable catalog endpoints.
Identifier | /req/searchable-catalog/sorting |
---|---|
Included in | Requirements class 14: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/sorting |
Statement | Implementations of sorting of record responses SHALL implement the following requirements class at the searchable catalog endpoint of /collections/{collectionId}/items where the itemType property of the collection with id {collectionId} (JSONPath: $.collections[*].itemType) is a string with the value record. |
A |
Identifier | /req/searchable-catalog/sorting-conformance |
---|---|
Included in | Requirements class 14: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/sorting |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of this requirements class SHALL declare the following conformance classes in the conformance declaration: |
8.4. Requirements Class “Local Resources Catalog” (Deployment)
8.4.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
---|---|
Target type | Web API |
Conformance class | Conformance class A.13: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog |
Prerequisites | Record Core Record Collection http://www.opengis.net/spec/ogcapi-records-1/1.0/req/autodiscovery |
Normative statements | Requirement 79: /req/local-resources-catalog/common Requirement 80: /req/local-resources-catalog/conformance Requirement 81: /req/local-resources-catalog/mandatory-catalog-properties Requirement 82: /req/local-resources-catalog/mandatory-record-properties Requirement 83: /req/local-resources-catalog/discovery |
The set of OGC API Standards define a number of resource endpoints from which summary information about resources accessible via the server’s API can be retrieved. These endpoints are referred to as local resources catalogs in this Standard because they provide metadata about resources offered locally by a deployment of some or all of the set of OGC API Standards.
NOTE:
local_resources_endpoint
Refers to the path from which a catalog of local resources can be retrieved.local_resources_catalog
Refers to an instance of the resource that can be retrieved from the local resources endpoint (i.e., the catalog).local_resources_item
Each local resources catalog includes an array member. The items of that array are objects (i.e., records) that contain summary metadata about resources retrievable via the server’s API. These objects are referred to as local resources items.
The /collections endpoint is an example of a local resources endpoint. Doing a GET operation at the local resources endpoint (i.e., GET /collections) returns a document that is an example of a local resources catalog. This document contains an array member named collections and the items of that array are the local resources items. Each of these local resources items provides metadata about some resource (e.g., a feature collection) that is accessible via the server’s API.
Other local resources endpoints available in the OGC API resource tree include the /processes endpoint which provides summary metadata about processes and the /collections/{collectionId}/scenes endpoint which provides metadata about the source images of a coverage.
In order to enable catalog-like searching at these local resources endpoints, this requirements class:
extends the information content of the local resources catalog to satisfy the requirements of the Record Collection common component;
extends the information content of the local resources i.e., to satisfy the requirements of the Record Core common component; and
optionally extends the local resources endpoint with a set of query parameters that support a basic capability.
The Local Resources Catalog requirements class does not define the specific endpoints in the OGC API resource tree that should be enabled with catalog-like query capabilities. It only defines how those endpoints should be enhanced should the requirement for catalog-like searching be identified by the responsible OGC Standard. It is anticipated that the responsible OGC standard will define a requirements class or extension to enable local resources catalog capabilities at that endpoint.
8.4.2. Common components
Identifier | /req/local-resources-catalog/common |
---|---|
Included in | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
Statement | Implementations of this requirements class SHALL implement the following common components: |
A | |
B | |
C |
8.4.3. Declaring conformance
Identifier | /req/local-resources-catalog/conformance |
---|---|
Included in | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of a local resources catalog SHALL declare the following conformance classes in the conformance declaration: |
C | A server that supports JSON responses SHALL declare the following conformance classes in the conformance declaration: |
D | A server that supports HTML responses SHALL declare the following conformance classes in the conformance declaration: |
8.4.4. Extending the local resources catalog
As an example of a local resources endpoint, consider the /collections endpoint. The resource, called collections, that can be retrieved from this endpoint is defined in OGC API — Features. The following table cross-walks the information content of the collections object with the catalog.
Table 14 — Crosswalk of collections object and catalog
Collections property | Requirement | Catalog property | Requirement |
---|---|---|---|
— | — | id | required |
— | — | title | optional |
— | — | description | optional |
— | — | links | optional |
— | — | extent | optional |
— | — | itemType | optional |
— | — | crs | optional |
— | — | created | optional |
— | — | updated | optional |
— | — | type | required |
— | — | keywords | optional |
— | — | themes | optional |
— | — | language | optional |
— | — | languages | optional |
— | — | resourceLanguages | optional |
— | — | externalIds | optional |
— | — | formats | optional |
— | — | contacts | optional |
— | — | license | optional |
— | — | rights | optional |
— | — | conformsTo | optional |
— | — | recordsArrayName | optional |
collections | required | records | optional |
links | required | links | required |
linkTemplates | optional | linkTemplates | optional |
The information content of the collections object, a local resources catalog, is sparse and so the following requirements and recommendations are made:
Identifier | /req/local-resources-catalog/mandatory-catalog-properties |
---|---|
Included in | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
A | The information model of the local resources catalog SHALL contain all the mandatory properties listed in Table 11. |
Table 15 — Additional properties for a local resources object
Property | Description |
---|---|
conformsTo | The extensions/conformance classes used in this local resources object. |
created | Date of creation of this local resources object. |
updated | The most recent date on which this local resources object was changed. |
type | The nature or genre of the resource described by this local resources object. |
title | A human readable name assigned to the resource described by this local resources object. |
description | A free-text account about the resource described by this local resources object. |
keywords | The topic or topics associated with the resource described by this local resources object. Typically represented using free-form keywords, tags, key phrases, or classification codes. |
themes | A knowledge organization system used to classify the resource described by this local resources object. |
language | The language used for textual values for this local resources object. |
languages | This list of other languages in which this local resources object can be retrieved. |
resourceLanguages | The list of languages in which the resource described by this local resources object is available. |
formats | A list of available distributions of the resource described by this local resources object. |
contacts | A list of contacts qualified by their role(s). |
license | A legal document under which the resource described by this local resources object is made available. |
rights | A statement that concerns all rights not addresses by the license such as a copyright statement. |
In practice the responsible standard would define how the two sets of properties are merged into the local resources catalog. In this example it is straight forward since the collections object (path: /collections) is sparse and most catalog properties can be added without issue. It should further be noted that for the collections object (path: /collections) the name of the array containing the local resources items (i.e., the records) is “collections” and so the value of the recordsArrayName property would be set to “collections”.
8.4.5. Extending the local resources item
As an example of a local resources item, consider the collection object defined in defined in OGC API — Features. The following table cross-walks the information content of the collection object with the properties defined for the Record Core common component:
Table 16 — Crosswalk of collection and record properties
Collection property | Requirement | Record property | Requirement |
---|---|---|---|
id | required | id | required |
— | — | created | optional |
— | — | updated | optional |
— | — | conformsTo | optional |
— | — | type | optional |
itemType | optional | — | — |
title | optional | title | optional |
description | optional | description | optional |
extent (space) | optional | geometry | optional |
extent (time) | optional | time | optional |
crs | optional | — | — |
— | — | keywords | optional |
— | — | themes | optional |
— | — | language | optional |
— | — | languages | optional |
— | — | resourceLanguages | optional |
— | — | externalIds | optional |
— | — | formats | optional |
— | — | contacts | optional |
— | — | license | optional |
— | — | rights | optional |
links | required | links | optional |
linkTemplates | optional | linkTemplates | optional |
Many of the properties of the collection, a local resources item, are also properties of a record but the searchability of the collection can be improved by enhancing its information content. Thus, the following requirements and recommendations are made:
Identifier | /req/local-resources-catalog/mandatory-record-properties |
---|---|
Included in | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
A | Each record accessible via the local resource catalog SHALL contain all the mandatory properties listed in Table 8 and Table 9. |
In practice the responsible standard would define how the two sets of properties are merged into the local resources item. In this case it is straight forward since the collection object (path: /collections/{collectionID}) and the record share a large number of properties. Where there is a difference, extent versus geometry and time, can be handled by including both sets of properties in the local resources i.e., and ensuring that their values are consistent.
8.4.6. Examples
8.4.6.1. Collections example
The following JSON Schema fragments illustrate how to extend the https://docs.ogc.org/is/17-069r4/17-069r4.html#_collections_ [collections object] (a local resources catalog) and the collection object (a local resources item) to include properties required and recommended by this requirements class.
---
allOf:
- $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collections.yaml'
- $ref: '../../../openapi/schemas/catalogCommonProperties.yaml'
- type: object
properties:
itemType:
type: string
enum:
- record
recordsArrayName:
type: string
enum:
- collections
Listing 44
---
allOf:
- $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml'
- $ref: '../../../openapi/schemas/recordCommonProperties.yaml'
Listing 45
NOTE: Referenced schemas can be found at:
8.4.6.2. Processes example
The following JSON Schema fragments illustrate how to extend the processes object (a local resources catalog) and the process summary (a local resources item) to include properties required and recommended by this requirements class.
---
allOf:
- $ref: 'https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/processList.yaml'
- $ref: '../../../openapi/schemas/catalogCommonProperties.yaml'
- type: object
properties:
itemType:
type: string
enum:
- record
recordsArrayName:
type: string
enum:
- processes
Listing 46
---
allOf:
- $ref: 'https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/processSummary.yaml'
- $ref: '../../../openapi/schemas/recordCommonProperties.yaml'
Listing 47
NOTE 1: Referenced schemas can be found at:
NOTE 2: T.D.B. Should add an instance example of a collection object.
8.4.7. Discovery of local resources catalog endpoints
Discovery of which local resources catalog endpoints in an OGC API deployment are instrumented for catalog-like searching is accomplished using Autodiscovery.
Identifier | /req/local-resources-catalog/discovery |
---|---|
Included in | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
A | The links section of a server’s landing page SHALL include one link (relation: http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog) for each API endpoint (e.g., /collections) that has been instrumented to be a local resources catalog. |
8.4.8. Requirements Class “Local Resources Catalog — Query Parameters” (Deployment)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/query-parameters |
---|---|
Target type | Web API |
Prerequisites | Local Resources Catalog Record Core Query Parameters |
Normative statements | Requirement 84: /req/local-resource-catalog/query-parameters/conformance Requirement 85: /req/local-resources-catalog/query-parameters Requirement 86: /req/local-resources-catalog/response |
Identifier | /req/local-resource-catalog/query-parameters/conformance |
---|---|
Included in | Requirements class 16: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/query-parameters |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of this requirements class SHALL declare the following conformance classes in the conformance declaration: |
8.4.8.1. Operation
Identifier | /req/local-resources-catalog/query-parameters |
---|---|
Included in | Requirements class 16: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/query-parameters |
A | The server SHALL, at the local resources endpoint, implement one or more of the Record Core Query Parameters as required to satisfy the server’s search requirements. |
B | The set of Record Core Query Parameters implemented at the local resources endpoint SHALL be defined in the server’s API definition document. |
8.4.8.2. Response
Identifier | /req/local-resources-catalog/response |
---|---|
Included in | Requirements class 16: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/query-parameters |
A | A successful execution of the operation SHALL be reported as a response with a HTTP status code 200. |
B | The response SHALL conform to the requirements of the local resources endpoint being extended. |
C | The response SHALL only include local resources objects selected by the request (e.g., only collections that satisfy the query predicates are retrieved from the /collections endpoint). |
8.4.9. Requirements Class “Local Resources Catalog — Filtering” (Deployment)
8.4.9.1. Overview
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering |
---|---|
Target type | Web API |
Prerequisites | Local Resources Catalog Filtering |
Normative statements | Requirement 87: /req/local-resource-catalog/filtering-conformance Requirement 88: /req/local-resources-catalog/filtering Requirement 89: /req/features-filter/filtering/queryables-link |
The Local Resources Catalog — Filtering requirements class specifies requirements and recommendations for supporting advanced filtering at local resource catalog endpoints.
8.4.9.2. Conformance
Identifier | /req/local-resource-catalog/filtering-conformance |
---|---|
Included in | Requirements class 17: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of this requirements class SHALL declare the following conformance classes in the conformance declaration: |
8.4.9.3. Filtering
Identifier | /req/local-resources-catalog/filtering |
---|---|
Included in | Requirements class 17: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering |
Statement | Implementations that offer enhanced filtering SHALL, at the local resources catalog endpoint (e.g., /collections), implement the following requirements class. |
A |
Identifier | /req/features-filter/filtering/queryables-link |
---|---|
Included in | Requirements class 17: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering |
A | Implementations of this requirements class SHALL, in the links section of the local resources endpoint, include a link (relation: http://www.opengis.net/def/rel/ogc/1.0/queryables). |
B | This link SHALL point to a resource for discovering the list of record properties (and their types) that may be used to construct a filter expressions. |
8.4.10. Requirements Class “Local Resources Catalog — Sorting” (Deployment)
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting |
---|---|
Target type | Web API |
Conformance class | Conformance class A.16: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog/sorting |
Prerequisites | Local Resources Catalog Sorting |
Normative statements | Requirement 90: /req/local-resources-catalog/sorting-conformance Requirement 91: /req/local-resources-catalog/sorting |
The Local Resources Catalog — Sorting requirements class specifies requirements and recommendations for supporting sorting of responses at local resource catalog endpoints.
8.4.10.1. Conformance
Identifier | /req/local-resources-catalog/sorting-conformance |
---|---|
Included in | Requirements class 18: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting |
A | A server’s conformance declaration SHALL be retrieved from the /conformance endpoint as defined in the Declaration of conformance classes clause of the OGC API — Features — Part 1: Core Standard. |
B | An implementation of this requirements class SHALL declare the following conformance classes in the conformance declaration: |
8.4.10.2. Sorting
Identifier | /req/local-resources-catalog/sorting |
---|---|
Included in | Requirements class 18: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting |
Statement | Implementations of sorting of record responses SHALL, at the local resources endpoint (e.g., /collections), implement the following requirements class. |
A |
See also: /req/sorting/get-sortables-op, /req/sorting/get-sortables-success.
8.4.10.3. Examples
The following example illustrates a catalog filter expression being applied to the local resources endpoint /collections. In this case, the client is seeking all collection objects whose extent intersects a specified bounding box and that include the keyword “windmills”.
Client Server
| |
| GET /collections?bbox=3,50,8,54&q=windmills HTTP/1.1 |
| Accept: application/json |
|-------------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "collections": [ |
| { |
| "id": "dutch_windmills", |
| "title": "Windmills within The Netherlands", |
| "description": "Locations of windmills within the Neth|
| erlands from Rijksdienst voor het Cultureel Erfgoed (|
| RCE) INSPIRE WFS. Uses GeoServer WFS v2 backend via O|
| GRProvider.", |
| "keywords": [ |
| "Netherlands", |
| "INSPIRE", |
| "Windmills", |
| "Heritage", |
| "Holland", |
| "RD" |
| ], |
| "links": [ |
| { |
| "type": "text/html", |
| "rel": "canonical", |
| "title": "information", |
| "href": "https://www.nationaalgeoregister.nl/geone|
| twork/srv/dut/catalog.search#/metadata/29|
| 1afe4b-4f4b-497c-8026-fb437c4e9c7e", |
| "hreflang": "nl-NL" |
| }, |
| { |
| "type": "application/json", |
| "rel": "root", |
| "title": "Landing page of this server as JSON", |
| "href": "https://demo.pygeoapi.io/master?f=json" |
| }, |
| { |
| "type": "text/html", |
| "rel": "root", |
| "title": "Landing page of this server as HTML", |
| "href": "https://demo.pygeoapi.io/master?f=html" |
| }, |
| { |
| "type": "application/json", |
| "rel": "self", |
| "title": "This document as JSON", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills?f=json" |
| }, |
| { |
| "type": "application/ld+json", |
| "rel": "alternate", |
| "title": "This document as RDF (JSON-LD)", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills?f=jsonld" |
| }, |
| { |
| "type": "text/html", |
| "rel": "alternate", |
| "title": "This document as HTML", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills?f=html" |
| }, |
| { |
| "type": "application/json", |
| "rel": "http://www.opengis.net/def/rel/ogc/1.0/sch|
| ema", |
| "title": "Schema of collection in JSON", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/schema?f=json" |
| }, |
| { |
| "type": "text/html", |
| "rel": "http://www.opengis.net/def/rel/ogc/1.0/sch|
| ema", |
| "title": "Schema of collection in HTML", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/schema?f=html" |
| }, |
| { |
| "type": "application/schema+json", |
| "rel": "http://www.opengis.net/def/rel/ogc/1.0/que|
| ryables", |
| "title": "Queryables for this collection as JSON",|
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/queryables?f=json" |
| }, |
| { |
| "type": "text/html", |
| "rel": "http://www.opengis.net/def/rel/ogc/1.0/que|
| ryables", |
| "title": "Queryables for this collection as HTML",|
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/queryables?f=html" |
| }, |
| { |
| "type": "application/geo+json", |
| "rel": "items", |
| "title": "Items as GeoJSON", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/items?f=json" |
| }, |
| { |
| "type": "application/ld+json", |
| "rel": "items", |
| "title": "Items as RDF (GeoJSON-LD)", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/items?f=jsonld" |
| }, |
| { |
| "type": "text/html", |
| "rel": "items", |
| "title": "Items as HTML", |
| "href": "https://demo.pygeoapi.io/master/collectio|
| ns/dutch_windmills/items?f=html" |
| } |
| ], |
| "extent": { |
| "spatial": { |
| "bbox": [ |
| [ |
| 3.37, |
| 50.75, |
| 7.21, |
| 53.47 |
| ] |
| ], |
| "crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS|
| 84" |
| }, |
| "temporal": { |
| "interval": [ |
| [ |
| null, |
| null |
| ] |
| ] |
| } |
| }, |
| "itemType": "feature", |
| "crs": [ |
| "http://www.opengis.net/def/crs/OGC/1.3/CRS84", |
| "http://www.opengis.net/def/crs/EPSG/0/4326", |
| "http://www.opengis.net/def/crs/EPSG/0/3857", |
| "http://www.opengis.net/def/crs/EPSG/0/4258", |
| "http://www.opengis.net/def/crs/EPSG/0/28992" |
| ], |
| "storageCRS": "http://www.opengis.net/def/crs/EPSG/0/2|
| 8992" |
| } |
| ], |
| "links": [ |
| { |
| "type": "application/json", |
| "rel": "self", |
| "title": "This document as JSON", |
| "href": "https://demo.pygeoapi.io/master/collections?f|
| =json" |
| }, |
| { |
| "type": "application/ld+json", |
| "rel": "alternate", |
| "title": "This document as RDF (JSON-LD)", |
| "href": "https://demo.pygeoapi.io/master/collections?f|
| =jsonld" |
| }, |
| { |
| "type": "text/html", |
| "rel": "alternate", |
| "title": "This document as HTML", |
| "href": "https://demo.pygeoapi.io/master/collections?f|
| =html" |
| } |
| ] |
| } |
|<--------------------------------------------------------------|
Listing 48
9. Media Types
9.1. Overview
The OGC API — Records Standard does not mandate any particular encoding for a record or a catalog. However, it does provide requirements classes for encodings that are commonly used in implementations of OGC API Standards. These encodings include JSON and HTML. This clause indicates the media that to be used for these encodings of the resources defined in this Standard.
9.2. Media types
A description of the MIME types is mandatory for any OGC API Standard that specifies requirements for data encoding(s). Table 17 provides a list of suitable MIME types for records and catalogs.
Table 17 — API — Records MIME Types
Encoding | Media Type | Profile Identifier | |
---|---|---|---|
Record | HTML | text/html | n/a |
JSON | application/json | ogc-record | |
GeoJSON | application/geo+json | ogc-record | |
Catalog | HTML | text/html | n/a |
JSON | application/json | ogc-catalog | |
application/ogc-catalog+json | n/a |
A JSON-encoded record can be identified using the media type application/json or application/geo+json. Neither media type, however, specifically identifies the content as a record as defined in this Standard. For this reason, this Standard defines the profile identifier http://www.opengis.net/def/profile/OGC/0/ogc-record to more specifically identify JSON-encoded record content using the profiling mechanism defined in RFC 6909, The ‘profile’ Link Relation Type.
A JSON-encoded catalog resource can be specifically identified using the media type application/ogc-catalog+json but there might be situations where use of the generic media type, application/json, is more appropriate. For these siturations this standard defines the profile identifier http://www.opengis.net/def/profile/OGC/0/ogc-catalog to more specifically identify JSON-encoded Catalog content using the profiling mechanism defined in RFC 6909, The ‘profile’ Link Relation Type.
NOTE 1: The tokens ogc-record and ogc-catalog in Table 17 are the profile identifiers extracted from the complete profile URIs of:
NOTE 2: It should be noted that the use of a generic media type without profile links may require that a resource be completely retrieved and inspected to determine conclusively that it is a record or catalog resource. On the other hand, using resource-specific media types or generic media types with profile links indicates the specific type of resource being dealt with without the need to first retrieve and inspect the complete resource in order to make the type determination.
9.3. Examples
9.3.1. Catalog example
The following example illustrates two ways that a server could respond to a request for a JSON-encoded catalog.
This first response example uses the specific media type, application/ogc-catalog+json, to indicate that the response content is a JSON-encoded catalog.
Client Server
| |
| GET /collections/dutch_windmills HTTP/1.1 |
| Accept: application/ogc-catalog+json |
|----------------------------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Content-Type: application/ogc-catalog+json |
| Link: <http://www.opengis.net/def/profile/OGC/0/ogc-catalog>; rel="profile"|
| |
| { |
| "id":"dutch_windmills", |
| "type": "Collection", |
| "title":"Windmills within The Netherlands", |
| "description":"Locations of windmills within the Netherlands", |
| "itemType":"record", |
| "keywords":[ |
| "Netherlands", |
| "INSPIRE", |
| "Windmills", |
| "Heritage", |
| "Holland", |
| "RD" |
| ], |
| "links":[ |
| . |
| . |
| . |
| { |
| "type":"application/geo+json", |
| "rel":"items", |
| "title":"Items as GeoJSON", |
| "href":"https://demo.pygeoapi.io/master/collections/dutch_windmills/items?f=json"
| }, |
| { |
| "type":"application/ld+json", |
| "rel":"items", |
| "title":"Items as RDF (GeoJSON-LD)", |
| "href":"https://demo.pygeoapi.io/master/collections/dutch_windmills/items?f=jsonld"
| }, |
| { |
| "href": "http://www.opengis.net/def/profile/OGC/0/ogc-catalog", |
| "rel": "profile", |
| "title": "This is a Catalog" |
| }, |
| . |
| . |
| . |
| ], |
| "extent":{ |
| "spatial":{ |
| "bbox":[ |
| [ |
| 3.37, |
| 50.75, |
| 7.21, |
| 53.47 |
| ] |
| ], |
| "crs":"http://www.opengis.net/def/crs/OGC/1.3/CRS84" |
| }, |
| "temporal":{ |
| "interval":[ |
| [ |
| null, |
| null |
| ] |
| ] |
| } |
| }, |
| "crs":[ |
| "http://www.opengis.net/def/crs/OGC/1.3/CRS84", |
| "http://www.opengis.net/def/crs/EPSG/0/4326", |
| "http://www.opengis.net/def/crs/EPSG/0/3857", |
| "http://www.opengis.net/def/crs/EPSG/0/4258", |
| "http://www.opengis.net/def/crs/EPSG/0/28992" |
| ], |
| "storageCRS":"http://www.opengis.net/def/crs/EPSG/0/28992" |
| } |
|<-----------------------------------------------------------------------------|
Listing 49
This second response example uses a generic media type, application/json, with a profile link (identifier: ogc-catalog) to indicate that the response content is a JSON-encoded catalog. As per RFC 6909 and recommendation /rec/query-param-profile/link-header the response includes a profile link in the response HTTP headers.
Client Server
| |
| GET /collections/dutch_windmills?profile=ogc-catalog HTTP/1.1 |
| Accept: application/json |
|----------------------------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| Link: <http://www.opengis.net/def/profile/OGC/0/ogc-catalog>; rel="profile"|
| |
| { |
| "id":"dutch_windmills", |
| "type": "Collection", |
| "title":"Windmills within The Netherlands", |
| "description":"Locations of windmills within the Netherlands", |
| "itemType":"record", |
| "keywords":[ |
| "Netherlands", |
| "INSPIRE", |
| "Windmills", |
| "Heritage", |
| "Holland", |
| "RD" |
| ], |
| "links":[ |
| . |
| . |
| . |
| { |
| "type":"application/geo+json", |
| "rel":"items", |
| "title":"Items as GeoJSON", |
| "href":"https://demo.pygeoapi.io/master/collections/dutch_windmills/items?f=json"
| }, |
| { |
| "type":"application/ld+json", |
| "rel":"items", |
| "title":"Items as RDF (GeoJSON-LD)", |
| "href":"https://demo.pygeoapi.io/master/collections/dutch_windmills/items?f=jsonld"
| }, |
| { |
| "href": "http://www.opengis.net/def/profile/OGC/0/ogc-catalog", |
| "rel": "profile", |
| "title": "This is a Catalog" |
| }, |
| . |
| . |
| . |
| ], |
| "extent":{ |
| "spatial":{ |
| "bbox":[ |
| [ |
| 3.37, |
| 50.75, |
| 7.21, |
| 53.47 |
| ] |
| ], |
| "crs":"http://www.opengis.net/def/crs/OGC/1.3/CRS84" |
| }, |
| "temporal":{ |
| "interval":[ |
| [ |
| null, |
| null |
| ] |
| ] |
| } |
| }, |
| "crs":[ |
| "http://www.opengis.net/def/crs/OGC/1.3/CRS84", |
| "http://www.opengis.net/def/crs/EPSG/0/4326", |
| "http://www.opengis.net/def/crs/EPSG/0/3857", |
| "http://www.opengis.net/def/crs/EPSG/0/4258", |
| "http://www.opengis.net/def/crs/EPSG/0/28992" |
| ], |
| "storageCRS":"http://www.opengis.net/def/crs/EPSG/0/28992" |
| } |
|<-----------------------------------------------------------------------------|
Listing 50
In both cases the server follows good practice and includes the profile link in the links section of the catalog for those situations where the response document is dissociated from the server that generated it.
9.3.2. Record example
The following example illustrates how a server might respond to a request for a GeoJSON-encoded record.
As per RFC 6906, recommendation /rec/query-param-profile/link-header and recommendation /rec/json/header-profile-link the response includes a profile link in the response HTTP headers. The same link is also included in the links section of the record for those situations where the response document is dissociated from the server that generated it.
Client Server
| |
| GET /collections/my_catalog/items/r01?profile=ogc-record HTTP/1.1 |
| Accept: application/geo+json |
|----------------------------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Content-Type: application/geo+json |
| Link: <http://www.opengis.net/def/profile/OGC/0/ogc-record>; rel="profile" |
| |
| { |
| |
| ... JSON-encoded records content ... |
| |
| "links": [ |
| . |
| . |
| . |
| { |
| "href": "http://www.opengis.net/def/profile/OGC/0/ogc-record", |
| "rel": "profile", |
| "title": "This is a OARec Record" |
| }, |
| . |
| . |
| . |
| ] |
| } |
|<-----------------------------------------------------------------------------|
Listing 51
9.4. Default Encodings
The canonical method of selecting a desired response encoding is to use HTTP content negotiation. However, content negotiation is not required by the HTTP standard. Therefore, default encodings must be established.
Identifier | /req/record-core/default-mediatype |
---|---|
Included in | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
A | If the JSON conformance class is advertised, then the default media type for record content SHALL be GeoJSON (i.e., application/geo+json; application=ogc-record). |
B | If the JSON conformance class is not advertised, then the default media type for record content SHALL be HTML (i.e text/html). |
Identifier | /req/record-collection/default-mediatype |
---|---|
Included in | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
A | If the JSON conformance class is advertised, then the default media type for catalog content SHALL be JSON (i.e., application/ogc-catalog+json). |
B | If the JSON conformance class is not advertised, then the default media type for catalog content SHALL be HTML (i.e., text.html). |
10. Requirements Class “Profile query parameter”
The Requirements Class “Profile query parameter” specifies additional provisions for properties that reference another resource.
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/query-param-profile |
---|---|
Target type | Web API |
Conformance class | Conformance class A.5: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/query-param-profile |
Normative statements | Requirement 94: /req/query-param-profile/definition Requirement 95: /req/query-param-profile/response |
Some properties may be represented in multiple representations in the same format, depending on the intended use of the data. One example are references to another web resource (see the [rc_profile-references]).
RFC 6906 The ‘profile’ Link Relation Type defines the concept of a profile to support such use cases.
A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms.
To request one or more profiles, a query parameter “profile” can be used:
Identifier | /req/query-param-profile/definition |
---|---|
Included in | Requirements class 19: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/query-param-profile |
A | A Records API implementation SHALL support the Profile (profile) parameter for the GET operation. |
B | The following OpenAPI 3.0 schema fragment SHALL define the characteristics of the profile parameter:
name: profile |
C | Each i.e., SHALL be one of the following:
|
Determining the profile(s) of the response is part of the content negotiation process after the proactive content negotiation as specified by the HTTP RFC has been completed. The server determines the applicable profile(s) for the selected media type.
Different media types have different characteristics. A consequence is that it can be impossible to support a profile for a media type or it can be against the design goals of a media type to support a profile.
The server will select the profile(s) of the response, if any, from the list of profiles supported for the media type and resource.
Identifier | /rec/query-param-profile/negotiation |
---|---|
A | If the server supports one or more of the requested profile(s) for the media type and resource, these profiles SHOULD be used for the response. |
B | The profile negotiation SHOULD NOT result in an error, e.g., because a requested profile cannot be provided. |
Identifier | /req/query-param-profile/response |
---|---|
Included in | Requirements class 19: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/query-param-profile |
A | The query parameter is not required, that is, omitting the parameter in a request SHALL not result in an error. |
B | If the media type of the response supports web links in accordance with RFC 8288 Web Linking, the response SHALL include links to the selected profile(s) with the link relation type “profile”. |
Identifier | /rec/query-param-profile/link-header |
---|---|
A | The response SHOULD include links to the selected profile(s) in the HTTP response headers. |
Annex A
(normative)
Conformance Class Abstract Test Suite (Normative)
A.1. Common components
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core |
---|---|
Requirements class | Requirements class 1: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core |
Target Type | Web API |
Conformance tests | Abstract test A.1: /conf/record-core/mandatory-properties-record Abstract test A.2: /conf/record-core/links Abstract test A.3: /conf/record-core/templated-link Abstract test A.4: /conf/record-core/templated-link-header Abstract test A.5: /conf/record-core/license Abstract test A.6: /conf/record-core/contact Abstract test A.7: /conf/record-core/time-instant-interval Abstract test A.8: /conf/record-core/time-instant Abstract test A.9: /conf/record-core/time-interval Abstract test A.10: /conf/record-core/time-zone Abstract test A.11: /conf/record-core/default-mediatype |
A.1.1. Mandatory properties
Identifier | /conf/record-core/mandatory-properties-record |
---|---|
Requirement | Requirement 1: /req/record-core/mandatory-properties-record |
Test purpose | Validate that a catalog record includes all mandatory properties. |
Test method |
|
A.1.2. Links
Identifier | /conf/record-core/links |
---|---|
Requirement | Requirement 8: /req/record-core/links |
Test purpose | Validate the behavior of link relations for link objects. |
Test method |
|
A.1.3. Link templates
Identifier | /conf/record-core/templated-link |
---|---|
Requirement | Requirement 9: /req/record-core/templated-link |
Test purpose | Validate the behavior of templated links. |
Test method |
|
Identifier | /conf/record-core/templated-link-header |
---|---|
Requirement | Requirement 10: /req/record-core/templated-link-header |
Test purpose | Validate the behavior of templated link header. |
Test method |
|
A.1.4. License
Identifier | /conf/record-core/license |
---|---|
Requirement | Requirement 7: /req/record-core/license |
Test purpose | Validate the behavior of license object. |
Test method |
|
A.1.5. Contacts
Identifier | /conf/record-core/contact |
---|---|
Requirement | Requirement 6: /req/record-core/contact |
Test purpose | Validate the behavior of contacts objects. |
Test method |
|
A.1.6. Time
Identifier | /conf/record-core/time-instant-interval |
---|---|
Requirement | Requirement 4: /req/record-core/time-instant-interval |
Test purpose | Validate the behavior of time instance and intervals in time object. |
Test method |
|
Identifier | /conf/record-core/time-instant |
---|---|
Requirement | Requirement 2: /req/record-core/time-instant |
Test purpose | Validate the behavior of time instances for time objects. |
Test method |
|
Identifier | /conf/record-core/time-interval |
---|---|
Requirement | Requirement 3: /req/record-core/time-interval |
Test purpose | Validate the behavior of time interval for time objects. |
Test method |
|
Identifier | /conf/record-core/time-zone |
---|---|
Requirement | Requirement 5: /req/record-core/time-zone |
Test purpose | Validate the behavior of time zone for time member. |
Test method |
|
A.1.7. Default media type
Identifier | /conf/record-core/default-mediatype |
---|---|
Requirement | Requirement 92: /req/record-core/default-mediatype |
Test purpose | Check the default encoding for a catalog record. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection |
---|---|
Requirements class | Requirements class 2: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection |
Target Type | Web API |
Conformance tests | Abstract test A.12: /conf/record-collection/mandatory-properties-collection Abstract test A.13: /conf/record-collection/itemType Abstract test A.14: /conf/record-collection/contact Abstract test A.15: /conf/record-collection/license Abstract test A.16: /conf/record-collection/links Abstract test A.17: /conf/record-collection/links-catalog-hierarchy Abstract test A.18: /conf/record-collection/links-catalog-related Abstract test A.19: /conf/record-collection/links-catalog-series Abstract test A.20: /conf/record-collection/links-record Abstract test A.21: /conf/record-collection/links-records Abstract test A.22: /conf/record-collection/records-array-name Abstract test A.23: /conf/record-collection/records Abstract test A.24: /conf/record-collection/default-mediatype |
A.1.8. Catalog properties
Identifier | /conf/record-collection/mandatory-properties-collection |
---|---|
Requirement | Requirement 11: /req/record-collection/mandatory-properties-collection |
Test purpose | Validate that a catalog object includes all mandatory properties. |
Test method |
|
Identifier | /conf/record-collection/itemType |
---|---|
Requirement | Requirement 12: /req/record-collection/itemType |
Test purpose | Validate the behavior of itemType member. |
Test method |
|
Identifier | /conf/record-collection/contact |
---|---|
Requirement | Requirement 13: /req/record-collection/contact |
Test purpose | Validate the behavior of contacts objects. |
Test method |
|
Identifier | /conf/record-collection/license |
---|---|
Requirement | Requirement 14: /req/record-collection/license |
Test purpose | Validate the behavior of the license member. |
Test method |
|
A.1.9. Catalog links
Identifier | /conf/record-collection/links |
---|---|
Requirement | Requirement 22: /req/record-collection/links |
Test purpose | Validate the behavior of “self” and “alternate” links. |
Test method |
|
Identifier | /conf/record-collection/links-catalog-hierarchy |
---|---|
Requirement | Requirement 21: /req/record-collection/links-catalog-hierarchy |
Test purpose | Validate the behavior of link relations to sub-ordinate catalogs. |
Test method |
|
Identifier | /conf/record-collection/links-catalog-related |
---|---|
Requirement | Requirement 19: /req/record-collection/links-catalog-related |
Test purpose | Validate the behavior of link to related catalogs. |
Test method |
|
Identifier | /conf/record-collection/links-catalog-series |
---|---|
Requirement | Requirement 20: /req/record-collection/links-catalog-series |
Test purpose | Validate the behavior of a series of catalogs. |
Test method |
|
Identifier | /conf/record-collection/links-record |
---|---|
Requirement | Requirement 15: /req/record-collection/links-record |
Test purpose | Validate the behavior of explicit links to records. |
Test method |
|
Identifier | /conf/record-collection/links-records |
---|---|
Requirement | Requirement 16: /req/record-collection/links-records |
Test purpose | Validate the behavior of a link to a record retrieval endpoint. |
Test method |
|
A.1.10. Catalog records
Identifier | /conf/record-collection/records-array-name |
---|---|
Requirement | Requirement 18: /req/record-collection/records-array-name |
Test purpose | Validate that the named of the inline records array is correctly advertised. |
Test method |
|
Identifier | /conf/record-collection/records |
---|---|
Requirement | Requirement 17: /req/record-collection/records |
Test purpose | Validate that inline records are correctly represented. |
Test method |
|
A.1.11. Media type
Identifier | /conf/record-collection/default-mediatype |
---|---|
Requirement | Requirement 93: /req/record-collection/default-mediatype |
Test purpose | Check the default encoding for a catalog. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/records-api |
---|---|
Requirements class | Requirements class 4: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |
Target Type | Web API |
Conformance tests | Abstract test A.25: /conf/records-api/features-api Abstract test A.26: /conf/records-api/catalog-response Abstract test A.27: /conf/records-api/catalogs-response Abstract test A.28: /conf/records-api/record-op Abstract test A.29: /conf/records-api/record-response Abstract test A.30: /conf/records-api/records-op Abstract test A.31: /conf/records-api/resource-name-mapping Abstract test A.32: /conf/records-api/mandatory-params |
A.1.12. Records API
Identifier | /conf/records-api/features-api |
---|---|
Requirement | Requirement 34: /req/records-api/features-api |
Test purpose | Validate compliance to Features Core. |
Test method |
|
Identifier | /conf/records-api/catalog-response |
---|---|
Requirement | Requirement 36: /req/records-api/catalog-response |
Test purpose | Validate collection API endpoint. |
Test method |
|
Identifier | /conf/records-api/catalogs-response |
---|---|
Requirement | Requirement 37: /req/records-api/catalogs-response |
Test purpose | Validate collections API endpoint. |
Test method |
|
Identifier | /conf/records-api/record-op |
---|---|
Requirement | Requirement 41: /req/records-api/record-op |
Test purpose | Validate that a record can be retrieved from the expected location. |
Test method |
|
Identifier | /conf/records-api/record-response |
---|---|
Requirement | Requirement 42: /req/records-api/record-response |
Test purpose | Validate a record response from the API. |
Test method |
|
Identifier | /conf/records-api/records-op |
---|---|
Requirement | Requirement 38: /req/records-api/records-op |
Test purpose | Validate that records can be retrieved from a catalog using query parameters. |
Test method |
|
Identifier | /conf/records-api/resource-name-mapping |
---|---|
Requirement | Requirement 35: /req/records-api/resource-name-mapping |
Test purpose | Validate the Records API implementation using Features API Standard with naming mapping. |
Test method |
|
Identifier | /conf/records-api/mandatory-params |
---|---|
Requirement | Requirement 39: /req/records-api/mandatory-params |
Test purpose | Validate each record containing the mandatory properties. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters |
---|---|
Requirements class | Requirements class 3: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters |
Target Type | Web API |
Conformance tests | Abstract test A.33: /conf/record-core-query-parameters/bbox Abstract test A.34: /conf/record-core-query-parameters/datetime Abstract test A.35: /conf/record-core-query-parameters/externalIds-definition Abstract test A.36: /conf/record-core-query-parameters/externalIds-response Abstract test A.37: /conf/record-core-query-parameters/ids-definition Abstract test A.38: /conf/record-core-query-parameters/ids-response Abstract test A.39: /conf/record-core-query-parameters/limit Abstract test A.40: /conf/record-core-query-parameters/q-definition Abstract test A.41: /conf/record-core-query-parameters/q-response Abstract test A.42: /conf/record-core-query-parameters/type-definition Abstract test A.43: /conf/record-core-query-parameters/type-response |
A.1.13. Query Parameters
Identifier | /conf/record-core-query-parameters/bbox |
---|---|
Requirement | Requirement 23: /req/record-core-query-parameters/bbox |
Test purpose | Validate bbox query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/datetime |
---|---|
Requirement | Requirement 24: /req/record-core-query-parameters/datetime |
Test purpose | Validate datetime query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/externalIds-definition |
---|---|
Requirement | Requirement 32: /req/record-core-query-parameters/externalIds-definition |
Test purpose | Validate externalIds query parameter. |
Test method |
name: externalIds
|
Identifier | /conf/record-core-query-parameters/externalIds-response |
---|---|
Requirement | Requirement 33: /req/record-core-query-parameters/externalIds-response |
Test purpose | Validate externalIds query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/ids-definition |
---|---|
Requirement | Requirement 30: /req/record-core-query-parameters/ids-definition |
Test purpose | Validate ids query parameter. |
Test method |
name: ids
|
Identifier | /conf/record-core-query-parameters/ids-response |
---|---|
Requirement | Requirement 31: /req/record-core-query-parameters/ids-response |
Test purpose | Validate ids query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/limit |
---|---|
Requirement | Requirement 25: /req/record-core-query-parameters/limit |
Test purpose | Validate limit query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/q-definition |
---|---|
Requirement | Requirement 26: /req/record-core-query-parameters/q-definition |
Test purpose | Validate q query parameter. |
Test method |
name: q
|
Identifier | /conf/record-core-query-parameters/q-response |
---|---|
Requirement | Requirement 27: /req/record-core-query-parameters/q-response |
Test purpose | Validate q query parameter. |
Test method |
|
Identifier | /conf/record-core-query-parameters/type-definition |
---|---|
Requirement | Requirement 28: /req/record-core-query-parameters/type-definition |
Test purpose | Validate type query parameter. |
Test method |
name: type
|
Identifier | /conf/record-core-query-parameters/type-response |
---|---|
Requirement | Requirement 29: /req/record-core-query-parameters/type-response |
Test purpose | Validate type query parameter. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/query-param-profile |
---|---|
Requirements class | Requirements class 19: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/query-param-profile |
Target Type | Web API |
Conformance tests | Abstract test A.44: /conf/query-param-profile/definition Abstract test A.45: /conf/query-param-profile/response |
A.1.14. Query Parameter Profile
Identifier | /conf/query-param-profile/definition |
---|---|
Requirement | Requirement 94: /req/query-param-profile/definition |
Test purpose | Validate profile query parameter. |
Test method |
name: profile
|
Identifier | /conf/query-param-profile/response |
---|---|
Requirement | Requirement 95: /req/query-param-profile/response |
Test purpose | Validate profile query parameter. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/cql-filter |
---|---|
Requirements class | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/cql-filter |
Prerequisites | OGC API — Features — Part 3: Filtering Common Query Language (CQL2) |
Target Type | Web API |
Conformance tests | Abstract test A.46: /conf/record-filter/filter-param Abstract test A.47: /conf/record-filter/filter-lang-param Abstract test A.48: /conf/record-filter/filter-crs-param Abstract test A.49: /conf/record-filter/response |
A.1.15. Filter Parameters
Identifier | /conf/record-filter/filter-param |
---|---|
Requirement | /req/record-filter/filter-param |
Test purpose | Validate filter query parameter. |
Test method |
|
Identifier | /conf/record-filter/filter-lang-param |
---|---|
Requirement | Requirement 49: /req/record-filter/filter-lang-param |
Test purpose | Validate filter-lang query parameter. |
Test method |
|
Identifier | /conf/record-filter/filter-crs-param |
---|---|
Requirement | Requirement 50: /req/record-filter/filter-crs-param |
Test purpose | Validate filter-crs query parameter. |
Test method |
|
A.1.16. Filter Response
Identifier | /conf/record-filter/response |
---|---|
Requirement | Requirement 51: /req/record-filter/response |
Test purpose | Validate filter response. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting |
---|---|
Requirements class | Requirements class 5: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting |
Target Type | Web API |
Conformance tests | Abstract test A.50: /conf/sorting/conformance Abstract test A.51: /conf/sorting/defaultSortOrder-definition Abstract test A.52: /conf/sorting/get-sortables-op Abstract test A.53: /conf/sorting/get-sortables-success Abstract test A.54: /conf/sorting/sortby-definition Abstract test A.55: /conf/sorting/sortby-response |
A.1.17. Conformance
Identifier | /conf/sorting/conformance |
---|---|
Requirement | /req/sorting/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.1.18. Default sort order definition
Identifier | /conf/sorting/defaultSortOrder-definition |
---|---|
Requirement | Requirement 47: /req/sorting/defaultSortOrder-definition |
Test purpose | Validate the behavior of sort order definitions. |
Test method | Sequence 1:
Sequence 2:
Sequence 3:
|
A.1.19. Sortables endpoint
Identifier | /conf/sorting/get-sortables-op |
---|---|
Requirement | Requirement 45: /req/sorting/get-sortables-op |
Test purpose | Validate the behavior of sortables endpoint. |
Test method |
|
Identifier | /conf/sorting/get-sortables-success |
---|---|
Requirement | Requirement 46: /req/sorting/get-sortables-success |
Test purpose | Validate the behavior of sortables endpoint. |
Test method |
|
A.1.20. Query parameter definition
Identifier | /conf/sorting/sortby-definition |
---|---|
Requirement | /req/sorting/sortby-definition |
Test purpose | Validate the availability of the sortby query parameter. |
Test method |
|
A.1.21. Query parameter behavior
Identifier | /conf/sorting/sortby-response |
---|---|
Requirement | Requirement 44: /req/sorting/sortby-response |
Test purpose | Validate the availability of the sortby query parameter. |
Test method | Sequence 1:
Sequence 2:
Sequence 3:
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html |
---|---|
Requirements class | Requirements class 9: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html |
Target Type | Web API |
Conformance tests | Abstract test A.56: /conf/html/conformance Abstract test A.57: /conf/html/content Abstract test A.58: /conf/html/definition |
A.1.22. Conformance
Identifier | /conf/html/conformance |
---|---|
Requirement | Requirement 60: /req/html/conformance |
Test purpose | Validate html identification. |
Test method |
|
A.1.23. API
Identifier | /conf/html/content |
---|---|
Requirement | Requirement 62: /req/html/content |
Test purpose | Validate the HTML response content. |
Test method |
|
Identifier | /conf/html/definition |
---|---|
Requirement | Requirement 61: /req/html/definition |
Test purpose | Validate the content type of HTML response. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json |
---|---|
Requirements class | Requirements class 8: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json |
Target Type | Web API |
Conformance tests | Abstract test A.59: /conf/json/conformance Abstract test A.60: /conf/json/catalog-content Abstract test A.62: /conf/json/catalog-response Abstract test A.63: /conf/json/record-content Abstract test A.65: /conf/json/record-response |
A.1.24. Conformance
Identifier | /conf/json/conformance |
---|---|
Requirement | Requirement 53: /req/json/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.1.25. Catalog
Identifier | /conf/json/catalog-content |
---|---|
Requirement | Requirement 58: /req/json/catalog-content |
Test purpose | Validate the JSON representation of a catalog. |
Test method |
|
Identifier | /conf/json/catalog-content-profile |
---|---|
Requirement | Requirement 59: /req/json/catalog-content-profile |
Test purpose | Validate the JSON representation of a catalog. |
Test method |
|
Identifier | /conf/json/catalog-response |
---|---|
Requirement | /req/json/catalog-response |
Test purpose | Validate the JSON response of a catalog. |
Test method |
|
A.1.26. Record
Identifier | /conf/json/record-content |
---|---|
Requirement | Requirement 55: /req/json/record-content |
Test purpose | Validate the behavior of link relations for record geojson. |
Test method |
|
Identifier | /conf/json/record-content-profile |
---|---|
Requirement | Requirement 56: /req/json/record-content-profile |
Test purpose | Validate the behavior of link relations for record geojson. |
Test method |
|
Identifier | /conf/json/record-response |
---|---|
Requirement | Requirement 54: /req/json/record-response |
Test purpose | Validate the JSON response of a record. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30 |
---|---|
Requirements class | Requirements class 10: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/oas30 |
Target Type | Web API |
Conformance tests | Abstract test A.66: /conf/oas30/conformance Abstract test A.67: /conf/oas30/oas-common |
A.1.27. Conformance
Identifier | /conf/oas30/conformance |
---|---|
Requirement | Requirement 64: /req/oas30/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.1.28. API description document
Identifier | /conf/oas30/oas-common |
---|---|
Requirement | Requirement 63: /req/oas30/oas-common |
Test purpose | Validate oas30 service description document. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/autodiscovery |
---|---|
Requirements class | Requirements class 7: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/autodiscovery |
Target Type | Web API |
Conformance test | Abstract test A.68: /conf/autodiscovery/links |
A.1.29. Links
Identifier | /conf/autodiscovery/links |
---|---|
Requirement | Requirement 52: /req/autodiscovery/links |
Test purpose | Validate the behavior of link relations for searchable catalog autodiscovery. |
Test method |
|
A.2. Crawlable catalog
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog |
---|---|
Requirements class | Requirements class 11: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |
Prerequisites | Conformance class A.2: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection Conformance class A.1: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core |
Target Type | Web API |
Conformance tests | Abstract test A.69: /conf/crawlable-catalog/conformance Abstract test A.70: /conf/crawlable-catalog/record Abstract test A.71: /conf/crawlable-catalog/record-location Abstract test A.72: /conf/crawlable-catalog/catalog Abstract test A.73: /conf/crawlable-catalog/location |
A.2.1. Conformance
Identifier | /conf/crawlable-catalog/conformance |
---|---|
Requirement | Validate conformance identification. |
Test purpose | /req/crawlable-catalog/conformance |
Test method |
|
A.2.2. Record
Identifier | /conf/crawlable-catalog/record |
---|---|
Requirement | Requirement 65: /req/crawlable-catalog/record |
Test purpose | Verify that a record is retrieveble from the Web |
Test method |
|
Identifier | /conf/crawlable-catalog/record-location |
---|---|
Requirement | Requirement 66: /req/crawlable-catalog/record-location |
Test purpose | Validate a crawlable catalog. |
Test method |
|
A.2.3. Catalog
Identifier | /conf/crawlable-catalog/catalog |
---|---|
Requirement | Requirement 67: /req/crawlable-catalog/catalog |
Test purpose | Validate a crawlable catalog object |
Test method |
|
Identifier | /conf/crawlable-catalog/location |
---|---|
Requirement | Requirement 68: /req/crawlable-catalog/location |
Test purpose | Verify that a catalog is retrievable from the Web |
Test method |
|
A.3. Local Resources Catalog
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog |
---|---|
Requirements class | Requirements class 15: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog |
Prerequisites | Conformance class A.1: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core Conformance class A.2: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection Conformance class A.11: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/autodiscovery |
Target Type | Web API |
Conformance tests | Abstract test A.74: /conf/local-resources-catalog/conformance Abstract test A.75: /conf/local-resources-catalog/building-blocks Abstract test A.76: /conf/local-resources-catalog/discovery Abstract test A.77: /conf/local-resources-catalog/mandatory-catalog-properties Abstract test A.78: /conf/local-resources-catalog/mandatory-record-properties |
A.3.1. Conformance
Identifier | /conf/local-resources-catalog/conformance |
---|---|
Requirement | Requirement 80: /req/local-resources-catalog/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.3.2. Local resources catalog
Identifier | /conf/local-resources-catalog/building-blocks |
---|---|
Requirement | /req/local-resource-catalog/common |
Test purpose | Validate conformance identification. |
Test method |
A.3.3. Discovery
Identifier | /conf/local-resources-catalog/discovery |
---|---|
Requirement | Requirement 83: /req/local-resources-catalog/discovery |
Test purpose | Validate discovery identification. |
Test method |
|
A.3.4. Mandatory catalog properties
Identifier | /conf/local-resources-catalog/mandatory-catalog-properties |
---|---|
Requirement | Requirement 81: /req/local-resources-catalog/mandatory-catalog-properties |
Test purpose | Verify that all mandatory catalog properties are present. |
Test method |
|
A.3.5. Mandatory record properties
Identifier | /conf/local-resources-catalog/mandatory-record-properties |
---|---|
Requirement | Requirement 82: /req/local-resources-catalog/mandatory-record-properties |
Test purpose | Validate conformance identification. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resource-catalog/query-parameters |
---|---|
Requirements class | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resource-catalog/query-parameters |
Prerequisites | Conformance class A.13: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog Conformance class A.4: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters |
Target Type | Web API |
Conformance tests | Abstract test A.79: /conf/local-resources-catalog/query-parameters/conformance Abstract test A.80: /conf/local-resources-catalog/query-parameters/query-parameters Abstract test A.81: /conf/local-resources-catalog/query-parameters/query-parameters-response |
A.3.6. Conformance
Identifier | /conf/local-resources-catalog/query-parameters/conformance |
---|---|
Requirement | /req/local-resources-catalog/query-parameters/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.3.7. Query Parameters
Identifier | /conf/local-resources-catalog/query-parameters/query-parameters |
---|---|
Requirement | /req/local-resources-catalog/query-parameters/query-parameters |
Test purpose | Determine the set of supported query parameters. |
Test method |
|
A.3.8. Response
Identifier | /conf/local-resources-catalog/query-parameters/query-parameters-response |
---|---|
Requirement | /req/local-resources-catalog/query-parameters/query-parameters-response |
Test purpose | Validate query parameters response. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog-filtering |
---|---|
Requirements class | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog-filtering |
Prerequisites | Conformance class A.6: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/cql-filter Conformance class A.13: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog |
Target Type | Web API |
Conformance tests | Abstract test A.82: /conf/local-resources-catalog/filtering-conformance Abstract test A.83: /conf/local-resources-catalog/building-blocks/filtering Abstract test A.84: /conf/local-resources-catalog/filtering/queryables-link |
A.3.9. Conformance
Identifier | /conf/local-resources-catalog/filtering-conformance |
---|---|
Requirement | /req/local-resources-catalog/filtering-conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.3.10. Filtering
Identifier | /conf/local-resources-catalog/building-blocks/filtering |
---|---|
Requirement | Requirement 88: /req/local-resources-catalog/filtering |
Test purpose | Validate local-resources catalog CQL filtering. |
Test method |
|
A.3.11. Queryables link
Identifier | /conf/local-resources-catalog/filtering/queryables-link |
---|---|
Requirement | /req/local-resources-catalog/filtering/queryables-link |
Test purpose | Validate queryables link for local resources catalog. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog/sorting |
---|---|
Requirements class | Requirements class 18: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting |
Prerequisites | Conformance class A.13: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog Conformance class A.7: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting |
Target Type | Web API |
Conformance tests | Abstract test A.85: /conf/local-resources-catalog/sorting-conformance Abstract test A.86: /conf/local-resources-catalog/building-blocks/sorting |
A.3.12. Conformance
Identifier | /conf/local-resources-catalog/sorting-conformance |
---|---|
Requirement | Requirement 90: /req/local-resources-catalog/sorting-conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.3.13. Sorting
Identifier | /conf/local-resources-catalog/building-blocks/sorting |
---|---|
Requirement | Requirement 91: /req/local-resources-catalog/sorting |
Test purpose | Validate sorting. |
Test method |
|
A.4. Searchable Catalog
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog |
---|---|
Requirements class | Requirements class 12: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |
Target Type | Web API |
Conformance tests | Abstract test A.87: /conf/searchable-catalog/conformance Abstract test A.88: /conf/searchable-catalog/building-blocks Abstract test A.89: /conf/searchable-catalog/mandatory-catalog-properties Abstract test A.90: /conf/searchable-catalog/mandatory-record-properties |
A.4.1. Conformance
Identifier | /conf/searchable-catalog/conformance |
---|---|
Requirement | Requirement 71: /req/searchable-catalog/conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.4.2. Searchable catalog
Identifier | /conf/searchable-catalog/building-blocks |
---|---|
Requirement | Requirement 70: /req/searchable-catalog/common |
Test purpose | Validate conformance identification. |
Test method |
|
A.4.3. Mandatory catalog properties
Identifier | /conf/searchable-catalog/mandatory-catalog-properties |
---|---|
Requirement | Requirement 72: /req/searchable-catalog/mandatory-catalog-properties |
Test purpose | Verify that all mandatory catalog properties are present. |
Test method |
|
A.4.4. Mandatory record properties
Identifier | /conf/searchable-catalog/mandatory-record-properties |
---|---|
Requirement | Requirement 73: /req/searchable-catalog/mandatory-record-properties |
Test purpose | Validate each record contains the mandatory properties. |
Test method |
|
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog/filtering |
---|---|
Requirements class | Requirements class 13: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering |
Prerequisites | Conformance class A.17: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog Conformance class A.6: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/cql-filter |
Target Type | Web API |
Conformance tests | Abstract test A.91: /conf/searchable-catalog/filtering-conformance Abstract test A.92: /conf/searchable-catalog/building-blocks/filtering Abstract test A.93: /conf/searchable-catalog/mandatory-queryables |
A.4.5. Conformance
Identifier | /conf/searchable-catalog/filtering-conformance |
---|---|
Requirement | Requirement 75: /req/searchable-catalog/filtering-conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.4.6. Filtering
Identifier | /conf/searchable-catalog/building-blocks/filtering |
---|---|
Requirement | Requirement 74: /req/searchable-catalog/filtering |
Test purpose | Validate enhanced filtering. |
Test method |
|
A.4.7. Mandatory queryables
Identifier | /conf/searchable-catalog/mandatory-queryables |
---|---|
Requirement | Requirement 76: /req/searchable-catalog/mandatory-queryables |
Test purpose | Validate existence of mandatory queryables. |
Test method |
Identifier | http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog/sorting |
---|---|
Requirements class | Requirements class 14: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/sorting |
Prerequisites | Conformance class A.17: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog Conformance class A.7: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting |
Target Type | Web API |
Conformance tests | Abstract test A.94: /conf/searchable-catalog/sorting-conformance Abstract test A.95: /conf/searchable-catalog/building-blocks/sorting |
A.4.8. Conformance
Identifier | /conf/searchable-catalog/sorting-conformance |
---|---|
Requirement | Requirement 78: /req/searchable-catalog/sorting-conformance |
Test purpose | Validate conformance identification. |
Test method |
|
A.4.9. Sorting
Identifier | /conf/searchable-catalog/building-blocks/sorting |
---|---|
Requirement | Requirement 77: /req/searchable-catalog/sorting |
Test purpose | Validate sorting. |
Test method |
|
Annex B
(informative)
Implementation summaries (Informative)
B.1. Overview
This annex presents implementation summaries for the crawlable catalog searchable catalog and local resources catalog deployment patterns. This information is meant to be a short guide for developers.
B.2. Crawlable catalog
To implement a catalog where records are stored as individual files in one or more web-accessible locations and can be crawled by simply following hypermedia controls.
For each discoverable resource create a file that contains a summary description of the resource using the record schema defined in Table 8 and Table 9.
Extend the record schema to enrich its content as necessary.
To make the resource discoverable, place each record file in a web-accessible location, preferably co-located (e.g., in the same directory or object store location) with the resource that the record is describing.
Optionally create a file containing a description of a collection of related records.
Also place the collection file in a web-accessible location.
B.3. Searchable catalog
In order to implement a catalog where records are stored in some backend database and are accessed through an access/search API:
implement the OGC API — Features — Core: Part 1 Standard;
implement the parameters defined in Table 12;
implement the record schema defined in Table 8 and Table 9; and
extend the record schema to enrich its content as necessary.
B.4. Local resources catalog
In order to implement a local resource catalog at an OGC API resources endpoint such as /collections for example:
Annex C
(informative)
Common resource types (Informative)
C.1. Overview
This annex describes common resource types when qualifying resources via a record’s properties.type property, in the absence of a formal controlled vocabulary. Please note that these codelists and identifiers are NOT normative. For information communities wishing to formally identify and qualify, it is suggested that a specification extension be developed to meet those requirements.
C.1.2. Services
Annex D
(informative)
Common contact roles (Informative)
D.1. Overview
This annex describes common contact types when qualifying contact roles via a record contact’s roles property, in the absence of a formal controlled vocabulary. Please note that these codelists and identifiers are NOT normative. For information communities wishing to formally identify and qualify, it is suggested that a specification extension be developed to meet those requirements.
Annex E
(informative)
Crosswalk between STAC and OGC API — Records — Part 1 Core (Informative)
The document “Crosswalk between STAC and OGC API — Records” presents a comparison between this standard and the Spatial Temporal Asset Catalog, V 1.0.0.
Annex F
(informative)
Abbreviated terms
API
Application Programming Interface
CORS
Cross-Origin Resource Sharing
CRS
Coordinate Reference System
CSW
Catalog Service for the Web
HTTP
Hypertext Transfer Protocol
HTTPS
Hypertext Transfer Protocol Secure
IANA
Internet Assigned Numbers Authority
OGC
Open Geospatial Consortium
RFC
Request for Comment
TRS
Temporal Coordinate Reference System
URI
Uniform Resource Identifier
WCS
Web Coverage Service
WFS
Web Feature Service
WMS
Web Map Service
WPS
Web Processing Service
YAML
YAML Ain’t Markup Language or Yet Another Markup Language
Annex G
(informative)
Revision History
Table G.1
Date | Release | Contributors | Primary clauses modified | Description |
---|---|---|---|---|
2024-12-19 | 1.0.0 | P. Vretanos, T. Kralidis, A. Tzotsos | all | Review for 1.0.0. |
Bibliography
[1] Internet Assigned Numbers Authority (IANA). Link Relation Types [online, viewed 2024-12-09], https://www.iana.org/assignments/link-relations/link-relations.xml
[2] W3C: Data Catalog Vocabulary — Version 3, W3C Recommendation 22 August 2024, https://www.w3.org/TR/vocab-dcat/
[3] W3C: Data on the Web Best Practices, W3C Recommendation 31 January 2017, https://www.w3.org/TR/dwbp/
[4] W3C/OGC: Spatial Data on the Web Best Practices, W3C Working Group Note 28 September 2017, https://www.w3.org/TR/sdw-bp/
[5] Linux Foundation: SPDX License List, https://spdx.org/licenses/
[6] M. Pilgrim, M., Ringnalda, P.: Atom Feed Autodiscovery [online, viewed 2024-12-09], https://datatracker.ietf.org/doc/html/draft-ietf-atompub-autodiscovery
[7] RSS Advisory Board: RSS Autodiscovery [online, viewed 2024-12-09], https://www.rssboard.org/rss-autodiscovery
[8] W3C: Data Catalog Vocabulary — Version 2, W3C Recommendation 4 February 2020, https://www.w3.org/TR/vocab-dcat-2/