I. Abstract

The OGC API – Environmental Data Retrieval (EDR) Part 1: Core Standard offers a flexible framework for geospatial data access. However, this flexibility can lead to implementation variability, making it difficult for clients to interact with different services consistently. To address this, communities of practice use API-EDR Service Profiles to formalize domain-specific constraints that ensure predictable service behavior and simplify client integration.

The OGC API-EDR Part 3: Service Profile Standard establishes a consistent approach for specifying these profiles. Each profile serves as a normative “contract” for a specific domain, consisting of an OGC ModSpec-compliant document containing:

Requirements: Mandatory rules subject to formal testing and conformance validation.
Recommendations and Permissions: Guidelines and best practices that are not subject to testing.

The primary purpose of a Service Profile is to eliminate the “validation gap” by providing a machine-readable set of rules for service discovery and interaction. By standardizing collection structures and parameters, profiles allow clients to understand exactly what a specific implementation provides without manual intervention. To support this, each profile includes a dedicated OpenAPI definition that provides a precise, machine-readable description of the operations and responses required by that profile.

Service profiles utilize a tiered architecture to maintain a clear distinction between standard rules and deployed instances:

Core OpenAPI Definition: The base framework provided by Part 1.
Service Profile OpenAPI Definition: A specialized subset describing only the requirements of the profile.
Implementation OpenAPI Definition: The full description of a deployed service, which may incorporate multiple profiles alongside vendor-specific capabilities.

A Service Profile is not required to constrain all aspects of the Core Standard; profiles may selectively address only those elements relevant to their specific domain requirements.

Implementations shall advertise their supported service profiles through a conformance declaration. This enables clients to automatically discover available functionality while allowing services to evolve and extend beyond the scope of individual profiles without compromising conformance.

II. Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, ModSpec, API, OpenAPI, HTML, Profile

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

No security considerations have been made for this Standard.

V. Submitting Organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

UK Met Office
Heazeltech
US NWS

VI. Submitters

All questions regarding this submission should be directed to the editor or the submitters:

Name	Affiliation
Mark Burgoyne	Met Office
Charles Heazel	Heazel Tech
Chris Little	Met Office

VII. Contributors

Additional contributors to this Standard include the following:

Individual name(s), Organization

Shane Mill, National Weather Service

Håvard Futsæter, Norwegian Meteorological Institute

Mikko Rauhala, Finnish Meteorological Institute

Guy Collins, Met Office

1. Scope

This Standard specifies the methodology for defining Service Profiles for the OGC API – Environmental Data Retrieval (EDR) Part 1: Core. It is limited to the definition of restrictive profiles, which specialize the existing Core Standard to meet domain-specific needs.

Service Profiles may selectively constrain specific aspects of the Core Standard based on domain needs. A profile is not required to address all possible constraints defined in this Standard.

This Standard does not define profiles that extend the EDR API with new functionality that falls outside the Core Standard’s specification. While a service profile may impose requirements additional to those in the Core, all such requirements must remain compliant with the underlying OGC API — EDR Part 1: Core Standard.

The normative restrictions in a Service Profile are defined as Requirements, which utilize JSON Schema fragments to enable formal, machine-readable conformance testing. While developed for EDR, the profiling mechanisms and requirements defined herein are intended to be applicable to other OGC API Standards and implementations.

2. Conformance

Conformance to the OGC API-EDR-Part 3 Standard (this document) by a profile of the OGC API — Environmental Data Retrieval Standard can be tested by inspection. The test suite is provided in Annex A.

This Standard contains normative language and thus places requirements on conformance, or mechanism for adoption, of candidate standards to which this Standard applies. In particular:

OGC API-EDR Requirements Class: Core specifies the core requirements which shall be met by all standards claiming conformance to this Standard.

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.

ISO: ISO 19106, Geographic information — Profiles. International Organization for Standardization, Geneva https://www.iso.org/standard/26011.html.

Mark Burgoyne, Dave Blodgett, Chuck Heazel, Chris Little: OGC 19-086r4, OGC API — Environmental Data Retrieval Standard. Open Geospatial Consortium (2021). http://www.opengis.net/doc/IS/ogcapi-edr-1/1.0.0.

https://docs.ogc.org/is/17-069r4/17-069r4.html, OGC API — Features — Part 1: Core, Open Geospatial Consortium (2022).

https://docs.ogc.org/is/19-072/19-072.html, OGC API - Common - Part 1: Core, Open Geospatial Consortium (2023).

http://docs.ogc.org/DRAFTS/20-024.html, OGC API - Common - Part 2: Geospatial Data (Draft), Open Geospatial Consortium

Policy SWG: OGC 08-131r3, The Specification Model — Standard for Modular specifications. Open Geospatial Consortium (2009). https://docs.ogc.org/pol/08-131r3/08-131r3.pdf.

OpenAPI Initiative (OAI). OpenAPI Specification 3.0 [online]. 2024 [viewed 2025-01-03]. The latest patch version at the time of publication of this standard was 3.0.4, available at https://spec.openapis.org/oas/v3.0.4

OpenAPI Initiative (OAI). OpenAPI Specification 3.1 [online]. 2024 [viewed 2025-01-03]. The latest patch version at the time of publication of this standard was 3.1.1, available at https://spec.openapis.org/oas/v3.1.1

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.

4.1. Collection

Body of resources that belong or are used together. An aggregate, set, or group of related resources.

[SOURCE: OGC 20-024]

4.2. Profile

A named set of requirements and constraints that specialize one or more base standards for a specific community or domain of use.

[SOURCE: ISO 19106:2004 Geographic information — Profiles]

4.3. Service Profile

A Profile of the OGC API – Environmental Data Retrieval (EDR) Part 1: Core Standard that defines a constrained and well-specified set of requirements for a specific domain or community of use.

4.4. Conformance Module; Conformance Test Module

A set of related conformance classes and their associated components.

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.

[SOURCE: OGC 08-131r5]

4.5. Conformance Class; Conformance Test Class

A set of conformance tests that must be passed to receive a single certificate of conformance.

Note 1 to entry: When no ambiguity is possible, the word test may be left out, so conformance test class maybe called a conformance class.

[SOURCE: OGC 08-131r5]

4.6. Conformance Test

A test, abstract or real, of one or more requirements contained within a standard, or set of standards.

[SOURCE: OGC 08-131r5]

4.7. Requirement

Expression in the content of a standard conveying criteria to be fulfilled if compliance with the standard is to be claimed and from which no deviation is permitted.

[SOURCE: OGC 08-131r5]

4.8. Requirements Class

An aggregate of requirements with a single standardization target type that must all be satisfied to pass a conformance test Class.

[SOURCE: OGC 08-131r5]

4.9. Requirements Module

A set of related requirements classes and their associated components.

[SOURCE: OGC 08-131r5]

4.10. Standardization Goal

A concise statement of the problem that the standard helps address and the strategy envisioned for achieving a solution. This strategy typically identifies real-world entities that need to be modified or constrained. At the abstract level, those entities are the Standardization Target Types.

[SOURCE: OGC 08-131r5]

4.11. Standardization Target

Entity to which some requirements of a standard apply.

Note 1 to entry: The standardization target is the entity which may receive a certificate of conformance for a requirements class.

