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 searchable catalog can be determined by inspecting the server''s OpenAPI document or, if the server implements CQL2, by exposing a queryable (e.g. named `scheme`) and enumerating the list of schemes in the queryable''s schema definition.' securitySchemes: openIdConnect: type: openIdConnect openIdConnectUrl: https://accounts.google.com/.well-known/openid-configuration x-refined-from: - 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