OGC API - Records - Part 1: Core

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:

To facilitate access to records in a catalog, the OGC API - Feature - Part 1: Core Standard has been:

Table 5 summarizes the access paths and relation types defined in this Standard.

Where:

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.

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:

The Records API Standard extends these core search capabilities to include:

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.

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.

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.

Table 8 and Table 9 define the set of properties, called the core properties, that may be included in a record.

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.

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.

In order to facilitate the ability to discover resources of a particular type(s), this Standard makes the following recommendations:

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.

In order to facilitate the discovery of resources utilizing keyword or free-text searches, this Standard makes the following recommendation:

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.

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.

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.

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.

A record may have one license property. If present, the value of this property should be a code, convenient for filtering records.

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 (eotion: 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).

Links in the links section may also encode canonical URIs for record properties such as type and license.

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.

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.

The following provides an example of using association links for related resources of a record, as both traditional links as well as link templates.

.Example of links and link templates in HTTP headers

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.



 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. 





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.

This Standard defines requirements classes for JSON and HTML encoding of a record. See Encodings.

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.

Table 11 defines the set of properties that may be used to describe a catalog.

In Catalog schema 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.

A catalog can include references to records, other catalogs or both. A catalog can also contain an array of catalog records.

In order to facilitate the discovery of resources utilizing keyword or free-text searches, this Standard makes the following recommendation:

See Keywords and Themes.

See Language handling.

See Templated links with variables.

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%3A//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:

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.

This Standard defines requirements for JSON and HTML encoding of a catalog. See Encodings.

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.

The core requirements for an API that enables searching a catalog are defined by the OGC API - Features - Part 1: Core Standard.

While this Standard does not specify any mandatory response encoding, support for the following encodings is recommended.

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).

The Sorting Requirements Class defines the requirements for specifying how records in a response should be ordered for presentation.

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.

To support clients, providing additional detail about the meaning of the sortables is recommended:

In an OpenAPI 3.0 document, the Sortables resource has the following schema:

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.

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 sever 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.

The following examples assume the following set of sortables retrieved from the servers /collection/{catalogId}/sortables endpoint:

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.

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 rel="http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog" link in the landing page and then, using that catalog, search for resources offered by the site.

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 sofware 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.

Catalog information that is only accessible in formats primarily intended to be read by machines, such as JSON or XML, have two issues:

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.

Servers conforming to this requirements class define their API using an OpenAPI Document.

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.

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.

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.

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.

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.