[SOURCE: OGC 08-131r5]

4.12. Standardization Target Type

Type of entity or set of entities to which the requirement of a standard apply.

Note 1 to entry: For example, the standardization target type for The OGC API – Features Standard are Web APIs. The standardization target type for the CDB Standard is “datastore”. It is important to understand that a standard’s root standardization target type can have sub-types, and that there can be a hierarchy of target types. For example, a Web API can have sub types of client, server, security, and so forth. As such, each requirements class can have a standardization target type that is a sub-type of the root.

[SOURCE: OGC 08-131r5]

5. Conventions

This sections provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML 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/doc/spec/ogcapi-edr-3/1.0

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.1.1. Shortcuts

In the interest of readability, the following terms will be used as shorthand for more complex text:

Profile: A Profile is a standard or specification which restricts and/or extends an existing standard. This standard defines the rules for creating a profile of the OGC API — Environmental Data Retrieval Standard. The term “Profile” will be used in this document as shorthand for “profile of the OGC API — Environmental Data Retrieval Standard”.
OGC API-EDR: The term OGC API-EDR will be used in this document as shorthand for the term “OGC API — Environmental Data Retrieval Standard”

6. Context

6.1. Standardization Goal

The goal of this Standard is to ensure interoperability between implementations of the OGC API — Environmental Data Retrieval Standard (OGC API-EDR).

The OGC API-EDR Standard does not try to address every possible application domain. Rather, it provides a foundation which can be tailored for a specific domain. The result of this tailoring is a domain specific “profile” of the EDR API Standard.

A significant risk to this approach is that, in the act of profiling, interoperability will be compromised. This risk can be mitigated by establishing rules for how the OGC API-EDR Standard can be profiled. The goal of this Standard is to define a set of rules sufficient to ensure interoperability while retaining the adaptability needed to support domain-specific requirements.

6.2. Standardization Target Type

The Standardization Target Type for this Standard is the Service Profile definition. This Standard establishes the requirements for creating, documenting, and validating these profiles.

It is important to understand the following distinctions:

A Standard for Standards: This document provides the rules for writing profile specifications; it does not define the requirements for the EDR API software implementation itself.
ModSpec Alignment: This Standard is a profile of OGC ModSpec Model — Part 1: Core — A Standard for Designing and Writing Modular Standards (ModSpec), ensuring that all resulting Service Profiles follow a consistent modular structure.
Implementation: An “implementation” of this Standard is a completed Service Profile document (e.g., a MetOcean EDR Profile).
Foundational Model: The profiling methodology is based on ISO 19106:2004 Geographic information — Profiles.

6.3. Service Profiles — Context — A Graphical View

Figure 1

7. Requirements Class Core

Requirements class 1: Requirements Class ‘Core’
Identifier	`http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Conformance class	Conformance class A.1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/conf/conf-class-core`
Target-type	OGC API-EDR Profile Standard
Normative statements	Requirement 1: `/req/core/modspec` Requirement 1-26: `/req/core/instanceid` Requirement 2: `/req/core/edr-conformant` Requirement 4: `/req/core/root` Requirement 5: `/req/core/root-description` Requirement 7: `/req/core/root-keywords` Requirement 8: `/req/core/root-provider` Requirement 9: `/req/core/root-contact` Requirement 10: `/req/core/root-links` Requirement 11: `/req/core/publishing` Requirement 12: `/req/core/openapi` Requirement 14: `/req/core/api` Requirement 15: `/req/core/requirements-set` Requirement 16: `/req/core/collectionid` Requirement 17: `/req/core/extent` Requirement 18: `/req/core/extent-spatial` Requirement 19: `/req/core/extent-temporal` Requirement 20: `/req/core/extent-vertical` Requirement 21: `/req/core/extent-custom` Requirement 22: `/req/core/parameter-names` Requirement 23: `/req/core/data-query` Requirement 24: `/req/core/output-format` Requirement 25: `/req/core/data-query-position` Requirement 26: `/req/core/data-query-radius` Requirement 27: `/req/core/data-query-area` Requirement 28: `/req/core/data-query-cube` Requirement 29: `/req/core/data-query-trajectory` Requirement 30: `/req/core/data-query-corridor` Requirement 31: `/req/core/data-query-locations` Requirement 32: `/req/core/data-query-instances` Requirement 33: `/req/core/paging-support` Requirement 34: `/req/core/status-codes` Requirement 35: `/req/core/links` Requirement 36: `/req/core/asynchronous` Requirement 37: `/req/core/pubsub`

7.1. Profiling Requirements

The Profile is conformant with the ModSpec

Requirement 1
Identifier	`/req/core/modspec`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A profile of the OGC API — Environmental Data Retrieval Standard SHALL be conformant to the OGC Modular Specification.

NOTE 1: The OGC Modular Specification (ModSpec) defines the standard structure for all OGC specifications. It requires that all normative rules be expressed as identifiable Requirements and Recommendations, each of which must be associated with a corresponding Abstract Test Case to ensure the profile is verifiable.

Implementations of the Profile are conformant with OGC API-EDR Part 1: Core

Requirement 2
Identifier	`/req/core/edr-conformant`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A profile of the OGC API — Environmental Data Retrieval Standard SHALL require that a conformant implementation (standardization target) of that profile demonstrate conformance to the OGC API — Environmental Data Retrieval Standard.

Profiles often focus on restricting the values of Path parameters. A Profile should clearly specify the requirements for these restrictions

A Profile must be interoperable with other OGC API-EDR data providers. Any valid OGC API-EDR document should be valid under the profile. That means:

If a data element is valid for OGC API-EDR, then it should not be prohibited under the profile
Custom query elements defined by a Service Profile SHALL be optional, not mandatory, for data queries.
It is valid for a profile to prohibit the production and population of OGC API-EDR optional elements by data providers within the profile’s domain.

A resource constrained by a Service Profile SHOULD include a link with a link relation type of profile that references the Service Profile defining the rules implemented by the response.

NOTE 2: Resources defined by Service Profiles can include /root, /collections, and /instances.

7.2. Platform Resources

OGC API - Common Standard defines a set of common capabilities which are applicable to any OGC Web API Standard and implementation instance. Those capabilities provide the platform upon which resource-specific APIs can be built. This section describes those capabilities and any modifications needed to better support spatio-temporal data resources.

Table 1 — Platform Resource Paths

PATH TEMPLATE	METHOD	RESOURCE
{root}/	GET	Landing page
{root}/{api}	GET	API Description (optional)
{root}/conformance	GET	Conformance Classes

Where:

{root} = Base URI for the API server
{api} = an identifier for an optional description of the API

7.2.1. API Landing Page

Path = {root}/

Dependencies

OGC API — Common — Part 1: Core
OGC API — Environmental Data Retrieval Standard

The landing page provides links that support exploration of the resources offered via the API. The most important component of a landing page is a list of links. The Landing Page resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to this definition. The normative JSON Schema for an EDR Landing Page is defined in the LandingPage.yaml document.

Profiles of the OGC API – Environmental Data Retrieval Standard are able to provide a richer description of the API by mandating optional attributes. The requirements below define additional content rules that service profiles can enforce.

