Open Geospatial Consortium (OGC) Collection API

openapi: 3.2.0
info:
  title: Ogc Collection API
  version: 1.0.0
  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/
  description: 'Operations tagged Collection across 3 of this provider''s published API definitions: ogc-records-part1-1-0-openapi-ogcapi-records-1-example-all-in-one.yaml, ogc-records-part1-1-0-openapi-ogcapi-records-1-example-ref-buildingblocks-bundle.yaml, ogc-records-part1-1-0-openapi-ogcapi-records-1-example-ref-schema-repo.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://example.org/data
  description: Production server
- url: https://example.org/data-dev
  description: Development server
security:
- openIdConnect: []
tags:
- name: Collection
  description: description of a catalog offered by this API
paths:
  /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'
    servers:
    - url: https://example.org/data
      description: Production server
    - url: https://example.org/data-dev
      description: Development server
components:
  responses:
    Catalog:
      description: "Information about the record collection with id `collectionId`.\n\nThe response contains a link to the items in the collection\n(path `/collections/{collectionId}/items`, link relation `items`)\nas well as key information about the collection. This information\nincludes:\n\n* A local identifier for the collection that is unique for the +\n  catalog;\n* A list of coordinate reference systems (CRS) in which geometries +\n  may be returned by the server. The first CRS is the default +\n  coordinate reference system (the default is always WGS 84 with +\n  axis order longitude/latitude);\n* An optional title and description for the collection;\n* An optional extent that can be used to provide an indication of +\n  the spatial and temporal extent of the collection - typically +\n  derived from the data;\n* An optional indicator about the type of the items in the collection +\n  (the default value, if the indicator is not provided, is 'record')."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/catalog'
        text/html:
          schema:
            type: string
    NotFound:
      description: 'The requested resource does not exist on the server. For example,

        a path parameter had an incorrect value.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    ServerError:
      description: A server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    NotAcceptable:
      description: 'Content negotiation failed. For example, the `Accept` header submitted

        in the request did not support any of the media types supported by the

        server for the requested resource.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    BadRequest:
      description: A client error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
  parameters:
    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
    catalogId:
      name: catalogId
      in: path
      description: local identifier of a catalog
      required: true
      schema:
        type: string
    profile:
      name: profile
      in: query
      description: "One or more identifiers that provide information about additional\nsemantics (constraints, conventions, extensions), in addition to \nthose defined by the media type, that are associated with the\ntarget resource."
      required: false
      schema:
        type: array
        items:
          type: string
      explode: false
      style: form
  schemas:
    linkBase:
      type: object
      properties:
        rel:
          type: string
          description: The type or semantics of the relation.
        type:
          type: string
          description: 'A hint indicating what the media type of the

            result of dereferencing the link should be.'
        hreflang:
          type: string
          description: 'A hint indicating what the language of the

            result of dereferencing the link should be.'
        title:
          type: string
          description: 'Used to label the destination of a link

            such that it can be used as a human-readable

            identifier.'
        length:
          type: integer
        profile:
          type: array
          description: "One or more identifiers that provide information about additional\nsemantics (constraints, conventions, extensions), in addition to \nthose defined by the media type, that are associated with the\ntarget resource."
          items:
            type: string
        created:
          type: string
          description: 'Date of creation of the resource pointed to

            by the link.'
          format: date-time
        updated:
          type: string
          description: 'Most recent date on which the resource pointed

            to by the link was changed.'
          format: date-time
    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
                  - 'null'
                  format: date-time
                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
    roles:
      description: 'The list of duties, job functions or permissions assigned by the system

        and associated with the context of this member.'
      type: array
      minItems: 1
      items:
        type: string
    linkTemplate:
      allOf:
      - $ref: '#/components/schemas/linkBase'
      - type: object
        required:
        - uriTemplate
        properties:
          uriTemplate:
            type: string
            description: 'Supplies a resolvable URI to a remote resource

              (or resource fragment).'
          varBase:
            type: string
            description: 'The base URI to which the variable name can be

              appended to retrieve the definition of the

              variable as a JSON Schema fragment.'
            format: uri-reference
          variables:
            type: object
            description: 'This object contains one key per substitution

              variable in the templated URL.  Each key defines

              the schema of one substitution variable using a

              JSON Schema fragment and can thus include things

              like the data type of the variable, enumerations,

              minimum values, maximum values, etc.'
    language:
      type: object
      description: The language used for textual values in this record.
      required:
      - code
      properties:
        code:
          type: string
          description: The language tag as per RFC-5646.
        name:
          type: string
          minLength: 1
          description: The untranslated name of the language.
        alternate:
          type: string
          description: 'The name of the language in another well-understood language,

            usually English.'
        dir:
          type: string
          description: 'The direction for text in this language. The default, `ltr`

            (left-to-right), represents the most common situation.

            However, care should be taken to set the value of `dir`

            appropriately if the language direction is not `ltr`.

            Other values supported are `rtl` (right-to-left), `ttb`

            (top-to-bottom), and `btt` (bottom-to-top).'
          enum:
          - ltr
          - rtl
          - ttb
          - btt
          default: ltr
    license:
      type: string
      description: 'A legal document under which the resource is made available.

        If the resource is being made available under a common license

        then use an SPDX license id (https://spdx.org/licenses/).

        If the resource is being made available under multiple common

        licenses then use an SPDX license expression v2.3 string

        (https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/)

        If the resource is being made available under one or more licenses

        that haven''t been assigned an SPDX identifier or one or more custom

        licenses then use a string value of ''other'' and include one or more

        links (rel="license") in the `link` section of the record to the

        file(s) that contains the text of the license(s).

        There is also the case of a resource that is private or unpublished

        and is thus unlicensed; in this case do not register such a resource

        in the catalog in the first place since there is no point in making

        such a resource discoverable.'
    exception:
      description: 'Imported from OGC API - Features - Part 1: Core

        See: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/exception.yaml'
      type: object
      required:
      - code
      properties:
        code:
          type: string
        description:
          type: string
    defaultSortOrder:
      type: array
      items:
        type: object
        required:
        - field
        - direction
        properties:
          field:
            type: string
          direction:
            type: string
            enum:
            - asc
            - desc
    link:
      type: object
      allOf:
      - $ref: '#/components/schemas/linkBase'
      - type: object
        required:
        - href
        properties:
          href:
            type: string
            format: uri
    contact:
      type: object
      description: 'Identification of, and means of communication with, person responsible

        for the resource.'
      anyOf:
      - required:
        - name
      - required:
        - organization
      properties:
        identifier:
          type: string
          description: A value uniquely identifying a contact.
        name:
          type: string
          description: The name of the responsible person.
        position:
          type: string
          description: 'The name of the role or position of the responsible person taken

            from the organization''s formal organizational hierarchy or chart.'
        organization:
          type: string
          description: Organization/affiliation of the contact.
        logo:
          description: 'Graphic identifying a contact. The link relation should be `icon`

            and the media type should be an image media type.'
          allOf:
          - $ref: '#/components/schemas/link'
          - type: object
            required:
            - rel
            - type
            properties:
              rel:
                enum:
                - icon
        phones:
          type: array
          description: Telephone numbers at which contact can be made.
          items:
            type: object
            required:
            - value
            properties:
              value:
                type: string
                description: The value is the phone number itself.
                pattern: ^\+[1-9]{1}[0-9]{3,14}$
              roles:
                $ref: '#/components/schemas/roles'
        emails:
          type: array
          description: Email addresses at which contact can be made.
          items:
            type: object
            required:
            - value
            properties:
              value:
                type: string
                description: The value is the email number itself.
                format: email
              roles:
                $ref: '#/components/schemas/roles'
        addresses:
          type: array
          description: Physical location at which contact can be made.
          items:
            type: object
            properties:
              deliveryPoint:
                type: array
                description: Address lines for the location.
                items:
                  type: string
              city:
                type: string
                description: City for the location.
              administrativeArea:
                type: string
                description: State or province of the location.
              postalCode:
                type: string
                description: ZIP or other postal code.
              country:
                type: string
                description: Country of the physical address.  ISO 3166-1 is recommended.
              roles:
                $ref: '#/components/schemas/roles'
        links:
          type: array
          description: On-line information about the contact.
          items:
            allOf:
            - $ref: '#/components/schemas/link'
            - type: object
              required:
              - type
        hoursOfService:
          type: string
          description: Time period when the contact can be contacted.
        contactInstructions:
          type: string
          description: 'Supplemental instructions on how or when to contact the

            responsible party.'
        roles:
          $ref: '#/components/schemas/roles'
    scheme:
      type: object
      required:
      - scheme-id
      - namespace
      properties:
        scheme-id:
          type: string
          description: "An identifier for this namespace.  The identifier can be used as a \nshort-form for the namespace."
        namespace:
          type: string
          description: 'A declarative region that provides a scope to the identifiers

            inside it. It is recommended that the value of namespace be a URI.'
        resolver:
          description: 'An extensible description of a mechanism that resolves a scheme

            identifier (scheme-id) to its namespace.'
          type: object
    recordCommonProperties:
      type: object
      properties:
        created:
          type: string
          description: The date this record was created in the server.
          format: date-time
        updated:
          type: string
          description: The most recent date on which the record was changed.
          format: date-time
        type:
          type: string
          description: 'The nature or genre of the resource. The value

            should be a code, convenient for filtering

            records. Where available, a link to the canonical

            URI of the record type resource will be added to

            the ''links'' property.'
        title:
          type: string
          description: A human-readable name given to the resource.
        description:
          type: string
          description: A free-text account of the resource.
        keywords:
          type: array
          description: 'The topic or topics of the resource. Typically

            represented using free-form keywords, tags, key

            phrases, or classification codes.'
          items:
            type: string
        themes:
          type: array
          description: 'A knowledge organization system used to classify

            the resource.'
          minItems: 1
          items:
            $ref: '#/components/schemas/theme'
        language:
          $ref: '#/components/schemas/language'
        languages:
          type: array
          description: 'This list of languages in which this record is

            available.'
          items:
            $ref: '#/components/schemas/language'
        resourceLanguages:
          type: array
          description: 'The list of languages in which the resource

            described by this record is available.'
          items:
            $ref: '#/components/schemas/language'
        externalIds:
          type: array
          description: 'An identifier for the resource assigned by an

            external (to the catalog) entity.'
          items:
            type: object
            properties:
              scheme:
                type: string
                description: 'A reference to an authority or identifier

                  for a knowledge organization system from

                  which the external identifier was obtained.

                  It is recommended that the identifier be a

                  resolvable URI.'
              value:
                type: string
                description: The value of the identifier.
            required:
            - value
        formats:
          type: array
          description: A list of available distributions of the resource.
          items:
            $ref: '#/components/schemas/format'
        contacts:
          type: array
          description: 'A list of contacts qualified by their role(s) in

            association to the record or the resource described

            by the record.'
          items:
            $ref: '#/components/schemas/contact'
        license:
          $ref: '#/components/schemas/license'
        rights:
          type: string
          description: 'A statement that concerns all rights not addressed

            by the license such as a copyright statement.'
    catalogCommonProperties:
      allOf:
      - $ref: '#/components/schemas/recordCommonProperties'
      - type: object
        required:
        - type
        properties:
          type:
            description: 'Fixed to "Collection" for collections of records and/or

              subordinate catalogs.  Wanted to use the JSON-Schema const

              key work but all the swagger validators tried complained

              about it.'
            type: string
            enum:
            - Collection
          conformsTo:
            type: array
            description: The extensions/conformance classes used in this collection.
            items:
              type: string
          recordsArrayName:
            description: "If records are encoded in-line within the catalog object,\nthis member advertises the name of the array member that \ncontains the catalog records.  By default the name of the\nrecords array is \"records\".  However, the name of this \narray member may be different.  A local resources catalog\nis an example of a circumstance where the records array\nmember may be named something other than \"records\".  For\nexample, in the case of a local resource catalog at the \n/collections endpoint, the name of the records array is\n\"collections\"."
            type: string
            default: records
          records:
            type: array
            description: 'An array of records that are part of this catalog that

              are encoded in-line within the catalog object.

              The items schema is intentionally general (i.e. object)

              to accomodate records that have been extended beyond

              the core record schema.'
            items:
              type: object
          links:
            type: array
            items:
              $ref: '#/components/schemas/link'
          linkTemplates:
            type: array
            items:
              $ref: '#/components/schemas/linkTemplate'
          defaultSortOrder:
            $ref: '#/components/schemas/defaultSortOrder'
          schemes:
            type: array
            description: A list of schemes used in this context.
            items:
              $ref: '#/components/schemas/scheme'
    catalog:
      allOf:
      - $ref: '#/components/schemas/f-collection'
      - $ref: '#/components/schemas/catalogCommonProperties'
      - type: object
        properties:
          itemType:
            description: 'If this catalog is a homogenous collection

              of records then itemType is a string of fixed

              value of record.

              If this catalog is a homogenous collection

              of other catalogs then itemType is a string of

              fixed value of catalog.

              If this catalog is a heterogenous collection

              of records and catalogs then itemType is a array

              indicated that item types of the members of this

              collections (i.e. record and/or catalog).'
            oneOf:
            - type: string
              enum:
              - record
              - catalog
            - type: array
              items:
                type: string
                enum:
                - record
                - catalog
    format:
      type: object
      anyOf:
      - required:
        - name
      - required:
        - mediaType
      properties:
        name:
          type: string
        mediaType:
          type: string
    theme:
      type: object
      required:
      - concepts
      - scheme
      properties:
        concepts:
          type: array
          description: 'One or more entity/concept identifiers from this knowledge

            system. it is recommended that a resolvable URI be used for

            each entity/concept identifier.'
          minItems: 1
          items:
            type: object
            required:
            - id
            properties:
              id:
                type: string
                description: An identifier for the concept.
              title:
                type: string
                description: A human readable title for the concept.
              description:
                type: string
                description: A human readable description for the concept.
              url:
                type: string
                format: uri
                description: A URI providing further description of the concept.
        scheme:
          type: string
          description: 'An identifier for the knowledge organization system used

            to classify the resource.  It is recommended that the

            identifier be a resolvable URI.  The list of schemes used

            in a search

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ogc/refs/heads/main/openapi/ogc-collection-api-openapi.yml