The approved standard OpenAPI description OGC itself publishes for OGC API - Records. This is the STANDARD'S contract, not any one deployment of it — the servers block is a template, so it describes what a conformant implementation must offer rather than a callable host.
openapi: 3.0.3
info:
title: "OGC API - Records - Part 1: Core"
version: '1.0.0'
description: |-
This is a sample OpenAPI definition that conforms to the conformance
classes of the "OGC API - Records - Part 1: Core" standard:
* Searchable Catalog
* Searchable Catalog - Sorting
* Local Resources Catalog
* Local Resources Catalog - Query Parameters
* Local Resources Catalog - Sorting
* OpenAPI 3.0
This example is a generic definition that uses path parameters to
describe all catalogs and records. The generic OpenAPI definition
does not provide any details on the catalogs or the record content.
This information is only available by accessing the catalog and its
records.
contact:
name: CubeWerx Inc.
email: pvretano@cubewerx.com
url: 'https://www.cubewerx.com'
license:
name: CC-BY 4.0 license
url: 'https://creativecommons.org/licenses/by/4.0/'
servers:
- url: 'https://example.org/data'
description: Production server
- url: 'https://example.org/data-dev'
description: Development server
tags:
- name: Capabilities
description: |-
essential characteristics of this API
- name: Conformance
description: |-
list of conformance classes implemented by this API
- name: Collections
description: |-
list of catalogs offered by this API
- name: Collection
description: |-
description of a catalog offered by this API
- name: Sortables
description: |-
list of record properties by which responses can be sorted
- name: Records
description: |-
access to records
- name: Record
description: |-
access to a single record
paths:
'/':
get:
tags:
- Capabilities
summary: landing page
description: |-
The landing page provides links to the API definition, the conformance
statements and to the record collections in this dataset.
operationId: getLandingPage
parameters:
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/LandingPage'
'4XX':
$ref: '#/components/responses/BadRequest'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/conformance':
get:
tags:
- Conformance
summary: information about specifications that this API conforms to
description: |-
A list of all conformance classes specified in a standard that the
server conforms to.
operationId: getConformanceDeclaration
responses:
'200':
$ref: '#/components/responses/ConformanceDeclaration'
'4XX':
$ref: '#/components/responses/BadRequest'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/collections':
get:
tags:
- Collections
summary: the record collections
description: |-
Fetch list of catalogs offered by this API
operationId: getCollections
parameters:
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/datetime'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/externalIds'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/sortby'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/Catalogs'
'4XX':
$ref: '#/components/responses/BadRequest'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/collections/{catalogId}':
get:
tags:
- Collection
summary: |-
describe the record collection with id `catalogId`
description: |-
Fetch a detailed description of a catalog or collection of records
with id `catalogId`.
operationId: describeCollection
parameters:
- $ref: '#/components/parameters/catalogId'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/Catalog'
'4XX':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/collections/{catalogId}/sortables':
get:
tags:
- Sortables
summary: |-
get the list of sortable properties
description: |-
Fetch the list of properties which can be used to sort the getRecords
response.
operationId: getSortables
parameters:
- $ref: '#/components/parameters/catalogId'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/Sortables'
'4XX':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/collections/{catalogId}/items':
get:
tags:
- Records
summary: fetch records
description: |-
Fetch records from the record collection with id `catalogId`.
Every record in a dataset belongs to a collection. A dataset may
consist of multiple record collections. A record collection is often a
collection of records of a similar type, based on a common schema.
Use content negotiation to request HTML or GeoJSON.
operationId: getRecords
parameters:
- $ref: '#/components/parameters/catalogId'
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/datetime'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/externalIds'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/sortby'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/Records'
'4XX':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
'/collections/{catalogId}/items/{recordId}':
get:
tags:
- Record
summary: fetch a single record
description: |-
Fetch the record with id `recordId` from the record collection
with id `catalogId`.
Use content negotiation to request HTML or GeoJSON.
operationId: getRecord
parameters:
- $ref: '#/components/parameters/catalogId'
- $ref: '#/components/parameters/recordId'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/profile'
responses:
'200':
$ref: '#/components/responses/Record'
'4XX':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'406':
$ref: '#/components/responses/NotAcceptable'
'5XX':
$ref: '#/components/responses/ServerError'
components:
parameters:
bbox:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/parameters/bbox.yaml'
Only features that have a geometry that intersects the bounding box are
selected. The bounding box is provided as four or six numbers,
depending on whether the coordinate reference system includes a
vertical axis (height or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Minimum value, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Maximum value, coordinate axis 3 (optional)
If the value consists of four numbers, the coordinate reference system
is WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/
CRS84) unless a different coordinate reference system is specified in
the parameter `bbox-crs`.
If the value consists of six numbers, the coordinate reference system
is WGS 84 longitude/latitude/ellipsoidal height (http://www.opengis.
net/def/crs/OGC/0/CRS84h) unless a different coordinate reference
system is specified in the parameter `bbox-crs`.
The query parameter `bbox-crs` is specified in
OGC API - Features - Part 2: Coordinate Reference Systems by Reference.
For WGS 84 longitude/latitude the values are in most cases the sequence
of minimum longitude, minimum latitude, maximum longitude and maximum
latitude. However, in cases where the box spans the antimeridian the
first value (west-most box edge) is larger than the third value
(east-most box edge).
If the vertical axis is included, the third and the sixth number are the
bottom and the top of the 3-dimensional bounding box.
If a feature has multiple spatial geometry properties, it is the
decision of the server whether only a single spatial geometry property
is used to determine the extent or all relevant geometries.
name: bbox
in: query
required: false
schema:
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
style: form
explode: false
catalogId:
name: catalogId
in: path
description: local identifier of a catalog
required: true
schema:
type: string
datetime:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/parameters/datetime.yaml
Either a date-time or an interval. Date and time expressions adhere to
RFC 3339. Intervals may be bounded or half-bounded (double-dots at
start or end).
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Half-bounded intervals: "2018-02-12T00:00:00Z/.." or
"../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value
of `datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.
name: datetime
in: query
required: false
schema:
type: string
style: form
explode: false
externalIds:
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
ids:
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
language:
name: language
in: query
description: |-
Optional way to query for specific languages for environments that can't
send HTTP headers in a simple way (e.g. a Web Browser).
The parameter accepts a comma-separated list of language identifiers,
optionally with priority per language.
This parameter value follows the specification of the `Accept-Language`
HTTP header.
schema:
type: array
items:
type: string
description: |-
The language tag as per RFC 5646, with optional priority parameter
`q` (0 - 1).
pattern: "^((?:(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?:([A-Za-z]{2,3}(-(?:[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?:[A-Za-z]{4}))?(-(?:[A-Za-z]{2}|[0-9]{3}))?(-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?:[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?:x(-[A-Za-z0-9]{1,8})+))?)|(?:x(-[A-Za-z0-9]{1,8})+))(?:;q=(?:1|1\\.0+|0|0\\.[0-9]+))?$"
explode: false
style: form
limit:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/parameters/limit.yaml
The optional limit parameter limits the number of items that are
presented in the response document.
Only items are counted that are on the first level of the collection
in the response document.
Nested objects contained within the explicitly requested items shall
not be counted.
Minimum = 1. Maximum = 10000. Default = 10.
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 10
style: form
explode: false
profile:
name: profile
in: query
description: |-
One or more identifiers that provide information about additional
semantics (constraints, conventions, extensions), in addition to
those defined by the media type, that are associated with the
target resource.
required: false
schema:
type: array
items:
type: string
explode: false
style: form
q:
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
recordId:
name: recordId
in: path
description: local identifier of a record
required: true
schema:
type: string
sortby:
name: sortby
in: query
description: |-
Specifies a comma-separated list of property names by which the
response shall be sorted. If the property name is preceded by a
plus (+) sign it indicates an ascending sort for that property.
If the property name is preceded by a minus (-) sign it indicates a
descending sort for that property. If the property is not preceded
by a plus or minus, then the default sort order implied is
ascending (+).
required: false
schema:
type: array
minItems: 1
items:
type: string
pattern: '[+|-]?[A-Za-z_].*'
explode: false
style: form
type:
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
schemas:
f-collections:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collections.yaml
type: object
required:
- links
- collections
properties:
links:
type: array
items:
$ref: '#/components/schemas/link'
collections:
type: array
items:
$ref: '#/components/schemas/f-collection'
f-collection:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml
type: object
required:
- id
- links
properties:
id:
description: identifier of the collection used, for example, in URIs
type: string
example: address
title:
description: human readable title of the collection
type: string
example: address
description:
description: a description of the features in the collection
type: string
example: An address.
links:
type: array
items:
$ref: '#/components/schemas/link'
example:
- href: http://data.example.com/buildings
rel: item
- href: http://example.com/concepts/buildings.html
rel: describedby
type: text/html
extent:
$ref: '#/components/schemas/f-extent'
itemType:
description: |-
indicator about the type of the items in the collection (the
default value is 'feature').
type: string
default: feature
crs:
description: |-
the list of coordinate reference systems supported by the service
type: array
items:
type: string
default:
- http://www.opengis.net/def/crs/OGC/1.3/CRS84
example:
- http://www.opengis.net/def/crs/OGC/1.3/CRS84
- http://www.opengis.net/def/crs/EPSG/0/4326
f-extent:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/extent.yaml
The extent of the features in the collection. In the Core only spatial
and temporal extents are specified. Extensions may add additional
members to represent other extents, for example, thermal or pressure
ranges.
An array of extents is provided for each extent type (spatial,
temporal). The first item in the array describes the overall extent of
the data. All subsequent items describe more precise extents, e.g., to
identify clusters of data. Clients only interested in the overall
extent will only need to access the first extent in the array.
type: object
properties:
spatial:
description: |-
The spatial extent of the features in the collection.
type: object
properties:
bbox:
description: |-
One or more bounding boxes that describe the spatial extent
of the dataset.
In the Core only a single bounding box is supported.
Extensions may support additional areas.
The first bounding box describes the overall spatial
extent of the data. All subsequent bounding boxes describe
more precise bounding boxes, e.g., to identify clusters of data.
Clients only interested in the overall spatial extent will
only need to access the first bounding box in the array.
type: array
minItems: 1
items:
description: |-
Each bounding box is provided as four or six numbers,
depending on whether the coordinate reference system
includes a vertical axis (height or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Minimum value, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Maximum value, coordinate axis 3 (optional)
If the value consists of four numbers, the coordinate
reference system is WGS 84 longitude/latitude (http://www.
opengis.net/def/crs/OGC/1.3/CRS84) unless a different
coordinate reference system is specified in `crs`.
If the value consists of six numbers, the coordinate
reference system is WGS 84 longitude/latitude/ellipsoidal
height (http://www.opengis.net/def/crs/OGC/0/CRS84h)
unless a different coordinate reference system is specified
in `crs`.
For WGS 84 longitude/latitude the values are in most cases
the sequence of minimum longitude, minimum latitude, maximum
longitude and maximum latitude. However, in cases where the
box spans the antimeridian the first value (west-most box
edge) is larger than the third value (east-most box edge).
If the vertical axis is included, the third and the sixth
number are the bottom and the top of the 3-dimensional
bounding box.
If a feature has multiple spatial geometry properties, it is
the decision of the server whether only a single spatial
geometry property is used to determine the extent or all
relevant geometries.
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
example:
- -180
- -90
- 180
- 90
crs:
description: |-
Coordinate reference system of the coordinates in the spatial
extent (property `bbox`). The default reference system is WGS
84 longitude/latitude. In the Core the only other supported
coordinate reference system is WGS 84 longitude/latitude/
ellipsoidal height for coordinates with height.
Extensions may support additional coordinate reference systems
and add additional enum values.
type: string
enum:
- 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
- 'http://www.opengis.net/def/crs/OGC/0/CRS84h'
default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
temporal:
description: |-
The temporal extent of the features in the collection.
type: object
properties:
interval:
description: |-
One or more time intervals that describe the temporal extent
of the dataset. In the Core only a single time interval is
supported.
Extensions may support multiple intervals.
The first time interval describes the overall temporal extent
of the data. All subsequent time intervals describe more
precise time intervals, e.g., to identify clusters of data.
Clients only interested in the overall temporal extent will
only need to access the first time interval in the array (a
pair of lower and upper bound instants).
type: array
minItems: 1
items:
description: |-
Begin and end times of the time interval. The timestamps are
in the temporal coordinate reference system specified in
`trs`. By default this is the Gregorian calendar.
The value `null` at start or end is supported and indicates
a half-bounded interval.
type: array
minItems: 2
maxItems: 2
items:
type: string
format: date-time
nullable: true
example:
- '2011-11-11T12:22:11Z'
- null
trs:
description: |-
Coordinate reference system of the coordinates in the temporal
extent (property `interval`). The default reference system is
the Gregorian calendar. In the Core this is the only supported
temporal coordinate reference system.
Extensions may support additional temporal coordinate reference
systems and add additional enum values.
type: string
enum:
- 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'
default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'
featureCollectionGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/featureCollectionGeoJSON.yaml
type: object
required:
- type
- features
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: '#/components/schemas/featureGeoJSON'
links:
type: array
items:
$ref: '#/components/schemas/link'
timeStamp:
type: string
format: date-time
numberMatched:
type: integer
minimum: 0
numberReturned:
type: integer
minimum: 0
featureGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/featureGeoJSON.yaml
type: object
required:
- type
- geometry
- properties
properties:
type:
type: string
enum:
- Feature
geometry:
$ref: '#/components/schemas/geometryGeoJSON'
properties:
type: object
nullable: true
id:
oneOf:
- type: string
- type: integer
links:
type: array
items:
$ref: '#/components/schemas/link'
geometryGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml
oneOf:
- $ref: '#/components/schemas/pointGeoJSON'
- $ref: '#/components/schemas/multipointGeoJSON'
- $ref: '#/components/schemas/linestringGeoJSON'
- $ref: '#/components/schemas/multilinestringGeoJSON'
- $ref: '#/components/schemas/polygonGeoJSON'
- $ref: '#/components/schemas/multipolygonGeoJSON'
- $ref: '#/components/schemas/geometrycollectionGeoJSON'
pointGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/pointGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Point
coordinates:
type: array
minItems: 2
items:
type: number
multipointGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/multipointGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: number
linestringGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/linestringGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- LineString
coordinates:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
multilinestringGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/multilinestringGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiLineString
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
polygonGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/polygonGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
multipolygonGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/multipolygonGeoJSON.yaml
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
geometrycollectionGeoJSON:
description: |-
Imported from OGC API - Features - Part 1: Core
See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometrycollectionGeoJSON.yaml
type: object
required:
- type
- geometries
properties:
type:
type: string
enum:
- GeometryCollection
geometries:
type: array
items:
$ref: '#/components/schemas/geometryGeoJSON'
exception:
d
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ogc/refs/heads/main/openapi/_original/ogc-records-part1-1-0-openapi-ogcapi-records-1-example-all-in-one.yaml