Permission 1
Identifier	`/per/core/multiple-collection-definition`
Statement	A Profile MAY impose requirements on the complete OGC API service implementation or on a defined subset of the functionality it provides.

Requirement 3
Identifier	`/rec/core/root-service-profile`
A	The root SHALL clearly indicate when service profile defines rules that apply to its contents.
B	The root SHOULD provide a link to its service profile definition with a link relation type of `profile`.

Requirement 4
Identifier	`/req/core/root`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	While the OGC API-EDR Landing Page schema requires only the links property, a Profile of the OGC API — Environmental Data Retrieval Standard SHALL require the following additional properties and content:
A	The `title` property SHALL be required and populated
B	The `links` property SHALL define the links that SHALL be included in the Root response.
C	Each `link` defined in the `links` property SHALL be populated with href and rel properties.

Recommendation 1
Identifier	`/rec/core/root`
Statement	While the OGC API-EDR Landing Page schema requires only the links property, a Profile of the OGC API – Environmental Data Retrieval Standard SHOULD mandate the following additional properties.
A	The `description` property SHOULD be required
B	The `keywords` property SHOULD be required
C	The `provider` property SHOULD be required and populated with the `name` and `url` properties
D	The `contact` property SHOULD be required and populated with the with the `email` properties

Requirement 5
Identifier	`/req/core/root-description`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `description` property, that property SHALL be populated.

Requirement 6
Identifier	`/req/core/root-attribution`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `attribution` property, that property SHALL be populated.

Requirement 7
Identifier	`/req/core/root-keywords`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `keywords` property, that property SHALL be populated with at least one keyword entry.

Requirement 8
Identifier	`/req/core/root-provider`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `provider` property.
A	A `provider` property SHALL be populated with a `name` property.

Permission 2
Identifier	`/per/core/provider-url-definition`
Statement	A `provider` property MAY be populated with a `url` property.

Requirement 9
Identifier	`/req/core/root-contact`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `contact` property,
A	A `contact` property SHALL be populated with the `email` property.

Permission 3
Identifier	`/per/core/contact-name-definition`
Statement	A `contact` property MAY be populated with the `name` property.

Permission 4
Identifier	`/per/core/contact-url-definition`
Statement	A `contact` property MAY be populated with the `url` property.

Requirement 10
Identifier	`/req/core/root-links`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that when an EDR Landing Page includes the `links` property:
A	The `links` property SHALL define the links that SHALL be included in the Root response
B	The `links` property SHALL be populated with `href` and `rel` properties

Permission 5
Identifier	`/per/core/links-type-href-length-definition`
Statement	The `links` property MAY be populated with type, hreflang and length properties

Recommendation 2
Identifier	`/rec/core/root-links`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHOULD require that when an EDR Landing Page includes the `links` property, the title property of each link SHALL be populated.

7.2.2. API Definition

Path = {root}/{api}

Dependencies

OGC API — Common — Part 1: Core
OGC API — Environmental Data Retrieval Standard

Every OGC API is required to provide a definition document that describes the capabilities of that API. This definition document can be used by developers to understand the API, by software clients to connect to the server, or by development tools to support the implementation of servers and clients. The API Definition resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to that definition.

Each service profiles of the OGC API – Environmental Data Retrieval standard must provide an OpenAPI 3.1 document when the profile includes requirements that can be expressed using the OpenAPI specification. A service profile document is a subset of the API definition produced by the OGC API-EDR implementation and reflects the additional requirements specified by the profile.

NOTE: At this time only OpenAPI 3.0 and OpenAPI 3.1 documents are supported by OGC Web API Standards.

Requirement 11
Identifier	`/req/core/publishing`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	An EDR service profile SHALL be published as an OpenAPI JSON document when it contains requirements that can be encoded in the OpenAPI specification.
A	The OpenAPI compatible rules described in the requirements SHALL be encoded using the OpenAPI 3.1 specification.
B	The OpenAPI compatible requirement rules SHALL be encoded in either the OpenAPI Path Item or in the Response object schema sections of the document.

Requirement 12
Identifier	`/req/core/openapi`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A profile OpenAPI document SHALL describe the profile EDR API as follows:
A	The servers attributes of the OpenAPI root object SHALL be blank (the profile is not linked to specific implementations)
B	The Extent requirement rules SHALL be encoded in the JSON schema defined in the 200 responses for the /collections and /collections/{collectionId} Paths object
C	data_query requirement rules SHALL be encoded in the JSON schema defined in the 200 responses for the /collections and /collections/{collectionId} Paths object
D	The conformance classes SHALL be encoded in the JSON schema defined in the 200 responses for the /conformance Paths object.
E	The `data_query` types SHALL be encoded as Paths objects in the OpenAPI document, where appropriate the `output_format`, `default_output_format`, `crs`, `within_units`, `width-units`, `height-units` and `limit` (paging) requirements SHALL be encoded in the child Parameter objects of the Paths object.
F	The output_format requirement rules SHALL be encoded in the 200 responses of the data_query type Paths objects
G	The `parameter_names` requirements SHALL be encoded in the JSON schema defined in the 200 responses for the /collections and /collections/{collectionId} Paths object.
H	Where a `Collection` has `Instances`, `parameter_names` requirements SHALL be encoded in the JSON schema defined in the 200 responses for the /collections/{collectionId}/instances and /collections/{collectionId}/instances/{instanceId} Paths object.
I	An EDR API SHALL advertise the location of the profile OpenAPI document it complies with in the `links` section of the API root with a link relation value of `profile`

7.2.3. Declaration of Conformance Classes

Path = {root}/conformance

Dependencies

OGC API — Common — Part 1: Core
OGC API — Environmental Data Retrieval Standard

To support “generic” clients that want to access implementations of multiple OGC API Standards and extensions — and not “just” a specific API server, the API has to declare the conformance classes it claims to have implemented. The Conformance Classes resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to this definition.

Profiles of the OGC API — Environmental Data Retrieval Standard have additional requirements governing which Conformance Classes and identifiers must be included in this resource.

Requirement 13
Identifier	`/req/core/conformance-classes`
Statement	An OGC API-EDR implementation SHALL advertise, in its list of conformance classes all service profiles that it supports.

7.2.4. OpenAPI version support

Requirement 14
Identifier	`/req/core/api`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Profile of the OGC API — Environmental Data Retrieval Standard SHALL specify the versions of OpenAPI that an implementation SHALL support.

NOTE 1: OpenAPI 3.0 and OpenAPI 3.1 are two distinct Conformance Classes in the OGC API-EDR Standard. This requirement can be addressed in a Profile by including the appropriate conformance classes at {root}/conformance.

NOTE 2: Profile developers should get guidance from the OGC Naming Authority on valid URIs for Profiles.

7.3. Spatio-temporal and Information Resources

Table 2 — Spatio-temporal and Information Resource Paths

PATH TEMPLATE	METHOD	RESOURCE
{root}/collections	GET	Metadata describing the Collections of data available from this API.
{root}/collections/{collectionId}	GET	Metadata describing the `Collection` of data which has the unique identifier{collectionId}

Where:

{root} = Base URI for the API server
{collectionId} = an identifier for a specific Collection of data

7.3.1. Collections

