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:

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.

Table 5 — Records API Paths

Where:

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:

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.

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

7.2.1.  Overview

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

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.

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.

7.2.4.  Type

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.

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:

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

"time" : {
    "date": "1969-07-20"
}

"time" : {
    "timestamp": "1969-07-20T20:17:40Z"
}

"time" : {
    "interval": [
        "1969-07-16",
        "1969-07-24"
    ]
}

"time" : {
    "interval": [
        "1969-07-16T05:32:00Z",
        "1969-07-24T16:50:35Z"
    ]
}

"time" : {
    "interval": [
        "2014-04-24T10:50:18Z",
        ".."
    ]
}

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.

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

7.2.10.  Language handling

7.2.11.  Contacts

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.

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

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

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.

---
allOf:
  - $ref: 'linkBase.yaml'
  - type: object
    required:
      - uriTemplate
    properties: 
      uriTemplate:
        type: string
        description: |-
          Supplies a resolvable URI to a remote resource
          (or resource fragment).
      varBase:
        type: string
        description: |-
          The base URI to which the variable name can be
          appended to retrieve the definition of the
          variable as a JSON Schema fragment.
        format: uri-reference
      variables:
        type: object
        description: |-
          This object contains one key per substitution
          variable in the templated URL.  Each key defines
          the schema of one substitution variable using a
          JSON Schema fragment and can thus include things
          like the data type of the variable, enumerations,
          minimum values, maximum values, etc.

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

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.

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:

7.3.6.  Keywords and Themes

See Keywords and Themes.

7.3.7.  Language handling

See Language handling.

7.3.8.  Contacts

7.3.9.  License

7.3.10.  Records and RecordsArrayName

"recordsArrayName": "collections"
"collections": [
  {... record describing a collection ... },
  {... record describing a collection ... },
  .
  .
  .
  ]

"recordsArrayName": "processes"
"processes": [
  { ... record describing a process ... },
  { ... record describing a process ... },
  .
  .
  .
  ]

7.3.11.  Other catalogs

7.3.12.  Links

7.3.13.  Templated links with variables

See Templated links with variables.

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.1.  Overview

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

7.4.2.  Query parameters

---
name: q
in: query
description: |-
  The optional q parameter supports keyword searching.  Only records
  whose text fields contain one or more of the specified search terms
  are selected.  The specific set of text keys/fields/properties of a
  record to which the q operator is applied is up to the discretion
  of the server.   Implementations should, however, apply the q
  operator to the title, description and keywords keys/fields/properties.
required: false
schema:
  type: array
  items:
    type: string
explode: false
style: form

q=ocean,climate%20%09change,desalination

(anytext CONTAINS 'ocean') OR
(anytext CONTAINS 'climate\s+change') OR
(anytext CONTAINS 'desalination')`

---
name: type
in: query
description: |-
  The optional type parameter allows a specific list of records, identified
  by their resource type, to be fetched from a catalog.  Only records whose
  resource type matches one of the values listed for this parameter shall
  appear in the response.
required: false
schema:
  type: array
  items:
    type: string
explode: false
style: form

---
name: ids
in: query
description: |-
  The optional ids parameter allows a specific list of records, identified
  by their identifiers, to be fetched from a catalog.  Only records whose
  identifier matches one of the values listed for this parameter shall appear
  in the response.
required: false
schema:
  type: array
  items:
    type: string
explode: false
style: form

---
name: externalIds
in: query
description: |-
  The optional externalIds parameter allows a specific list of records,
  identified by their external identifiers, to be fetched from a catalog.
  Only records where one of their associated external identifiers equals
  one of the values listed for this parameter shall appear in the response.
required: false
schema:
  type: array
  items:
    type: string
    pattern: ([^:]+:)?[^:]+
explode: false
style: form

name: <name of property>
in: query
required: false
style: form
explode: false

name: <name of property>
in: query
required: false
schema:
  type: array
explode: false

7.5.1.  Overview

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

7.5.2.  Encodings

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

7.5.3.  Record collection response

---
allOf:
  - $ref: 'catalog.yaml'
  - type: object
    properties:
      itemType:
        description: |-
          For a collection of records, the itemType is
          fixed to "record".
        type: string
        enum:
          - record

7.5.4.  Record collections response

7.5.5.  Records access

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}