The Record Requirements Class defines the requirements for a catalogue record.
The atomic unit of information in a catalogue is a record which is defined in this clause.
It is expected that the information necessary to populate the fields/properties of a catalogue record is readily available for any resource that is being registered in the catalogue.
It is anticipated that the schema of a record will be extended to describe specific resource types (e.g. datasets, services, etc.) and also extended by information communities wishing to enrich the information content of the record to suit their needs.
Although this document does not mandate any particular encoding for a record, this document does define conformance classes for two encodings:
Other encoding are allowed but are not described in this document.
Table 1 and Table 2 define the set of properties, called the core queryables, that may be included in a record.
| Queryables | Requirement | Description | GeoJSON key |
|---|---|---|---|
recordId |
required |
A unique record identifier assigned by the server. |
id |
created |
optional |
The date this record was created in the server. |
properties.created |
updated |
optional |
The most recent date on which the record was changed. |
properties.updated |
conformsTo |
optional |
The extensions/conformance classes used in this record. |
conformsTo |
| Queryables | Requirement | Description | GeoJSON key |
|---|---|---|---|
geometry |
required |
A geometry associated with the resource that is used for discovery. Can be null if there is no associated geometry. |
geometry |
time |
required |
The temporal extent of the resource. Can be null if there is no associated temporal extent. |
time |
type |
required |
The nature or genre of the resource. |
properties.type |
title |
required |
A human-readable name given to the resource. |
properties.title |
description |
optional |
A free-text description of the resource. |
properties.description |
keywords |
optional |
A list of free-form keywords or tags associated with the resource. |
properties.keyword |
language |
optional |
The natural language used for textual values (i.e. titles, descriptions, etc) of a resource. |
properties.language |
externalIds |
optional |
One or more identifiers for the resource assigned by an external entity. |
properties.externalIds |
themes |
optional |
A knowledge organization system used to classify the resource. |
properties.themes |
formats |
optional |
A list of available distributions for the resource. |
properties.formats |
providers |
optional |
A list of providers qualified by their role in association to the record. |
properties.providers |
license |
optional |
A legal document under which the resource is made available. |
properties.license |
rights |
optional |
A statement that concerns all rights not addressed by the license such as a copyright statement. |
properties.rights |
links |
required |
A list of links for accessing the resource (e.g. download link, access link, etc.) in one of the supported distribution formats and/or links to other resources associated with this resource. Also, a list of links for navigating the API (e.g. prev, next, alternate, etc.). |
links |
In tables Table 1 and Table 2 this standard defines a core set of properties for describing discoverable resources. It is anticipated that this core set of properties will be extended to suite specific use cases or requirements. For example, a catalogue record may be extended to include additional properties from the GeoDCAT vocabulary. The fact that a catalogue record has been extended in this way can be advertised using the conformsTo member. The conformsTo member is a list of URIs that identify each extension used in a record. This specification does not define the specific URIs that are used to identify a specific extension; it simply provides a place where these identifiers can be listed.
In the case where all the records of a catalogue use the same set of extensions, and to prevent unnecessary duplication, there is also a conformsTo member at the collection or catalogue level that may be used to declare which extensions are used in all records of the catalogue. Extensions listed at the catalogue and record levels are cumulative.
A record allows for one properties.keywords and one to many properties.themes
properties. 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.
link:../examples/json/keywords-themes.json[role=include]The following recommendations provide clarification on where and how to use these properties in a record.
A record has one properties.type property. The value of this property should be a code, convenient for filtering records.
In addition, links to external resources describing the record type vocabulary used to populate the properties.type member are recommended, as described in Associations and Links.
A record has one properties.licenses property. The value of this property should be a code, convenient for filtering records.
In addition, links to external resources describing the licences used are recommended, as described in Associations and Links.
A record must contain a links section. This links section many contain navigation links and/or association links.
Navigation links are meant to encode relationships between catalogue entities (i.e. collections and records). Navigation links in the links section can include links to the collection (rel="collection) of which a record is a member, alternative representations (rel="alternate") of the record, and navigation links to previous (rel="prev") or next (rel="next") records in a chain of records. Links in the links section may also be used to organize records in a hierarchy (rel="root", rel="parent", rel="child).
Links in the links section may also encode canoncial 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 catalogue. 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 indivdually 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 catalogue 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 in order 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. The OGC Web Map Service (WMS) 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.
|
Note
|
This specification does not define any specific link relations that should be used for links in the links section. Such relationships are typically domain specific and so it is left to communities of interest to standardize the links that relations should use.
|
The following provides an example of using association links for related resources of a record, as both traditional link relations as well as API resources via URI templates.
link:../examples/json/associations-simple-and-uri-template.json[role=include]The links in a record could be (in this example represented as link headers):
Link: <http://data.example.org/collections/my_catalogue/items/record_123.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/my_catalogue/items/record_123.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/my_catalogue.json>; rel="collection"; type="application/json"
Link: <http://data.example.org/collections/my_catalogue.html>; rel="collection"; type="text/html"OGC API - Records 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 catalogue 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 for the binding link would only allow retrieval of the entire coverage. Using a templated link, however, would allow the context of the catalogue query (i.e. the bbox) to be passed to down to the binding link. The templated link with all substitution values resolved would thus retrieve the subset of the coverage that corresponds to the spatial contraint 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 such as WMS or WFS is not sufficient to access resources offered by those services. Additional information in the form of request parameters and values are required in order to have a complete link to a resources. A templated link with variables can provide this additional context.
This specification extends the schema for a link to include substitution variables who values are filled in at runtime prior to resolving the link.
The link schema is extended with the addition of two properties named templated and variables. The templated property is a boolean that is used to indicate the the URL of the link (i.e. href) is a template and contains substitution variables. The variables property uses JSON-Schema fragments to define the characteristics of each substitution variable referenced in the templated link URL.
link:../examples/json/templated-link.json[role=include]A record contains information, encoded in the links section, for accessing one or more resources described by the record. Since a resource may have multiple representations there may be multiple links pointing to each represention of a resource. Furthermore, representations of a resource may be created and updated at different times. In order to capture this life cycle information of resource representations, the 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.
Two kinds of languages are handled in this specification. The language associated with the resource and the language associated with the record that describes the resource in the catalogue.
The language associated with the resource is specified using the language property of a catalogue record. This indicates the language associated with the resource that the record described.
The language for the record itself is negotiated between a client and the servers using the Accept-Language header of HTTP. Records in a response document can only be presented in a single negotiated language. 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.