OGC API implementations typically organize their geospatial resources into collections. Information about those Collections is accessed through the /collections path and the http://www.opengis.net/def/rel/ogc/1.0/data link relation.

Path = {root}/collections

Dependencies

OGC API — Common — Part 2: Geospatial Data
OGC API — Environmental Data Retrieval Standard

The Collections resource is initially defined in the Collections conformance class of the OGC API — Common — Part 2 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to that definition.

An implementation of the OGC API-EDR may support multiple collections. Additional requirements address how the Service Profile should document requirements at the per-collection level as well as on the landing page (where appropriate)

NOTE: A Service profile can apply to multiple Collections and an OGC API EDR implementation can support multiple Service Profiles.

Requirement 15
Identifier	`/req/core/requirements-set`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
A	The collection SHALL clearly identify the service profile that applies.
B	The collection SHOULD provide a link to the service profile definition with a link relation type of `profile`.
C	The service profile SHALL consist of a set of requirements for a `Collection` and (if the `Collection` supports `Instances`) the `Instances` of the `Collection`. For each of the attributes listed, if it is in the `Collection` (or instance), there SHALL be a requirement to define it.

Permission 6
Identifier	`/per/core/multiple-service-profile-definition`
Statement	An OGC API EDR implementation MAY include multiple service profiles.

7.3.2. Collection Description

Each resource Collection is described by a set of metadata. That metadata can be accessed directly using the /collections/{collectionId} path and as an entry in the Collections property of the /collections response.

Path:

{root}/collections (returns metadata for every Collection)
{root}/collections/{collectionId} (returns metadata for the specified Collection)

Dependencies

OGC API — Common — Part 2: Geospatial Data
OGC API — Environmental Data Retrieval Standard

7.3.2.1. Collection ID parameter restrictions

Requirement 16
Identifier	`/req/core/collectionid`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts the valid values of the `collectionId` parameter, then:
A	The Service Profile SHALL specify the rules that the `collectionId` values must follow.
B	Those rules SHALL include a brief description explaining how the `collectionId` is generated.
C	Those rules SHALL be specified using either: identifier string or Regular expression defining valid string patterns.

7.3.2.2. Extent property restrictions

The Collection metadata includes an Extent property which defines a spatio-temporal envelope that encompasses the geospatial data in the Collection.

Requirement 17
Identifier	`/req/core/extent`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Service Profile of the OGC API — Environmental Data Retrieval Standard SHALL define a requirement defining a `bbox` which specifies the minimum spatial bounds that SHALL be supported

Recommendation 3
Identifier	`/rec/core/extent`
Statement	A requirement SHOULD be defined specifying the rules for defining the `Collection` extent.

Requirement 18
Identifier	`/req/core/extent-spatial`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
NOTE	Regular expressions could be used to restrict reference system definitions to WKT2 or EPSG values
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard supports Extents with spatial dimensions, then:
A	The Service Profile SHALL specify the rules for the spatial Coordinate Reference System (CRS).
B	Those rules SHALL be specified using either: Enumerated list of valid CRS values Regular expression defining valid CRS string patterns.

Permission 7
Identifier	`/per/core/extent-spatial`
Statement	Regular expressions MAY be used to restrict reference system definitions to WKT2 or EPSG values

Requirement 19
Identifier	`/req/core/extent-temporal`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard supports Extents with a temporal dimension, then:
A	The Service Profile SHALL specify the rules for expressing the Temporal Reference System (TRS).
B	Those rules SHALL be specified using either: Enumerated list of valid TRS values Regular expression defining valid TRS string patterns.

Recommendation 4
Identifier	`/rec/core/extent-temporal`
Statement	A requirement SHOULD be defined specifying the minimum temporal bounds that SHALL be supported

Requirement 20
Identifier	`/req/core/extent-vertical`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard supports Extents with a vertical dimension, then:
A	The Service Profile SHALL specify the rules for expressing the Vertical Reference System (VRS).
B	Those rules SHALL be specified using either: Enumerated list of valid VRS values Regular expression defining valid VRS string patterns.

Recommendation 5
Identifier	`/rec/core/extent-vertical`
Statement	A requirement SHOULD be defined specifying the minimum vertical bounds that SHALL be supported

Requirement 21
Identifier	`/req/core/extent-custom`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard supports Extents with a custom dimension, then:
A	The Service Profile SHALL specify the rules for expressing the custom dimension.
B	Those rules SHALL be specified using either: A custom dimension id A custom dimension reference value A custom interval value An enumerated list of valid custom dimension values

Recommendation 6
Identifier	`/rec/core/extent-custom`
Statement	A requirement SHOULD be defined specifying the minimum bounds of custom extents that SHALL be supported

7.3.2.3. Parameter metadata

Requirement 22
Identifier	`/req/core/parameter-names`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile restricts the allowed values or definitions of `parameter_names`, then:
A	The Service Profile SHALL define requirements that explicitly list the permitted `parameter_names`.
B	Each parameter definition SHALL include the following properties as defined in the OGC API-EDR Part 1 schema: `name` (the key within the `parameter_names` object), `unit`, `observedProperty`, and `measurementType` (including `method` and `duration` where applicable).

"parameter_names": {
  "t2m": {
    "type": "Parameter",
    "description": "Air temperature at 2m",
    "unit": {
      "label": "Kelvin",
      "symbol": {
        "value": "K",
        "type": "https://qudt.org/vocab/unit/K"
      }
    },
    "observedProperty": {
      "id": "http://codes.wmo.int/grib2/codeflag/4.2/0-0-0",
      "label": "Air temperature at 2m"
    }
  },
  "ff": {
    "type": "Parameter",
    "description": "10m Wind Speed",
    "unit": {
      "label": "m/s",
      "symbol": {
        "value": "ms-1",
        "type": "https://qudt.org/vocab/unit/M/s"
      }
    },
    "observedProperty": {
      "id": "http://codes.wmo.int/grib2/codeflag/4.2/0-2-1",
      "label": "10m Wind Speed"
    },
    "measurementType": {
      "method": "mean",
      "duration": "-PT10M"
    }}}

Listing 1 — Example of a constrained parameter_names definition in a Service Profile

Permission 8
Identifier	`/per/core/parameter-names-schema`
Statement	An OGC API EDR implementation MAY apply schema constraints to the parameter_names objects without explicity enumerating the parameters. Explicit enumeration of parameters is only required when a service profile mandates the presence of specific named parameters.

7.4. Query Resources

Table 3 — Query Resource Paths

PATH TEMPLATE	METHOD	RESOURCE
{root}/collections/{collectionId}/{queryType}	GET, POST(Optional)	Retrieve data according to the query pattern from a `Collection` with the unique identifier {collectionId}
{root}/collections/{collectionId}/instances	GET	Retrieve metadata about Instances of a `Collection`
{root}/collections/{collectionId}/instances/{instanceId}	GET	Retrieve metadata from a specific `Instance` of a `Collection` with the unique identifiers{collectionId} and {instanceId}
{root}/collections/{collectionId}/instances/{instanceId}/{queryType}	GET, POST(Optional)	Retrieve data according to the query pattern from a specific `Instance` of a `Collection` with the unique identifiers{collectionId} and {instanceId}

Where:

{root} = Base URI for the API server
{collectionId} = an identifier for a specific Collection of data
{instanceId} = an identifier for a specific version or Instance of a Collection of data
{queryType} = an identifier for a specific query pattern to retrieve data from a specific Collection of data

Path = {root}/collections/{collectionId}/{queryType}

Dependencies: OGC API — Environmental Data Retrieval Standard Part 1: Core

Requirement 23
Identifier	`/req/core/data-query`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Service Profile of the OGC API — Environmental Data Retrieval Standard SHALL require definition of the supported data queries.
A	The data_queries definitions SHALL specify which data queries a collection supports. This can be defined as follows: Enumerated list of query types
B	Each data_query type listed SHALL have a requirement definition.

7.4.1. Parameters

The following parameters are supported by all OGC API-EDR queries.

7.4.1.1. Output Format parameter

Also known as the -f parameter.

Data format for the output data (available options are listed in the Collections response).

Requirement 24
Identifier	`/req/core/output-format`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	For every output_format specified in any of the data_query enumerated lists, there SHALL be a requirement which defines the schema or structure of the data (depending on the format).

Recommendation 7
Identifier	`/rec/core/output-format`
Statement	The recommended definition approaches are as follows: JSON – Link to a JSON Schema definition XML – Link to a XML Schema definition CSV, TSV, PSV, SSV – Link to a definition based on the CSV on the web recommendations available from the CSV on the Web Working Group. Other types (e.g. binary file types) – Link to a description of the format

Permission 9
Identifier	`/rec/core/output-format-schema`
Statement	Data schemas MAY be restrictive as needed to promote interoperability, while still accomodating all valid responses.

7.4.2. Position Query

The Position query returns data for the requested coordinate. Logic for identifying the best match for the coordinate will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/position

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 25
Identifier	`/req/core/data-query-position`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `position` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `position` query.
B	The `Position` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of the operations that the query supports (i.e. GET, POST)
C	The `position` query requirement SHALL also specify the logic used in selecting the data returned by the response, i.e. exact, nearest neighbour, most representative or interpolated.

Permission 10
Identifier	`/per/core/position-mandatory-query-definition`
Statement	The `position` query requirement MAY specify which OGC API-EDR `position` query parameters are mandatory for compliance with the profile.

Permission 11
Identifier	`/per/core/position-timestep-diff-query-definition`
Statement	The `position` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 12
Identifier	`/per/core/position-vertical-diff-query-definition`
Statement	The `position` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 13
Identifier	`/per/core/position-custom-dimension-diff-query-definition`
Statement	The `position` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

Permission 14
Identifier	`/per/core/position-choice-query-definition`
Statement	The `position` query requirement MAY specify rules on how the service should identify the most appropriate value for the requested position if there is no exact match (i.e. nearest, most representative, interpolated or none).

7.4.3. Radius Query

The Radius query returns data within the defined radius of the requested coordinate.

Path = {root}/collections/{collectionId}/radius

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 26
Identifier	`/req/core/data-query-radius`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `Radius` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `Radius` query.
B	The `radius` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of `within_units` values Enumerated list of the operations that the query supports (i.e. GET, POST)

Permission 15
Identifier	`/per/core/radius-mandatory-query-definition`
Statement	The `radius` query requirement MAY specify which OGC API-EDR `radius` query parameters are mandatory for compliance with the profile.

Permission 16
Identifier	`/per/core/radius-timestep-diff-query-definition`
Statement	The `radius` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 17
Identifier	`/per/core/radius-vertical-diff-query-definition`
Statement	The `radius` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 18
Identifier	`/per/core/radius-custom-dimension-diff-query-definition`
Statement	The `radius` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.4. Area Query

The Area query returns data within the polygon defined by the coords parameter. Logic for identifying the best match for the requested area will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/area

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 27
Identifier	`/req/core/data-query-area`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `area` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `area` query.
B	The `area` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of the operations that the query supports (i.e. GET, POST)

Permission 19
Identifier	`/per/core/area-mandatory-query-definition`
Statement	The `area` query requirement MAY specify which OGC API-EDR `area` query parameters are mandatory for compliance with the profile.

Permission 20
Identifier	`/per/core/area-timestep-diff-query-definition`
Statement	The `area` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 21
Identifier	`/per/core/area-vertical-diff-query-definition`
Statement	The `area` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 22
Identifier	`/per/core/area-custom-dimension-diff-query-definition`
Statement	The `area` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.5. Cube Query

The Cube query returns a data cube defined by the bbox and z parameters.

Path = {root}/collections/{collectionId}/cube

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 28
Identifier	`/req/core/data-query-cube`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `cube` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `cube` query.
B	The `Cube` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of the operations that the query supports (i.e. GET, POST)

Permission 23
Identifier	`/per/core/cube-mandatory-query-definition`
Statement	The `cube` requirement MAY specify which OGC API-EDR `cube` query parameters are mandatory for compliance with the profile.

Permission 24
Identifier	`/per/core/cube-timestep-diff-query-definition`
Statement	The `cube` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 25
Identifier	`/per/core/cube-vertical-diff-query-definition`
Statement	The `cube` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 26
Identifier	`/per/core/cube-resolution-x`
Statement	The `cube` query requirement MAY specify rules that constrain the valid range of resolution-x values.

Permission 27
Identifier	`/per/core/cube-resolution-y`
Statement	The `cube` query requirement MAY specify rules that constrain the valid range of resolution-y values.

Permission 28
Identifier	`/per/core/cube-resolution-z`
Statement	The `cube` query requirement MAY specify rules that constrain the valid range of resolution-z values.

Permission 29
Identifier	`/per/core/cube-custom-dimension-diff-query-definition`
Statement	The `cube` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.6. Trajectory Query

The Trajectory query returns data along the path defined by the coords parameter. Logic for identifying the best matches for the requested trajectory will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/trajectory

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 29
Identifier	`/req/core/data-query-trajectory`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `trajectory` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `Ttrajectory` query.
B	The `trajectory` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of the operations that the query supports (i.e. `GET`, `POST`)

Permission 30
Identifier	`/per/core/trajectory-mandatory-query-definition`
Statement	The `trajectory` requirement MAY specify which OGC API-EDR `trajectory` query parameters are mandatory for compliance with the profile.

Permission 31
Identifier	`/per/core/trajectory-timestep-diff-query-definition`
Statement	The `trajectory` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 32
Identifier	`/per/core/trajectory-vertical-diff-query-definition`
Statement	The `trajectory` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 33
Identifier	`/per/core/trajectory-custom-dimension-diff-query-definition`
Statement	The `trajectory` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.7. Corridor Query

The Corridor query returns data along and around the path defined by the coords parameter. Logic for identifying the best match for the requested corridor will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/corridor

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 30
Identifier	`/req/core/data-query-corridor`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `corridor` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `corridor` query.
B	The `corridor` requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of `width-units` values Enumerated list of `height-units` values Enumerated list of the operations that the query supports (i.e. GET, POST)

Permission 34
Identifier	`/per/core/corridor-mandatory-query-definition`
Statement	The `corridor` requirement MAY specify which OGC API-EDR `corridor` query parameters are mandatory for compliance with the profile.

Permission 35
Identifier	`/per/core/corridor-timestep-diff-query-definition`
Statement	The `corridor` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 36
Identifier	`/per/core/corridor-vertical-diff-query-definition`
Statement	The `corridor` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple vertical levels, but not all parameters have data for the requested levels.

Permission 37
Identifier	`/per/core/corridor-resolution-x`
Statement	The `corridor` query requirement MAY specify rules that constrain the valid range of resolution-x values.

Permission 38
Identifier	`/per/core/corridor-resolution-y`
Statement	The `corridor` query requirement MAY specify rules that constrain the valid range of resolution-y values.

Permission 39
Identifier	`/per/core/corridor-resolution-z`
Statement	The `corridor` query requirement MAY specify rules that constrain the valid range of resolution-z values.

Permission 40
Identifier	`/per/core/corridor-custom-dimension-diff-query-definition`
Statement	The `corridor` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.8. Locations Query

The Locations query returns data for the named location. Logic for identifying the best match for the coordinate will depend on the Collection and is at the discretion of the query service implementer. If a location id is not defined, the API implementation instance SHALL return a GeoJSON features array of valid location identifiers, the schema of the GeoJSON response SHOULD be defined in the OpenAPI definition of the EDR service.

Path = {root}/collections/{collectionId}/locations

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 31
Identifier	`/req/core/data-query-locations`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard restricts data queries by making the `locations` query mandatory, then:
A	The Service Profile SHALL include a requirement mandating the `locations` query.
B	The `locations` query requirement SHALL specify the following: Enumerated list of `output_format` types The `default_output_format` Enumerated list of `crs_details` values Enumerated list of the operations that the query supports (i.e. GET, POST)

Example 1

identifier: /per/core/locations-mandatory-query-definition
statement: The locations requirement MAY specify which OGC API-EDR locations query parameters are mandatory for compliance with the profile.

Example 2

Permission 41
Identifier	`/per/core/locations-mandatory-locationid-definition`
Statement	The `locations` query requirement MAY specify a list of required `locationId` values.

Permission 42
Identifier	`/per/core/location-timestep-diff-query-definition`
Statement	The `location` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for multiple timesteps, but not all parameters have data for the requested timesteps.

Permission 43
Identifier	`/per/core/location-custom-dimension-diff-query-definition`
Statement	The `location` query requirement MAY specify rules on how the service should respond if a query is made for several parameters for a custom dimension value range, but not all parameters have data for the requested dimension values.

7.4.9. Instances Query

Having multiple versions or Instances of the same Collection, where the same information is reprocessed or regenerated is not unusual. Although these versions could be described as new Collections the Instance query type allows this data to be described as different views of the same Collection.

Path = {root}/collections/{collectionId}/instances

Dependencies: OGC API — Environmental Data Retrieval Standard

Requirement 32
Identifier	`/req/core/data-query-instances`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard extends data queries by making the `instances` within a `Collection` queryable, then:
A	`instances` SHALL be defined in the `data_queries` enumerated list.
B	The Service Profile SHALL specify the rules that the `instanceId` values must follow.
C	Those rules SHALL include a brief description explaining how the `instanceId` is generated.
D	Those rules SHALL be specified using either: identifier string Regular expression defining valid string patterns.
E	The Service Profile MAY define a `instanceId` string which represents either a default or the latest value of `InstanceId`.

7.4.9.1. Parameter queryType

Path — Instance Query {root}/collections/{collectionId}/instances/{instanceId}/{queryType}

7.4.10. Items Query

Paths: * {root}/collections/{collectionId}/items * {root}/collections/{collectionId}/items/{itemid}

Dependencies

OGC API — Features — Part 1: Core
OGC API — Environmental Data Retrieval Standard

The EDR API Items query is like an OGC API — Features Part 1: Core endpoint. The Items query offers some basic compatibility with API-Features for convenience. It may be used to catalog pre-existing EDR sampling features. The pre-existence of an EDR sampling feature may be because a particular query has been cached for later use, such as a monitoring location. Or there may be a catalog of spatio-temporal sampling features such as domains of anomalies in a dataset. A GeoJSON-compatible JSON-Schema is specified to document an EDR API query endpoint and valid query parameters including time range, parameters, and spatial characteristics. A service can define a custom GeoJSON schema in the OpenAPI definition for the service, with the default being the edr-geojson schema if no alternative is documented.

7.4.10.1. ItemID parameter

If an itemId is not specified, the query will return a list of the available itemIds. This behavior is specified in OGC API - Features.

7.4.10.2. Limit parameter

Paging restrictions (limit parameter provided in the request, multi-page response).

Requirement 33
Identifier	`/req/core/paging-support`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile of the OGC API — Environmental Data Retrieval Standard is extended to support paging, then:
A	A requirement SHALL be created for each combination of query pattern and output format that must support paging.
B	Each paging requirement SHALL specify the default number of items to return per page request.

7.5. General Requirements

7.5.1. HTTP Status Codes

HTTP response

Response status codes

Requirement 34
Identifier	`/req/core/status-codes`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	A Service Profile of the OGC API — Environmental Data Retrieval Standard SHALL require that the definitions of all http status codes SHALL be provided.
A	These definitions SHALL provide the following: A description of the cause of the response. A JSON schema for the message body structure

7.5.2. Links

Response links

Requirement 35
Identifier	`/req/core/links`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Profile of the OGC API — Environmental Data Retrieval Standard restricts valid responses to only those which include links, then:
A	The Profile SHALL require that link objects are included in a response.
B	The Profile SHALL define the required link objects in full.
C	The link objects SHALL require that the `href`, `rel` and `type` attributes are populated.
Statement	for example: { "href": "https://creativecommons.org/licenses/by-nc/4.0/", "rel": "licence", "type": "text/html" }, { "href": "https://docs.ogc.org/cs/21-069r2/21-069r2.html", "rel": "service-doc", "title": "CoverageJSON Community Standard v1.0" "type": "text/html" }

7.5.3. Asynchronous Queries

While Web protocols typically use request-response operations, there is also support for asychronous operations.

HTTP Asynchronous — This requirement address the use of HTTP asynchronous operations such as Webhooks and Callbacks.

Requirement 36
Identifier	`/req/core/asynchronous`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Service Profile extends the OGC API — Environmental Data Retrieval Standard with support for asynchronous operations, then:
A	Requirements SHALL be defined for each query type that is asynchronous
B	Each asynchronous query type requirement SHALL define the HTTP Status Code and provide a message schema and text used to inform the user that the response is asynchronous.
C	Each asynchronous query type requirement SHALL document the mechanism for delivering the result of the asynchronous query.

Permission 44
Identifier	`/per/core/asynchronous`
Statement	The documentation of the mechanism for delivering the result of the asynchronous query MAY be provided through a link to an external document.

7.5.4. EDR Part 2 Publish Subscribe Workflows

Publish-Subscribe — This requirement addresses the use of Publish-Subscribe protocols. These are protocols supported in addition to HTTP.

Requirement 37
Identifier	`/req/core/pubsub`
Included in	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Statement	If a Profile of the OGC API — Environmental Data Retrieval Standard extends the supported operations to include Publish-Subscribe operations, then:
A	Support for the OGC API — Environmental Data Retrieval — Part 2: Publish-Subscribe workflow Standard SHALL be required.
B	The pubsub requirement SHALL specify the channels that SHALL be supported
C	The pubsub requirement SHALL specify the payloads that a pubsub channel SHALL support

8. Media Types for any data encoding(s)

A section describing the MIME-types to be used is mandatory for any standard involving data encodings. If no suitable MIME type exists in http://www.iana.org/assignments/media-types/index.html then this section may be used to define a new MIME type for registration with IANA.

Annex A
(informative)
Conformance Class Abstract Test Suite (Normative)

A.1. Conformance Class Core

Conformance class A.1: Conformance Class ‘Core’
Identifier	`http://www.opengis.net/spec/ogcapi-edr-3/1.0/conf/conf-class-core`
Requirements class	Requirements class 1: `http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/req-class-core`
Conformance tests	Abstract test A.1: `/conf/core/modspec` Abstract test A.2: `/conf/core/publishing` Abstract test A.4: `/conf/core/api` Abstract test A.5: `/conf/core/edr-conformant` Abstract test A.6: `/conf/core/root` Abstract test A.7: `/conf/core/requirements-set` Abstract test A.8: `/conf/core/parameter-names` Abstract test A.9: `/conf/core/collectionid` Abstract test A.10: `/conf/core/extent` Abstract test A.11: `/conf/core/output-format` Abstract test A.12: `/conf/core/paging-support` Abstract test A.13: `/conf/core/status-codes` Abstract test A.14: `/conf/core/links` Abstract test A.15: `/conf/core/data-query` Abstract test A.18: `/conf/core/data-query-area` Abstract test A.21: `/conf/core/data-query-corridor` Abstract test A.19: `/conf/core/data-query-cube` Abstract test A.23: `/conf/core/data-query-instances` Abstract test A.22: `/conf/core/data-query-locations` Abstract test A.16: `/conf/core/data-query-position` Abstract test A.17: `/conf/core/data-query-radius` Abstract test A.20: `/conf/core/data-query-trajectory` Abstract test A.24: `/conf/core/asynchronous` Abstract test A.25: `/conf/core/pubsub`

Abstract test A.1
Identifier	`/conf/core/modspec`
Requirement	Requirement 1: `/req/core/modspec`
Test purpose	Validate that the service profile is compliant with the OGC Modular Specification.
Test method
Step	Verify that the service profile is compliant with the OGC Modular Specification.

Abstract test A.2
Identifier	`/conf/core/publishing`
Requirement	Requirement 11: `/req/core/publishing`
Test purpose	Validate that an OpenAPI description of the service profile is available
Test method
Step	Verify that an OpenAPI document describing the service profile exists Verify that the OpenAPI document is compliant with the OpenAPI 3.1 specification Verify that the OpenAPI document includes schemas for the `Collection` and `Instance` query responses Verify that the `Collection` and `Instance` schemas include all of the queries defined in the data-query requirement Verify that the `Collection` and `Instance` schema include Path objects for each of the data_queries defined in the service profile. Verify that the Path Object define Items for the HTTP operations defined by the data query requirements in the service profile Verify that the Path Item definitions include the enumerated lists defined by the data query requirements in the service profile

Abstract test A.3
Identifier	`/conf/core/conformance-classes`
Requirement	Requirement 13: `/req/core/conformance-classes`
Test purpose	Validate that all conformance classes are advertised
Test method
Step	Verify that any service profile advertised in the links section of the root or collection endpoints is included in the response from the /conformance endpoint.

Abstract test A.4
Identifier	`/conf/core/api`
Requirement	Requirement 14: `/req/core/api`
Test purpose	Validate that the service profile includes a requirement specifying the OpenAPI versions that implementations shall support.
Test method
Step	Verify that the service profile includes a requirement defining the OpenAPI versions that implementations shall support. Verify that the service profile includes a conformance class testing that OpenAPI versions are supported.

Abstract test A.5
Identifier	`/conf/core/edr-conformant`
Requirement	Requirement 2: `/req/core/edr-conformant`
Test purpose	Validate that any implementation conforming to the Service Profile Standard demonstrates conformance with the OGC API-EDR Standard.
Test method
Step	Verify that the service profile specifies that regardless of any service profile specific requirements, implementations shall function as OGC API-EDR Part 1 — Core compliant API’s.

Abstract test A.6
Identifier	`/conf/core/root`
Requirement	Requirement 4: `/req/core/root`
Test purpose	Validate that the service profile defines the service landing page
Test method
Step	Verify that the links section includes a link to its service profile definition. Verify that the service profile defines a `Title` for the service Verify that the service profile defines the `Links` required for the service Verify that each link defined for the service has a `href` and `rel` attribute. Verify that any `Description` attributes in the service profile have a defined value. Verify that any `Attribution` attributes in the service profile have a defined value. Verify that any `Keywords` attributes in the service profile have defined values. Verify that any `Provider` attributes in the service profile have `name` and `url` attributes. Verify that the providers `name` and `url` attributes have defined values. Verify that any `Contact` attributes in the service profile have an `email` attributes. Verify that contact `email` attributes has a defined value.

Abstract test A.7
Identifier	`/conf/core/requirements-set`
Requirement	Requirement 15: `/req/core/requirements-set`
Test purpose	Validate that the service profile defines at least one requirement for a collection
Test method
Step	Verify that the collection contains a link to the service profile definition. Verify that the service profile contains at least one requirement which applies to a collection. Verify that collection requirements in the service profile clearly identify which collection a requirement applies to.

Abstract test A.8
Identifier	`/conf/core/parameter-names`
Requirement	Requirement 22: `/req/core/parameter-names`
Test purpose	Validate that the parameter_names requirement is correctly defined
Test method
Step	Verify that the parameter_names requirement defines a set of parameter objects Verify that each parameter object in the set has a unique key Verify that each parameter object in the set has a type value of “Parameter” Verify that each parameter object in the set has a description attribute Verify that each parameter object in the set has a unit attribute Verify that each unit object a label attribute Verify that each unit object a symbol attribute Verify that each symbol object a value attribute Verify that each symbol object a type attribute Verify that each parameter object in the set has an observedProperty attribute Verify that each observedProperty object has an id attribute Verify that each observedProperty object has a label attribute

Abstract test A.9
Identifier	`/conf/core/collectionid`
Requirement	Requirement 16: `/req/core/collectionid`
Test purpose	Validate that a `collectionId` requirement is correctly defined.
Test method
Step	Verify that a `collectionId` requirement includes an explanation of how a `collectionId` is derived. Verify that a `collectionId` requirement specifies either an identifier string or a Regular expression.

Abstract test A.10
Identifier	`/conf/core/extent`
Requirement	Requirement 17: `/req/core/extent`
Test purpose	Validate the service profile extent requirements are defined correctly.
Test method
Step	Verify that the service profile has a requirement specifying the spatial extent of the `Collection`. Verify that the service profile specifies either an enumerated list of CRS values or a Regular expression definition for valid CRS values. Verify that Temporal extent requirements specify either an enumerated list of TRS values or a Regular expression definition for valid TRS values. Verify that Vertical extent requirements specify either an enumerated list of VRS values or a Regular expression definition for valid VRS values. Verify that Custom extent requirements specify the id of the custom dimension. Verify that Custom extent requirements specify the custom dimension reference value. Verify that Custom extent requirements specify the custom dimension interval value. Verify that Custom extent requirements specify an enumerated list of the valid custom dimension values.

Abstract test A.11
Identifier	`/conf/core/output-format`
Requirement	Requirement 24: `/req/core/output-format`
Test purpose	Validate that the service profile correctly defines output-formats
Test method
Step	Verify that the service profile contains references to the schemas or format descriptions for all output-formats defined in the data queries requirements

Abstract test A.12
Identifier	`/conf/core/paging-support`
Requirement	Requirement 33: `/req/core/paging-support`
Test purpose	Validate that paging support requirements are correctly defined
Test method
Step	Verify that a paging support requirement defines which query types will support output paging Verify that a paging support requirement identifies which output formats support paging in paging-capable queries Verify that a paging support requirement defines the default number of items to return per page request

Abstract test A.13
Identifier	`/conf/core/status-codes`
Requirement	Requirement 34: `/req/core/status-codes`
Test purpose	Validate that the service profile defines any HTTP status code responses required by a service.
Test method
Step	Verify that the service profile contains HTTP status code definitions Verify that any HTTP status code definition has a description value. Verify that each HTTP status code definition includes a JSON schema for the response body.

Abstract test A.14
Identifier	`/conf/core/links`
Requirement	Requirement 35: `/req/core/links`
Test purpose	Validate that link requirements are correctly defined
Test method
Step	Verify that link requirements define a `href` value Verify that link requirements define a `rel` value Verify that link requirements define a `type` value

Abstract test A.15
Identifier	`/conf/core/data-query`
Requirement	Requirement 23: `/req/core/data-query`
Test purpose	Validate that a service profile correctly defines the query types that a service shall support.
Test method
Step	Verify that the profile defines an enumerated list of the queries that a service shall support. Verify that for each definition in the enumerated list there is a corresponding data query requirement in the profile.

Abstract test A.16
Identifier	`/conf/core/data-query-position`
Requirement	Requirement 25: `/req/core/data-query-position`
Test purpose	Verify that Position query requirements are defined correctly in a service profile.
Test method
Step	Verify a Position query requirement defines the logic in used selecting the appropriate data response. Verify a Position query requirement defines an enumerated list of output_format types. Verify a Position query requirement defines the default output_format. Verify a Position query requirement defines an enumerated list of crs_details values. Verify a Position query requirement defines a list of supported HTTP operations.

Abstract test A.17
Identifier	`/conf/core/data-query-radius`
Requirement	Requirement 26: `/req/core/data-query-radius`
Test purpose	Verify that Radius query requirements are defined correctly in a service profile.
Test method
Step	Verify a Radius query requirement defines an enumerated list of output_format types. Verify a Radius query requirement defines the default output_format. Verify a Radius query requirement defines an enumerated list of crs_details values. Verify a Radius query requirement defines an enumerated list of within_units values. Verify a Radius query requirement defines a list of supported HTTP operations.

Abstract test A.18
Identifier	`/conf/core/data-query-area`
Requirement	Requirement 27: `/req/core/data-query-area`
Test purpose	Verify that Area query requirements are defined correctly in a service profile.
Test method
Step	Verify an Area query requirement defines an enumerated list of output_format types. Verify an Area query requirement defines the default output_format. Verify an Area query requirement defines an enumerated list of crs_details values. Verify an Area query requirement defines a list of supported HTTP operations.

Abstract test A.19
Identifier	`/conf/core/data-query-cube`
Requirement	Requirement 28: `/req/core/data-query-cube`
Test purpose	Verify that Cube query requirements are defined correctly in a service profile.
Test method
Step	Verify a Cube query requirement defines an enumerated list of output_format types. Verify a Cube query requirement defines the default output_format. Verify a Cube query requirement defines an enumerated list of crs_details values. Verify a Cube query requirement defines a list of supported HTTP operations.

Abstract test A.20
Identifier	`/conf/core/data-query-trajectory`
Requirement	Requirement 29: `/req/core/data-query-trajectory`
Test purpose	Verify that Trajectory query requirements are defined correctly in a service profile.
Test method
Step	Verify a Trajectory query requirement defines an enumerated list of output_format types. Verify a Trajectory query requirement defines the default output_format. Verify a Trajectory query requirement defines an enumerated list of crs_details values. Verify a Trajectory query requirement defines a list of supported HTTP operations.

Abstract test A.21
Identifier	`/conf/core/data-query-corridor`
Requirement	Requirement 30: `/req/core/data-query-corridor`
Test purpose	Verify that Corridor query requirements are defined correctly in a service profile.
Test method
Step	Verify that a Corridor requirement defines an enumerated list of output_format types. Verify that a Corridor requirement defines the default output_format. Verify that a Corridor requirement defines an enumerated list of crs_details values. Verify that a Corridor requirement defines an enumerated list of width-units values. Verify that a Corridor requirement defines an enumerated list of height-units values. Verify that a Corridor requirement defines a list of supported HTTP operations.

Abstract test A.22
Identifier	`/conf/core/data-query-locations`
Requirement	Requirement 31: `/req/core/data-query-locations`
Test purpose	Verify that Locations query requirements are defined correctly in a service profile.
Test method
Step	Verify a Locations query requirement defines an enumerated list of output_format types. Verify a Locations query requirement defines the default output_format. Verify a Locations query requirement defines an enumerated list of crs_details values. Verify a Locations query requirement defines a list of supported HTTP operations.

Abstract test A.23
Identifier	`/conf/core/data-query-instances`
Requirement	Requirement 32: `/req/core/data-query-instances`
Test purpose	Validate than a service profile correctly defines support for `instances`
Test method
Step	Verify that the data queries requirement enumerated list includes an entry for `instances`. Verify that an `instanceId` requirement includes an explanation of how an `instanceId` is derived. Verify that an `instanceId` requirement contains either an identifier string or a Regular expression rule for defining the `instanceId`.

Abstract test A.24
Identifier	`/conf/core/asynchronous`
Requirement	Requirement 36: `/req/core/asynchronous`
Test purpose	Validate that an asynchronous query support requirement in correctly defined
Test method
Step	Verify that all asynchronous query requirements in a service profile define a HTTP Status Code for the asynchronous response. Verify that all asynchronous query requirements in a service profile define a message schema for the asynchronous response. Verify that all asynchronous query requirements in a service profile define the text for the asynchronous response. Verify that all asynchronous query requirements in a service profile define the mechanism for delivering the asynchronous query result.

Abstract test A.25
Identifier	`/conf/core/pubsub`
Requirement	Requirement 37: `/req/core/pubsub`
Test purpose	Validate Pub/Sub requirements
Test method
Step	Verify that the service profile specifies the OGC API-EDR Part 2 conformance class Verify that the service profile defines the channels services shall implement. Verify that the service profile defines the message payloads required for each of the channels in the service. Verify the service profile contains an AsyncAPI definition that describes the channels and their messages.

Document number:	25-014r1
Document type:	OGC Standard
Document subtype:	Implementation
Document stage:	Draft
Document language:	English