Showing preview only (559K chars total). Download the full file or copy to clipboard to get everything.
Repository: radiantearth/stac-api-spec
Branch: release/v1.0.0
Commit: 604ade6158de
Files: 80
Total size: 532.3 KB
Directory structure:
gitextract_tuehb0n8/
├── .circleci/
│ ├── .spectral-fragments.yml
│ ├── .spectral.yml
│ ├── build-openapi.sh
│ ├── config.yml
│ └── publish.js
├── .github/
│ └── pull_request_template.md
├── .gitignore
├── .nvmrc
├── .remarkignore
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── PRINCIPLES.md
├── README.md
├── build/
│ ├── index.html
│ ├── redoc_index.html
│ └── swagger-config.yaml
├── core/
│ ├── README.md
│ ├── commons.yaml
│ └── openapi.yaml
├── extensions.md
├── fragments/
│ └── itemcollection/
│ ├── README.md
│ ├── examples/
│ │ ├── itemcollection-sample-full.json
│ │ └── itemcollection-sample-minimal.json
│ └── openapi.yaml
├── implementation.md
├── item-search/
│ ├── README.md
│ ├── examples.md
│ └── openapi.yaml
├── ogcapi-features/
│ ├── README.md
│ ├── openapi-collections.yaml
│ └── openapi-features.yaml
├── overview.md
├── package.json
├── stac-api.gv
└── stac-spec/
├── .circleci/
│ ├── config.yml
│ ├── publish-schemas.js
│ └── rc.yaml
├── .github/
│ └── pull_request_template.md
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── STAC-UML.drawio
├── best-practices.md
├── catalog-spec/
│ ├── README.md
│ ├── catalog-spec.md
│ └── json-schema/
│ └── catalog.json
├── collection-spec/
│ ├── README.md
│ ├── collection-spec.md
│ └── json-schema/
│ └── collection.json
├── examples/
│ ├── README.md
│ ├── catalog.json
│ ├── collection-only/
│ │ ├── collection-with-schemas.json
│ │ └── collection.json
│ ├── collection.json
│ ├── collectionless-item.json
│ ├── core-item.json
│ ├── extended-item.json
│ ├── extensions-collection/
│ │ ├── collection.json
│ │ └── proj-example/
│ │ └── proj-example.json
│ └── simple-item.json
├── extensions/
│ └── README.md
├── item-spec/
│ ├── README.md
│ ├── common-metadata.md
│ ├── item-spec.md
│ └── json-schema/
│ ├── basics.json
│ ├── datetime.json
│ ├── instrument.json
│ ├── item.json
│ ├── licensing.json
│ └── provider.json
├── overview.md
├── package.json
├── principles.md
└── process.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .circleci/.spectral-fragments.yml
================================================
extends: "spectral:oas"
rules:
openapi-tags: off
info-contact: off
oas3-api-servers: off
oas3-unused-component: off
operation-operationId: off
oas3-parameter-description: true
================================================
FILE: .circleci/.spectral.yml
================================================
extends: "spectral:oas"
rules:
oas3-api-servers: off
oas3-schema: warn
tag-description: true
oas3-parameter-description: true
================================================
FILE: .circleci/build-openapi.sh
================================================
#!/bin/bash
PATH=./node_modules/.bin:$PATH
# find all OpenAPI docs that are not fragments
FINS=(core/openapi.yaml item-search/openapi.yaml ogcapi-features/openapi-collections.yaml ogcapi-features/openapi-features.yaml)
FOUTS=(core item-search collections ogcapi-features)
for i in "${!FINS[@]}"; do
fout=./build/${FOUTS[$i]}/openapi.yaml
mkdir -p "${fout%/*}"
openapi bundle --ext yaml --output "${fout}" "${FINS[$i]}"
cp build/redoc_index.html "${fout%/*}"/index.html
done
================================================
FILE: .circleci/config.yml
================================================
version: 2.1
references:
restore_repo: &restore_repo
restore_cache:
keys:
- v0-repo-{{ .Branch }}-{{ .Revision }}
- v0-repo-{{ .Branch }}
- v0-repo
restore_dependencies: &restore_dependencies
restore_cache:
keys:
- v0-dependencies-{{ checksum "package.json"}}
- v0-dependencies
restore_build: &restore_build
restore_cache:
keys:
- v0-build-{{ .Branch }}-{{ .Revision }}
jobs:
validate:
working_directory: ~/stac
docker:
- image: cimg/node:16.14
steps:
- checkout
- save_cache:
key: v0-repo-{{ .Branch }}-{{ .Revision }}
paths:
- ~/stac
- run:
name: install
command: npm install
- save_cache:
key: v0-dependencies-{{ checksum "package.json"}}
paths:
- ~/stac/node_modules
- run:
name: validate
command: npm run check
build:
working_directory: ~/stac
docker:
- image: cimg/node:16.14
steps:
- *restore_repo
- *restore_dependencies
- run:
name: build openapi
command: npm run build-openapi
- save_cache:
key: v0-build-{{ .Branch }}-{{ .Revision }}
paths:
- ~/stac/build
publish:
working_directory: ~/stac
docker:
- image: cimg/node:16.14
steps:
- *restore_repo
- *restore_dependencies
- *restore_build
- add_ssh_keys
- run:
name: publish
command: |
ssh-keyscan github.com >> ~/.ssh/known_hosts
npm run publish-openapi -- $CIRCLE_TAG
check-core-changes:
working_directory: ~/stac
docker:
- image: cimg/node:16.14
steps:
- *restore_repo
- *restore_dependencies
- run:
name: check-core-changes
command: npm run check-stac-spec-changes --compare-to=<< pipeline.git.base_revision >>
workflows:
version: 2
ci:
jobs:
- validate:
filters:
tags:
only: /^v.*/
- build:
requires:
- validate
filters:
tags:
only: /^v.*/
- check-core-changes:
requires:
- validate
filters:
tags:
only: /^v.*/
- publish:
requires:
- build
filters:
tags:
only: /^v.*/
branches:
# Only main branch, not PRs
only: main
================================================
FILE: .circleci/publish.js
================================================
const ghpages = require('gh-pages');
let args = process.argv.slice(2);
let tag = 'main';
if (args.length && args[0].trim().length > 0) {
tag = args[0];
}
ghpages.publish('build/', {
src: '**',
dest: tag,
message: 'Publish JSON Schemas [ci skip]',
user: {
name: 'STAC CI',
email: 'ci@stacspec.org'
}
}, error => {
console.error(error ? error : 'Deployed to gh-pages');
process.exit(error ? 1 : 0);
});
================================================
FILE: .github/pull_request_template.md
================================================
**Related Issue(s):**
- #
**Proposed Changes:**
1.
2.
**PR Checklist:**
- [ ] This PR has **no** breaking changes.
- [ ] This PR does not make any changes to the core spec in the `stac-spec` directory (these are included as a subtree and should be updated directly in [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec))
- [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-api-spec/blob/main/CHANGELOG.md) **or** a CHANGELOG entry is not required.
================================================
FILE: .gitignore
================================================
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# nyc test coverage
.nyc_output
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
# Typescript v1 declaration files
typings/
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variables file
.env
# next.js build output
.next
# IntelliJ IDEA files
.idea/
*.iml
================================================
FILE: .nvmrc
================================================
16
================================================
FILE: .remarkignore
================================================
/CHANGELOG.md
/CODE_OF_CONDUCT.md
================================================
FILE: CHANGELOG.md
================================================
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [v1.0.0] - 2023-04-24
None
## [v1.0.0-rc.4] - 2023-04-13
## Changed
- Field `type` is no longer required for all Link objects, but is instead strongly
recommended. This was added as a requirement in 1.0.0-rc.3 based on a mis-reading
of the OGC Features spec, and is now removed as a requirement.
## [v1.0.0-rc.3] - 2023-03-27
## Changed
- Browseable has been moved to an extension, now located at <https://github.com/stac-api-extensions/browseable>
- Link relation `parent` is no longer a required link for Collections or Items
- Field `type` is now required for all Link objects
## Added
- Added authentication status code recommendations.
- Added extension field to all OpenAPI specifications `x-conformance-classes` indicating the
conformance classes they define.
- STAC API - Item Search now requires a `root` link relation in the response from `/search`
- Added a `collection` link from and Item to its Collection to conform with the STAC spec.
### Fixed
- Item Search `limit` parameter semantics have been changed again to align with the current OAFeat definition, rather than the inconsistent definition in [version 1.0](http://www.opengis.net/doc/IS/ogcapi-features-1/1.0). The new behavior is that if a client requests a limit value above the maximum advertised by the server, that the server should treat the request as if the limit parameter were the maximum value. It must not respond with a error because the the limit value, and must respond with no more than that many items.
## [v1.0.0-rc.2] - 2022-11-01
### Added
- Added optional `numberMatched` and `numberReturned` fields to ItemCollection to align with OGC Commons
and OAFeat.
### Changed
- The Collections specification has been incorporated into the *Features* specification, but remains as
a separate conformance class.
- The Browseable specification has been incorporated into the *Core* specification, but remains as
a separate conformance class.
- Extensions moved to standalone specification repositories:
- [Items and Collections API Version](https://github.com/stac-api-extensions/version)
- [Fields](https://github.com/stac-api-extensions/fields)
- [Filter](https://github.com/stac-api-extensions/filter)
- [Context](https://github.com/stac-api-extensions/context)
- [Sort](https://github.com/stac-api-extensions/sort)
- [Transaction](https://github.com/stac-api-extensions/transaction)
- [Query](https://github.com/stac-api-extensions/query)
- [Children](https://github.com/stac-api-extensions/children)
### Fixed
- Item Search `limit` parameter semantics now align with OAFeat. The server must not return more Items than the limit and a limit value higher than advertised in the
service description must return a 400 Bad Request status code.
## [v1.0.0-rc.1] - 2022-03-17
### Added
- The CQL2 Accent and Case-insensitive Comparison
(`http://www.opengis.net/spec/cql2/1.0/conf/accent-case-insensitive-comparison`) conformance class
adds the ACCENTI and CASEI functions for case-insensitive comparison. These replace the UPPER and
LOWER psuedo-functions that were previously part of the Advanced Comparison Operators class.
### Changed
- Query Extension is no longer deprecated.
- Children conformance class now requires the /children endpoint includes all child catalogs or collections
referenced via `child` link relations from the Landing Page
- Clarified behavior of Transaction Extension endpoints:
- PUT and PATCH of a body that changes the `collection` or `id` is disallowed.
- POST, PUT, and PATCH do not need to include the `collection` attribute, as it should be derived from the URL.
- POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which
the server can derive a valid Item, e.g., by populating the id and collection fields or adding links
- Likewise, POST can be used with a body of a FeatureCollection that contains features that meet the same constraints.
- Specifications now use the term "must" instead of "shall". The semantics of these words are identical.
- Conformance class for Item Search Filter is now
`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`, whereas before it was incorrectly stated as
`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`
### Deprecated
### Removed
### Fixed
## [v1.0.0-beta.5] - 2022-01-14
### Added
- Added `STAC API - Browseable` conformance class
- Added `STAC API - Children` conformance class
- Added description of how to support both search and browse in an API.
- The paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used
for the STAC API - Features endpoint `/collections/{collection_id}/items`, as described in OAFeat.
- The paging mechanism via a Link with rel `next` or `prev` as defined for items can also be used
for the STAC API - Features and STAC API - Collections endpoint `/collections`.
### Changed
- Limit parameter semantics now match OAFeat. Previously, the behavior was not precisely defined.
- Filter Extension updates to align with changes to OAFeat CQL2 spec
- Updated all "CQL" usages to "CQL2"
- Most conformance class URIs are now prefixed with `http://www.opengis.net/spec/cql2/` instead
of `http://www.opengis.net/spec/ogcapi-features-3/`
- Conformance classes `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/basic-cql`,
`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-text`, and
`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-json` have had `cql` replaced
with `cql2` (in addition to the prefix change) to
become `http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2`,
`http://www.opengis.net/spec/cql2/1.0/conf/cql2-text`, and
`http://www.opengis.net/spec/cql2/1.0/conf/cql2-json`
- Significant changes to CQL2 JSON format, now using `op` and `args` structure
- Spatial operator `INTERSECTS` is now `S_INTERSECTS`
- Temporal operator `ANYINTERACTS` is now `T_INTERSECTS`
- Updated Example 3 (now Example 5) to make it clear that property to property comparisons require the
Property-Property Comparisons conformance class
- The CQL2 Case-insensitive Comparison
(`http://www.opengis.net/spec/cql2/1.0/conf/case-insensitive-comparison`) conformance class
that adds UPPER/LOWER terms or function CASEI for case-insensitive comparison has not been added
to this spec yet, since the definition in CQL2 is in flux.
- `service-desc` endpoint may return any service description format, typically a
machine-consumable one (previous restricted required to be OpenAPI 3.0 JSON)
- `service-doc` endpoint may return any service description format, typically a
human-consumable one (previous restricted required to be HTML)
### Deprecated
### Removed
### Fixed
- Collection conformance class URI should be `https://api.stacspec.org/v1.0.0-beta.XXX/collections` instead
of `http://stacspec.org/spec/api/1.0.0-beta.XXX/extensions/collections`
- definition of Item object was missing `properties` as an attribute
- Filter Extension - examples of using intervals and timestamps in CQL2 were incorrect and have been fixed
- Filter Extension - examples are updated so that text and json examples are equivalent
## [v1.0.0-beta.4] - 2021-10-05
### Added
- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
endpoint (`/collections/{collectionId}/items`)
- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
- In Item Search, added endpoint table
### Changed
- Filter Extension - query language is now referred to as "CQL2" rather than CQL
- Filter Extension now uses OAFeat Part 3 conformance class URIs
- Filter Extension - The following changes have been made to the Filter Extension conformance classes to align with changes to the OAFeat CQL draft. All classes
whose names have changed also have changed conformance URI strings.
- "Basic CQL" now includes the "not equal" operator (`<>`)
- "Basic CQL" has always supported datetime comparisons, but this is now explicitly mentioned
- "Enhanced Comparison Operators" has been renamed "Advanced Comparison Operators". This is the same as the OAFeat CQL definition, except
that it does not require the `upper` and `lower` functions.
- "Enhanced Spatial Operators" has been renamed to just "Spatial Operators" (not to be confused with Basic Spatial Operators)
- "Basic Temporal Operators" and "Enhanced Temporal Operators" have merged into "Temporal Operators"
- "Functions" has been renamed "Custom Functions"
- "Arithmetic" has been renamed "Arithmetic Expressions"
- "Arrays" has been renamed "Array Operators"
- "Queryable Second Operand" has been renamed "Property-Property Comparisons"
- The required Link Relations and endpoints for each conformance class now use the wording of 'shall'
instead of 'should'. While this technically changes the semantics, it was generally understood
previously the semantics were those of 'shall' (must).
- Explicitly state that the `/children` endpoint can return Catalog and Collection objects that have fewer
fields than are available through other endpoints.
### Deprecated
### Removed
### Fixed
## [v1.0.0-beta.3] - 2021-08-06
### Added
- Added STAC API - Collections definition (subset of STAC API - Features)
- More thorough definitions for valid `datetime` and `bbox` query parameter values.
### Changed
- Query extension not deprecated; recommendation to use Filter (<https://github.com/radiantearth/stac-api-spec/pull/157>)
- Filter Extension conformance classes refactored to better align with STAC API use cases.
- Renamed conformance class "Queryable First Operand"
(<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand>) to
"Queryable Second Operand"
(<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-second-operand>)
### Deprecated
### Removed
- Remove stac_version and stac_extensions fields in ItemCollection
### Fixed
## [v1.0.0-beta.2] - 2021-06-01
### Added
- Added Filter extension to integrate OAFeat Part 3 CQL
- Catalog and Collection definitions now have required field "type"
- Added recommendation to enable CORS for public APIs
### Changed
- Updated all STAC versions to 1.0.0
- Passing the `ids` parameter to an item search does not deactivate other query parameters [#125](https://github.com/radiantearth/stac-api-spec/pull/125)
- The first extent in a Collection is always the overall extent, followed by more specific extents. [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520)
### Deprecated
- Query extension is now deprecated. Replaced by the Filter extension using OGC CQL.
### Removed
### Fixed
- Updated text description of root ('/') endpoint (also called landing page) that the return type is a Catalog
## [v1.0.0-beta.1] - 2020-12-10
### Added
- The landing page returns the conformance classes in a property `conformsTo`, which mirrors `GET /conformances` from OGC APIs.
- Conformance classes for all the major functionality and extensions, to be referenced in a new `conformsTo` JSON object in the landing page.
- Fragments: reusable OpenAPI documents for sort, filter, fields and context, along with explanation of how they work.
- ItemCollection moved from [STAC Core](https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/itemcollection-spec.md) to this repo.
### Changed
- Major re-organization of the content and directory structure to make better conformance classes.
- STAC API Core is the landing page (a STAC catalog and conformance information).
- Item Search is the `search` cross-collection item search resource.
- STAC API - Features is the OGC API - Features standards to be used in a STAC API.
- Extensions are specified in the relevant functionality directory, though they can share openapi yaml's in the 'fragments' directory.
- Updated to STAC specification version 1.0.0-beta.2
- Named explicit supported STAC core versions to be from 0.9.0 up to (and not including) 2.0.0
- Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute
- Added root endpoint Link `search` must have `type` of `application/geo+json`
- Corrected the description of endpoint `/collections` to say it returns an object per OAFeat, instead of an array of Collection
- Updated transaction extension so it aligns with OGC API - Features Part 4: Simple Transactions
### Deprecated
### Removed
### Fixed
- BBOX openapi yaml to only allow 4 or 6 element arrays
- Fixed invalid OpenAPI files
## Older versions
See the [stac-spec CHANGELOG](https://github.com/radiantearth/stac-spec/blob/v0.9.0/CHANGELOG.md)
for STAC API releases prior to or equal to version 0.9.0.
[Unreleased]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0...main>
[v1.0.0]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0>
[v1.0.0-rc.4]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.4>
[v1.0.0-rc.3]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3>
[v1.0.0-rc.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2>
[v1.0.0-rc.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1>
[v1.0.0-beta.5]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5>
[v1.0.0-beta.4]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.4>
[v1.0.0-beta.3]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.3>
[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.2>
[v1.0.0-beta.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1>
================================================
FILE: CITATION.cff
================================================
cff-version: 1.2.0
message: "If you are referring to the STAC API specification in your publications, please cite it as below."
type: software
title: "SpatioTemporal Asset Catalog (STAC) API specification"
authors:
- name: "STAC API Contributors"
preferred-citation:
type: standard
title: "SpatioTemporal Asset Catalog (STAC) API specification"
abstract: "An API to make geospatial assets openly searchable and crawlable."
version: v1.0.0
year: 2023
date-released: 2023-04-24
license: Apache-2.0
url: https://stacspec.org
repository: https://github.com/radiantearth/stac-api-spec
authors:
- name: "STAC API Contributors"
email: stac-psc@radiant.earth
================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of
any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address,
without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com).
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of
actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the
community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations
================================================
FILE: CONTRIBUTING.md
================================================
## Contributing
Pull Requests are the primary method of contributing to the spec itself, and everyone is welcome to submit
changes. Suggestions for changes to the core will be taken with higher priority if a clear implementation
of STAC API has been built that can highlight the problem.
We consider everyone using the specification to catalog their data to be a 'contributor', as STAC is
really about the end result of more interoperable data, not just creating a spec for the sake of it.
So if you want to help then the best thing you can do is make new catalogs or build software that uses
the spec. And please do give us feedback. The best place to do so is on our
[gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). If you are interested in helping
but aren't sure where to, then see the [stac-ecosystem](https://github.com/stac-utils/stac-ecosystem) repo
for ideas on projects to advance STAC.
## Development Process
The SpatioTemporal Asset Catalog API specification is under active development.
The `main` branch is a place of active development,
where a new change in one part of the spec might not yet be fully updated everywhere else. Releases are tagged. The team uses the
[stac-api-spec issue tracker](https://github.com/radiantearth/stac-api-spec/issues) to identify and track all that will be done for
a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and
examples.
### Submitting Pull Requests
Any proposed changes to the specification should be done as pull requests. Please make these
requests against the [main](https://github.com/radiantearth/stac-api-spec/tree/main) branch.
Creating a Pull Request will show our PR template, which includes checkbox reminders for a number
of things, including adding an entry the [CHANGELOG](CHANGELOG.md) and making the PR against the `main`
branch.
All pull requests should submit clean markdown, which is checked by the continuous integration
system. Please use `npm run check` locally, as described in the [next section](#check-files),
to ensure that the checks on the pull request succeed. If it does not then you can look at the
mistakes online, which are the same as running `npm run check` locally would surface.
All pull requests that modify or create JSON schema files or examples should use
[JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo.
All pull requests additionally require a review of two STAC core team members. Releases are cut
from main and require 3 approvals.
### Check files
The same check-markdown and check-openapi programs that runs as a check on PR's is part of the repo and can be run locally.
To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).
Any recent version of node/npm should work.
If using nvm, run `nvm install`.
Install the dependencies with npm:
```bash
npm install
```
Then to do the check for markdown and examples you run:
```bash
npm run check
```
This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.
To just check the markdown, run:
```bash
npm run check-markdown
```
To just validate the OpenAPI definitions, run:
```bash
npm run check-openapi
```
### Working with the OpenAPI files
The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is
contained within several YAML files in the various directories. These live in the same place as the markdown defining
various parts of the specification. Currently we expect developers to be up to speed with
OpenAPI and using their own tools to modify things. In the future we will provide tools to make it easier to work with.
There are html version of the OpenAPI files online at `https://api.stacspec.org/{version_number}` with `{version_number}` being the git tag or `dev`.
Often, updating
the JSON Schema and OpenAPI files is one of the harder aspects of creating a change, so please, don't
hesitate to ask for help in doing this!
## Release Process
To release a new version of the STAC spec the following list of tasks must be done.
- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github
issue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not
need to be completed, but the core release team should all review the issues to make sure that the critical ones for the
release have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no
open issues against the milestone.
- **Check dependencies**: STAC relies on OGC API - Features and STAC Core specifications at its core, and will likely rely
on additional Features API extensions as well as OGC API - Commons. We aim to always reference the latest version of these,
so before releasing we should check to make sure we are on the latest stable versions, and upgrade if it makes sense. We include
the latest stable STAC core spec version as a 'submodule', so before release we should update that to be the latest.
- **Agreement from core team**: The core STAC API team should meet (on video or on gitter) and decided that the release is ready.
This should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep
with a coherent whole.
- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense
and there are no typos, errors, etc.
- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements
in the release. And anything in 'unreleased' section should move to the version of the spec to be released.
- **Check Online API Docs**: Check to make sure the online API docs reflect the release at <https://api.stacspec.org/>
(this step may go away once we are confident this works well, as this publishing is in flux)
- **Release on Github**: The final step to create the release is to add a new 'release' on
<https://github.com/radiantearth/stac-api-spec/releases>. This should use a tag like the others, with a 'v' prefix and then the
release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to
the full milestone of everything closed in the issue tracker.
- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel
to post / promote it.
### Release Candidates
Before any release that has *major* changes (made as a judgement call by the core contributors) there should be a 'release
candidate' to ensure the wider community of implementors can try it out
and catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec
version is good, so this step is essential if there are major changes. The release should proceed as normal, but called
vX.Y.Z-RC.1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations
should be updated to the new specification before there is a real release. And ideally an API client is also
updated. This provides the core sanity check. If there are changes or fixes to the spec or
schemas needed from their feedback then make fixes and do RC2. If it is just fixes to the examples or tooling then no
additional RC is needed. After there is no more changes to spec or schemas then the release process should be done on `main`,
with no changes to the spec - just updating the version numbers.
## Governance
The STAC API spec follows the same governance as the [core STAC spec](https://github.com/radiantearth/stac-spec/blob/master/process.md#governance).
================================================
FILE: LICENSE
================================================
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "{}"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright {yyyy} {name of copyright owner}
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
================================================
FILE: PRINCIPLES.md
================================================
This project will be governed by a set of informal core principles. These principles are not set in stone,
and indeed they should evolve in the same manner that all specifications worked on should - proposed and
reviewed in pull requests, approved by consensus. The goal of the principles is to help avoid
[bikeshedding](http://bikeshed.org/) - lay down some meta-rules so we can focus on creating useful
core geospatial standards.
- **Creation and evolution of specs in Github**, using Open Source principles
(please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you).
The collaboration facilities of Github should be used to their full extent. All proposed improvements and
changes should come in the form of pull requests, using code review functionality to discuss changes.
- **Alignment with OGC standards** - The Open Geospatial Consortium publishes a large set of geospatial standards.
To the greatest extent possible, the STAC API should align with existing and in-progress OGC API standards. The
STAC API has a symbiotic relationship with these standards, as it seeks both to reuse their building blocks and
push them forward in a practical direction. Among the most important of these are:
- [OGC API - Common](https://ogcapi.ogc.org/common/)
- [OGC API - Features](https://ogcapi.ogc.org/features/), particularly [OGC API - Features - Part 1: Core](http://docs.ogc.org/is/17-069r3/17-069r3.html)
- [OGC API - Records](https://ogcapi.ogc.org/records/)
- [Common Query Language (CQL2)](https://docs.ogc.org/DRAFTS/21-065.html), formerly part of OGC
API - Features - Part 3: Filtering and the Common Query Language (CQL)
- **Web API using JSON + HTTP at the core.** JSON has won over XML, and resource-centric over SOAP. We embrace them and
are not considering legacy options. Forward looking protocols can be considered as extensions,
but the default specifications should be in JSON, following best web API practices. HTTP caching and
error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,
so it should also be core. As STAC APIs follow a resource-centric, hypermedia-driven model, a core principal
is the use of HTTP Request Methods ("verbs") and the `Content-Type` header to drive behavior on resources ("nouns").
- **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible,
defining one core concept and refraining from describing lots of options. Additional options can be made
as separate specifications that build on the core. But the core specs should be small and easily understandble,
with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces.
Implementors should not be forced to implement lots of options just for basic compliance - they should be
able to pick and choose which pieces are relevant to the problems they are trying to solve.
- **Specify in OpenAPI 3.0 (formerly known as Swagger) specification.** All web interfaces should be
specified in [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).
This enables generation of live documentation, client libraries and test engines, and makes the spec less ambiguous.
Accompanying human readable specifications should be available in github and auto-built in to html.
- **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice
should be considered with a developer audience. And specifications should be accessible to developers who do not
have geospatial background. A developer should not need to understand 'projections' to implement a simple feature
access service. But we should think through the spec extensions they could use in the future when their client asks
for data in a different projection.
- **Working code required.** Proposed changes should be accompanied by working code
(ideally with a link to an online service running the code). A reference implementation should be available
online to power the interactive documentation. Both core conformance classes and extensions follow the
[Maturity Classification](README.md#maturity-classification) model.
- **Design for scale.** The design should work great with more data than can be imagined right now.
Ideally implementations are built with large test data sets to validate that they will work.
Everything should be compatible with content distribution network (CDN) caching.
## Resources
- Open Source Principles - [Producing Open Source Software](http://producingoss.org) by Karl Fogel.
- Best Practices JSON API Design - [JSON API](http://jsonapi.org/) best practices for making API's with JSON
- Pragmatic REST - [Web API Design: Crafting interfaces that developers love](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf)
- Open API Initiative - [OpenAPIs.org](https://openapis.org/)
================================================
FILE: README.md
================================================
<!--lint disable no-html-->
<img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" alt="stac-logo" width="700"/>
# STAC API Foundation Specifications
- [STAC API Foundation Specifications](#stac-api-foundation-specifications)
- [Releases (stable)](#releases-stable)
- [Development (unstable)](#development-unstable)
- [About](#about)
- [Stability Note](#stability-note)
- [Maturity Classification](#maturity-classification)
- [Communication](#communication)
- [In this repository](#in-this-repository)
- [Contributing](#contributing)
## Releases (stable)
- [v1.0.0](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0) (latest)
- [v1.0.0-rc.4](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.4)
- [v1.0.0-rc.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3)
- [v1.0.0-rc.2](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2)
- [v1.0.0-rc.1](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1)
- [v1.0.0-beta.5](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5)
- [v1.0.0-beta.4](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.4)
- [v1.0.0-beta.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.3)
- [v1.0.0-beta.2](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.2)
- [v1.0.0-beta.1](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1)
- [v0.9.0](https://github.com/radiantearth/stac-api-spec/tree/v0.9.0)
## Development (unstable)
The [main](https://github.com/radiantearth/stac-api-spec/tree/main) branch in GitHub is
used for active development and may be unstable. Implementers should reference one of
the release branches above for a stable version of the specification.
**NOTE**: This means that if you are on github.com/radiantearth/stac-api-spec then you are looking at an unreleased,
unstable version of the specification. Use the first listed link on releases to read the current released, stable version
of the spec.
## About
The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried.
A 'spatiotemporal asset' is any file that represents information about the Earth captured in a certain space and
time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
A STAC API is a dynamic version of a SpatioTemporal Asset Catalog. This repository defines the three
STAC API foundation specifications -- [STAC API - Core](core/),
[STAC API - Features](ogcapi-features/), and [STAC API - Item Search](item-search/) -- which can be composed
with [Extensions](extensions.md) to define a specific STAC API implementation.
A STAC API can be used to retrieve STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md),
[Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md),
or STAC API [ItemCollection](fragments/itemcollection/README.md) objects from various endpoints.
Catalog and Collection objects are JSON, while Item and ItemCollection objects are GeoJSON-compliant entities with foreign members.
Typically, a Feature is used when returning a single Item object, and FeatureCollection when multiple Item objects (rather than a
JSON array of Item entities).
The API can be implemented in compliance with the *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)* standard
(OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API
to search STAC catalogs, where the features returned are STAC [Item](stac-spec/item-spec/item-spec.md) objects,
that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
The specification for STAC API is provided as files that follow the [OpenAPI](http://openapis.org/) 3.0 specification,
rendered online into HTML at <https://api.stacspec.org/v1.0.0>, in addition to human-readable documentation.
## Stability Note
This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is
currently in a 'beta' state, with no major changes anticipated.
As of v1.0.0, we remain fully aligned with
[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)
Version 1.0, and we are working to stay aligned
as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API
specification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking change
will require the spec to go to 2.0.0.
## Maturity Classification
Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states
in terms of stability and number of implementations. All extensions must include a
maturity classification, so that STAC API spec users can easily get a sense of how much they can count
on the extension.
| Maturity Classification | Min Impl # | Description | Stability |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback |
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. |
| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | Will not be updated and may be removed in an upcoming major release. |
Maturity mostly comes through diverse implementations, so the minimum number of implementations
column is the main gating function for an extension to mature. But extension authors can also
choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
the less breaking changes of the next level.
A 'mature' classification level will likely be added once there are extensions that have been
stable for over a year and are used in twenty or more implementations.
## Communication
For any questions feel free to jump on our [gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby) or email
our [google group](https://groups.google.com/forum/#!forum/stac-spec). The majority of communication about the evolution of
the specification takes place in the [issue tracker](https://github.com/radiantearth/stac-api-spec/issues) and in
[pull requests](https://github.com/radiantearth/stac-api-spec/pulls).
## In this repository
The **[Overview](overview.md)** document describes all the various parts of the STAC API and how they fit together.
**STAC API - Core:**
The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and
retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.
**STAC API - Features:**
The *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API -
Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of
each STAC collection. It also includes extensions that can be used to further enhance OAFeat.
**STAC API - Item Search Specification:**
The *[item-search](item-search)* folder contains the Item Search specification, which enables
cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions.
**Extensions:**
The *[extensions](extensions.md) document* describes how STAC adds new functionality
through extensions. The official list of STAC API Extensions
is maintained at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).
**Fragments:**
The *[fragments/](fragments/)* folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI
schemas and parameters for behavior like sorting and filtering. Most all of them are compatible with
OGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations.
OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.
**STAC Specification:** This repository includes a '[sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules)', which
is a copy of the [STAC specification](stac-spec/) tagged at the latest stable version.
Sub-modules aren't checked out by default, so to get the directory populated
either use `git submodule update --init --recursive` if you've already cloned it,
or clone from the start with `git clone --recursive git@github.com:radiantearth/stac-api-spec.git`.
**Implementation Recommendations:** Recommendations for implementing a STAC API may be found [here](implementation.md).
These are mostly concerns that apply to an entire API implementation and are not part of the specification itself.
## Contributing
Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate.
Beforehand, please review our [guidelines for contributions and development process](CONTRIBUTING.md).
================================================
FILE: build/index.html
================================================
<!DOCTYPE html>
<html>
<head>
<title>STAC API</title>
<!-- needed for adaptive design -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
<h1>STAC API</h1>
<h2>Conformance Classes</h2>
<ul>
<li><a href="core/">STAC API - Core</a></li>
<li><a href="item-search/">STAC API - Item Search</a></li>
<li><a href="ogcapi-features/">STAC API - Features</a></li>
<li><a href="collections/">STAC API - Collections</a></li>
</ul>
</body>
</html>
================================================
FILE: build/redoc_index.html
================================================
<!DOCTYPE html>
<html>
<head>
<title>STAC API</title>
<!-- needed for adaptive design -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc
spec-url='openapi.yaml'
expandResponses='200,201,202,203,204'
pathInMiddlePanel='true'
hideDownloadButton='true'
></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
================================================
FILE: build/swagger-config.yaml
================================================
openapi: 3.0.3
info:
title: STAC API - Complete
version: 1.0.0-rc.2
apis:
- url: 'build/core/openapi.yaml'
paths:
exclude:
- "^\/$"
- url: 'build/item-search/openapi.yaml'
- url: 'build/ogcapi-features/openapi.yaml'
- url: 'build/ogcapi-features/extensions/version/openapi.yaml'
- url: 'build/ogcapi-features/extensions/transaction/openapi.yaml'
================================================
FILE: core/README.md
================================================
# STAC API - Core Specification
- [STAC API - Core Specification](#stac-api---core-specification)
- [Summary](#summary)
- [Overview](#overview)
- [Core](#core)
- [Link Relations](#link-relations)
- [Endpoints](#endpoints)
- [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core)
- [Extensions](#extensions)
## Summary
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/core)),
- **Conformance URIs:**
- <https://api.stacspec.org/v1.0.0/core>
- **[Maturity Classification](../README.md#maturity-classification):** Candidate
- **Dependencies**: None
and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
## Overview
All STAC API implementations must implement the *STAC API - Core* conformance class
<https://api.stacspec.org/v1.0.0/core>. This requires a server to return from a root endpoint a valid
[STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) "landing page" that also includes a `conformsTo`
attribute with a string array value. Any API implementing this is considered a minimal, valid STAC API.
## Core
The root of a STAC API is the Landing Page, which is a STAC Catalog object with additional fields.
This resource is the starting point to determine what behaviors
the API supports via the `conformsTo` array and the URIs of resources via link relations.
Support for this type of behavior in a web API is known as
[Hypermedia as the Engine of Application State (HATEOAS)](https://en.wikipedia.org/wiki/HATEOAS).
A hypermedia-driven web API provides a robust, consistent, and flexible mechanism for interacting with remote resources.
STAC API relies heavily on hypermedia for API resource discovery and navigation.
In a STAC API, the root endpoint (Landing Page) has the following characteristics:
- The returned JSON is a [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md), and provides any number of 'child' links
to navigate to additional [Catalog](../stac-spec/catalog-spec/catalog-spec.md),
[Collection](../stac-spec/collection-spec/README.md), and [Item](../stac-spec/item-spec/README.md) objects.
- The `links` attribute is part of a STAC Catalog, and provides a list of relations to API endpoints. Some of these endpoints can
exist on any path (e.g., sub-catalogs) and some have a specified path (e.g., `/search`),
so the client must inspect the `rel` (relationship) to understand what capabilities are offered at each location.
- The `conformsTo` section provides the capabilities of this service. This is the field
that indicates to clients that this is a STAC API and how to access conformance classes, including this
one. The relevant conformance URIs are listed in each part of the API specification. If a conformance URI is listed then
the service must implement all of the required capabilities.
Note the `conformsTo` array follows the same structure of the OGC API - Features [declaration of conformance
classes](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes), except it is part of the
landing page instead of in the JSON response from the `/conformance` endpoint. This is different from how the OGC API advertises
conformance, as STAC feels it is important for clients
to understand conformance from a single request to the landing page. Implementers who implement the *OGC API - Features* and/or
[STAC API - Features](../ogcapi-features/README.md) conformance classes must also implement the `/conformance` endpoint.
The scope of the conformance classes declared in the `conformsTo` field and the `/conformance` endpoint are limited
to the STAC API Catalog that declares them. A STAC API Catalog may link to sub-catalogs within it via `child` links
that declare different conformance classes. This is useful when an entire catalog cannot be searched against to
support the *STAC API - Item Search* conformance class, perhaps because it uses multiple databases to store items,
but sub-catalogs whose items are all in one database can support search.
## Link Relations
The STAC definition of Link does not require the `type` field,
but it is **STRONGLY RECOMMENDED** that this field exists.
If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.
The following Link relations are defined for the Landing Page (root).
| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------------- | ----------- | -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Core | **REQUIRED** The root URI |
| `self` | `/` | application/json | OAFeat | **REQUIRED** Self reference, same as root URI |
| `service-desc` | `/api` | various | OAFeat | **REQUIRED** The service description in a machine-readable format |
| `service-doc` | `/api.html` | text/html | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |
| `child` | various | application/json | STAC API - Core | The child STAC Catalogs & Collections. |
| `item` | various | application/geo+json | STAC API - Core | The child STAC Items. |
The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be
OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML),
`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1`
(3.1 JSON).
A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML
page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API
, but any format is allowed. The Link `type` field should correspond to whatever format or formats are
supported by this endpoint, e.g., `text/html`.
Additionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These
relations form a directed graph that enables traversal from a root catalog or collection to items.
While it is valid to have `item` links from the landing page, most STAC API implementations
serve large numbers of features, so they will typically use several layers of intermediate `child` links to sub-catalogs and collections before
getting to Item objects. These relations form a directed graph
of Catalogs and Collections, where interior nodes contain `child` relations, and the penultimate nodes will be
Catalogs with `item` relations to individual Items as leaf nodes.
`child` link relations may point to another STAC Catalog that *also* acts as a STAC API root, which can support
search over only a sub-catalog. This is useful for very large or federated catalogs that cannot support searching
over the entire catalog, but can support searching over individual sub-catalogs within it.
Note that there is a different link relation `items` (plural)
used by the [STAC API - Features](../ogcapi-features/README.md) conformance class that links from a collection resource
(at the `/collections/{collectionId}` endpoint) to the items in
that collection (at the `/collections/{collectionId}/items` endpoint). Both of these endpoints are
[derived from OGC API - Features](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_).
## Endpoints
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml).
| **Endpoint** | **Media Type** | **Returns** | **Description** |
| ------------ | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities |
| `/api` | various | any | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. |
The service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1
with media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON),
or `application/vnd.oai.openapi+json;version=3.1` (3.1 JSON). Whichever format or formats are used, the link
with relation `service-desc` must have a `type` field that matches an `Accept` header value to which the service
responds, and the `Content-Type` header in the response should contain the same media type. If the OpenAPI 3.0
format is used, the conformance class `http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30` should be
advertised. All service descriptions provided as part of the STAC API spec use OpenAPI 3.0 YAML format, and can
easily be used to return either YAML or JSON from this endpoint. OAFeat does not currently define a conformance
class for OpenAPI 3.1, but may in the future.
## Example Landing Page for STAC API - Core
This JSON is what would be expected from an API that only implements *STAC API - Core*. It is a valid STAC Catalog
with additional Links and a `conformsTo` attribute. In practice,
most APIs will also implement other conformance classes, and those will be reflected in the `links` and
`conformsTo` attribute. A more typical Landing Page example is in
the [overview](../overview.md#example-landing-page) document.
This particular catalog provides both the ability to browse down to child Catalog objects through its
`child` links, and also provides the search endpoint to be able to search across items in its collections. Note
that some of those links are not required and other servers may provide
different conformance classes and a different set of links.
```json
{
"stac_version": "1.0.0",
"id": "example-stac",
"title": "A simple STAC API Example",
"description": "This Catalog aims to demonstrate a simple landing page",
"type": "Catalog",
"conformsTo" : [
"https://api.stacspec.org/v1.0.0/core"
],
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stac-api.example.com/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stac-api.example.com/api.html"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/catalogs/sentinel-2"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/catalogs/landsat-8"
}
]
}
```
## Extensions
STAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).
================================================
FILE: core/commons.yaml
================================================
openapi: 3.0.3
info:
title: The SpatioTemporal Asset Catalog API - Commons
description: This is the OpenAPI version of the core STAC spec JSON Schemas.
version: v1.0.0
paths: {}
components:
responses:
Error:
description: An error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/exception"
schemas:
exception:
type: object
description: |-
Information about the exception: an error code plus an optional description.
required:
- code
properties:
code:
type: string
description:
type: string
conformanceClasses:
type: object
required:
- conformsTo
properties:
conformsTo:
description: >-
A list of all conformance classes implemented by the server.
In addition to the STAC-specific conformance classes, all OGC-related
conformance classes listed at `GET /conformance` must be listed here.
This entry should mirror what `GET /conformance` returns, if implemented.
type: array
items:
type: string
catalog:
type: object
required:
- stac_version
- type
- id
- description
- links
properties:
stac_version:
$ref: "#/components/schemas/stac_version"
stac_extensions:
$ref: "#/components/schemas/stac_extensions"
type:
type: string
enum:
- Catalog
id:
type: string
title:
type: string
description:
type: string
links:
$ref: "#/components/schemas/links"
collection:
type: object
required:
- stac_version
- type
- id
- description
- license
- extent
- links
properties:
stac_version:
$ref: "#/components/schemas/stac_version"
stac_extensions:
$ref: "#/components/schemas/stac_extensions"
type:
type: string
enum:
- Collection
id:
description: identifier of the collection used, for example, in URIs
type: string
title:
description: human readable title of the collection
type: string
description:
type: string
description: >-
Detailed multi-line description to fully explain the catalog or
collection.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
rich text representation.
keywords:
type: array
description: List of keywords describing the collection.
items:
type: string
license:
$ref: "#/components/schemas/license"
extent:
$ref: "#/components/schemas/extent"
providers:
$ref: "#/components/schemas/providers"
links:
$ref: "#/components/schemas/links"
summaries:
description: |-
Summaries are either a unique set of all available values *or*
statistics. Statistics by default only specify the range (minimum
and maximum values), but can optionally be accompanied by additional
statistical values. The range can specify the potential range of
values, but it is recommended to be as precise as possible. The set
of values must contain at least one element and it is strongly
recommended to list all values. It is recommended to list as many
properties as reasonable so that consumers get a full overview of
the Collection. Properties that are covered by the Collection
specification (e.g. `providers` and `license`) may not be repeated
in the summaries.
type: object
additionalProperties:
oneOf:
- type: array
title: Set of values
items:
description: A value of any type.
- type: object
title: Statistics
description: |-
By default, only ranges with a minimum and a maximum value can
be specified. Ranges can be specified for ordinal values only,
which means they need to have a rank order. Therefore, ranges
can only be specified for numbers and some special types of
strings. Examples: grades (A to F), dates or times.
Implementors are free to add other derived statistical values
to the object, for example `mean` or `stddev`.
required:
- min
- max
properties:
min:
anyOf:
- type: string
- type: number
max:
anyOf:
- type: string
- type: number
example:
stac_version: "1.0.0"
stac_extensions: []
type: Collection
id: Sentinel-2
title: "Sentinel-2 MSI: MultiSpectral Instrument, Level-1C"
description: |
Sentinel-2 is a wide-swath, high-resolution, multi-spectral
imaging mission...
license: proprietary
keywords:
- copernicus
- esa
- eu
- msi
- radiance
- sentinel
providers:
- name: ESA
roles:
- producer
- licensor
url: "https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi"
extent:
spatial:
bbox:
- - -180
- -56
- 180
- 83
temporal:
interval:
- - "2015-06-23T00:00:00Z"
- "2019-07-10T13:44:56Z"
summaries:
datetime:
min: "2015-06-23T00:00:00Z"
max: "2019-07-10T13:44:56Z"
"sci:citation":
- "Copernicus Sentinel data [Year]"
"eo:gsd":
- 10
- 30
- 60
"platform":
- sentinel-2a
- sentinel-2b
"constellation":
- sentinel-2
"instruments":
- msi
"view:off_nadir":
min: 0
max: 100
"view:sun_elevation":
min: 6.78
max: 89.9
"eo:bands":
- - name: B1
common_name: coastal
center_wavelength: 4.439
- name: B2
common_name: blue
center_wavelength: 4.966
- name: B3
common_name: green
center_wavelength: 5.6
- name: B4
common_name: red
center_wavelength: 6.645
- name: B5
center_wavelength: 7.039
- name: B6
center_wavelength: 7.402
- name: B7
center_wavelength: 7.825
- name: B8
common_name: nir
center_wavelength: 8.351
- name: B8A
center_wavelength: 8.648
- name: B9
center_wavelength: 9.45
- name: B10
center_wavelength: 1.3735
- name: B11
common_name: swir16
center_wavelength: 1.6137
- name: B12
common_name: swir22
center_wavelength: 2.2024
links:
- rel: self
href: "http://cool-sat.com/collections/Sentinel-2"
type: application/json
- rel: root
href: "http://cool-sat.com/collections"
type: application/json
- rel: license
href: "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf"
title: Legal notice on the use of Copernicus Sentinel Data and Service Information
type: application/pdf
extent:
type: object
description: |-
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.
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 item in each array.
required:
- spatial
- temporal
properties:
spatial:
description: |-
The spatial extent of the features in the collection.
type: object
required:
- bbox
properties:
bbox:
description: |-
One or more bounding boxes that describe the spatial extent of the dataset.
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 item in each 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)
The coordinate reference system of the values 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`.
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
minItems: 4
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 this is the only supported coordinate reference system.
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"
default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
temporal:
description: |-
The temporal extent of the features in the collection.
type: object
required:
- interval
properties:
interval:
description: |-
One or more time intervals that describe the temporal extent of the dataset.
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 extent will only need
to access the first item in each array.
type: array
minItems: 1
items:
description: |-
Begin and end times of the time interval. The timestamps
are in the coordinate reference system specified in `trs`. By default
this is the Gregorian calendar.
The value `null` is supported and indicates an open time 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 reference system.
Extensions may support additional temporal 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"
links:
type: array
items:
$ref: "#/components/schemas/link"
link:
title: Link
type: object
required:
- href
- rel
properties:
href:
type: string
format: uri
description: The location of the resource
rel:
type: string
description: Relation type of the link
type:
type: string
description: The media type of the resource
title:
type: string
description: Title of the resource
method:
type: string
enum:
- GET
- POST
default: GET
description: Specifies the HTTP method that the resource expects
headers:
type: object
description: Object key values pairs they map to headers
example:
Accept: application/json
body:
type: object
description: For POST requests, the resource can specify the HTTP body as a JSON object.
merge:
type: boolean
default: false
description: |-
This is only valid when the server is responding to POST request.
If merge is true, the client is expected to merge the body value
into the current request body before following the link.
This avoids passing large post bodies back and forth when following
links, particularly for navigating pages through the `POST /search`
endpoint.
NOTE: To support form encoding it is expected that a client be able
to merge in the key value pairs specified as JSON
`{"next": "token"}` will become `&next=token`.
license:
type: string
description: |-
License(s) of the data as a SPDX
[License identifier](https://spdx.org/licenses/). Alternatively, use
`proprietary` if the license is not on the SPDX license list or
`various` if multiple licenses apply. In these two cases links to the
license texts SHOULD be added, see the `license` link relation type.
Non-SPDX licenses SHOULD add a link to the license text with the
`license` relation in the links section. The license text MUST NOT be
provided as a value of this field. If there is no public license URL
available, it is RECOMMENDED to host the license text and
link to it.
example: Apache-2.0
providers:
type: array
description: >-
A list of providers, which may include all organizations capturing or
processing the data or the hosting provider. Providers should be listed
in chronological order with the most recent provider being the last
element of the list.
items:
type: object
title: Provider
required:
- name
properties:
name:
description: The name of the organization or the individual.
type: string
description:
description: >-
Multi-line description to add further provider information such as
processing details for processors and producers, hosting details
for hosts or basic contact information.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
rich text representation.
type: string
roles:
description: |-
Roles of the provider.
The provider's role(s) can be one or more of the following
elements:
* licensor: The organization that is licensing the dataset under
the license specified in the collection's license field.
* producer: The producer of the data is the provider that
initially captured and processed the source data, e.g. ESA for
Sentinel-2 data.
* processor: A processor is any provider who processed data to a
derived product.
* host: The host is the actual provider offering the data on their
storage. There should be no more than one host, specified as last
element of the list.
type: array
items:
type: string
enum:
- producer
- licensor
- processor
- host
url:
description: >-
Homepage on which the provider describes the dataset and publishes
contact information.
type: string
format: url
bbox:
description: |-
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 (elevation or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Lower left corner, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Upper right corner, coordinate axis 3 (optional)
The coordinate reference system of the values is WGS84
longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
For WGS84 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 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.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.
type: array
minItems: 4
maxItems: 6
items:
type: number
example:
- -110
- 39.5
- -105
- 40.5
datetime:
type: string
format: date-time
nullable: true
description: |-
The searchable date and time of the assets, in UTC.
It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
`null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.
example: "2018-02-12T00:00:00Z"
stac_version:
title: STAC version
type: string
example: 1.0.0
stac_extensions:
title: STAC extensions
type: array
uniqueItems: true
items:
anyOf:
- title: Reference to a JSON Schema
type: string
format: uri
- title: Reference to a core extension
type: string
item:
description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- stac_version
- id
- type
- geometry
- bbox
- links
- properties
- assets
properties:
stac_version:
$ref: "#/components/schemas/stac_version"
stac_extensions:
$ref: "#/components/schemas/stac_extensions"
id:
$ref: "#/components/schemas/itemId"
bbox:
$ref: "#/components/schemas/bbox"
geometry:
$ref: "#/components/schemas/geometryGeoJSON"
type:
$ref: "#/components/schemas/itemType"
links:
$ref: "#/components/schemas/links"
properties:
$ref: "#/components/schemas/properties"
assets:
$ref: "#/components/schemas/assets"
example:
stac_version: "1.0.0"
stac_extensions:
- "https://stac-extensions.github.io/eo/v1.0.0/schema.json"
- "https://stac-extensions.github.io/view/v1.0.0/schema.json"
- "https://example.com/cs-extension/1.0/schema.json"
type: Feature
id: CS3-20160503_132131_05
bbox:
- -122.59750209
- 37.48803556
- -122.2880486
- 37.613537207
geometry:
type: Polygon
coordinates:
- - - -122.308150179
- 37.488035566
- - -122.597502109
- 37.538869539
- - -122.576687533
- 37.613537207
- - -122.2880486
- 37.562818007
- - -122.308150179
- 37.488035566
properties:
datetime: "2016-05-03T13:22:30.040Z"
title: A CS3 item
license: PDDL-1.0
providers:
- name: CoolSat
roles:
- producer
- licensor
url: "https://cool-sat.com/"
"view:sun_azimuth": 168.7
"eo:cloud_cover": 0.12
"view:off_nadir": 1.4
"platform": coolsat2
"instruments":
- cool_sensor_v1
"eo:bands": []
"view:sun_elevation": 33.4
"eo:gsd": 0.512
collection: CS3
links:
- rel: self
href: "http://cool-sat.com/collections/CS3/items/20160503_132130_04"
type: application/geo+json
- rel: root
href: "http://cool-sat.com/collections"
type: application/json
- rel: parent
href: "http://cool-sat.com/collections/CS3"
type: application/json
- rel: collection
href: "http://cool-sat.com/collections/CS3"
type: application/json
assets:
analytic:
href: "http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif"
title: 4-Band Analytic
type: image/tiff; application=geotiff; profile=cloud-optimized
thumbnail:
href: "http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png"
title: Thumbnail
type: image/png
itemId:
type: string
description: Provider identifier, a unique ID.
itemType:
type: string
description: The GeoJSON type
enum:
- Feature
properties:
type: object
required:
- datetime
description: provides the core metadata fields plus extensions
properties:
datetime:
$ref: "#/components/schemas/datetime"
additionalProperties:
description: Any additional properties added in via Item specification or extensions.
assets:
type: object
additionalProperties:
type: object
required:
- href
properties:
href:
type: string
format: url
description: Link to the asset object
example: >-
http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
title:
type: string
description: Displayed title
example: Thumbnail
description:
type: string
description: >-
Multi-line description to explain the asset.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
rich text representation.
example: Small 256x256px PNG thumbnail for a preview.
type:
type: string
description: Media type of the asset
example: image/png
roles:
type: array
items:
type: string
description: Purposes of the asset
example:
- thumbnail
geometryGeoJSON:
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"
geometrycollectionGeoJSON:
type: object
required:
- type
- geometries
properties:
type:
type: string
enum:
- GeometryCollection
geometries:
type: array
items:
$ref: "#/components/schemas/geometryGeoJSON"
linestringGeoJSON:
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:
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
multipointGeoJSON:
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: number
multipolygonGeoJSON:
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
pointGeoJSON:
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Point
coordinates:
type: array
minItems: 2
items:
type: number
polygonGeoJSON:
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
featureCollectionGeoJSON:
type: object
required:
- type
- features
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: "#/components/schemas/featureGeoJSON"
featureGeoJSON:
type: object
required:
- type
- geometry
- properties
properties:
type:
type: string
enum:
- Feature
geometry:
$ref: "#/components/schemas/geometryGeoJSON"
properties:
type: object
nullable: true
================================================
FILE: core/openapi.yaml
================================================
openapi: 3.0.3
info:
title: STAC API - Core
version: v1.0.0
description: >-
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core
specification. Any service that implements this endpoint to allow discovery of
spatiotemporal assets can be considered a STAC API.
contact:
name: STAC Specification
url: "http://stacspec.org"
license:
name: Apache License 2.0
url: "http://www.apache.org/licenses/LICENSE-2.0"
x-conformance-classes: ["https://api.stacspec.org/v1.0.0/core"]
tags:
- name: Core
description: essential characteristics of a STAC API
paths:
"/":
get:
tags:
- Core
summary: landing page
description: |-
Returns the root STAC Catalog or STAC Collection that is the entry point
for users to browse with STAC Browser or for search engines to crawl.
This can either return a single STAC Collection or more commonly a STAC
catalog.
The landing page provides links to the
API definition (link relations `service-desc` and `service-doc`)
and the STAC records such as collections/catalogs (link relation `child`)
or items (link relation `item`).
Extensions may add additional links with new relation types.
operationId: getLandingPage
responses:
"200":
$ref: "#/components/responses/LandingPage"
"4XX":
$ref: "commons.yaml#/components/responses/Error"
"5XX":
$ref: "commons.yaml#/components/responses/Error"
components:
schemas:
landingPage:
allOf:
- $ref: "commons.yaml#/components/schemas/catalog"
- $ref: "commons.yaml#/components/schemas/conformanceClasses"
responses:
LandingPage:
description: |-
The landing page provides links to the API definition
(link relations `service-desc` and `service-doc`).
content:
application/json:
schema:
$ref: "#/components/schemas/landingPage"
example:
type: Catalog
stac_version: "1.0.0"
id: sentinel
title: Copernicus Sentinel Imagery
description: Catalog of Copernicus Sentinel 1 and 2 imagery.
conformsTo:
- "https://api.stacspec.org/v1.0.0/core"
links:
- href: "http://data.example.org/"
rel: self
type: application/json
title: this document
- href: "http://data.example.org/api"
rel: service-desc
type: application/vnd.oai.openapi+json;version=3.0
title: the API definition
- href: "http://data.example.org/api.html"
rel: service-doc
type: text/html
title: the API documentation
- href: "http://data.example.org/catalogs/sentinel-1"
rel: child
type: application/json
title: Sentinel 1 Catalog
- href: "http://data.example.org/catalogs/sentinel-2"
rel: child
type: application/json
title: Sentinel 2 Catalog
================================================
FILE: extensions.md
================================================
# STAC API Extensions
STAC API aims to define a core of functionality, with richer capabilities enabled by extensions. The list of
STAC API Extensions is maintained at **<https://stac-api-extensions.github.io>**.
This document explains the process of creating and maturing an extension.
Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged
to add the extension to the [official list](https://stac-api-extensions.github.io) by creating an issue or PR
on <https://github.com/stac-api-extensions/stac-api-extensions.github.io>.
All extensions must include a [maturity classification](README.md#maturity-classification), so that STAC API
specification users can easily get a sense of how much they can count on the extension.
## Extensions and Conformance
Each extension has its own conformance class, which is specified with one or more **conformance URIs**
that are defined for the extension. These must be listed in the `conformsTo` JSON of the Landing Page,
as specified by [STAC API - Core](core/), to let clients know that they can use the functionality.
A number of extensions define functionality that could be used easily in a number of endpoints, such
as additional parameters for search through either **STAC API - Item Search** or **STAC API - Features**.
## Creating new extensions
Creating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives
an overview of the functionality. In the README, a conformance URI should be provided, so clients can use it to tell if
a service has the indicated functionality. It is also recommended to note the 'extension maturity', as defined above,
so others can know how widely it is used.
The new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes.
The first step in sharing the extension is to add it to the official list, as described above. If it is of something
that the wider community may be interested in, then it may be added to the
[stac-api-extensions](https://github.com/stac-api-extensions) GitHub organization.
================================================
FILE: fragments/itemcollection/README.md
================================================
# STAC API - ItemCollection Fragment
This document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) ItemCollection.
An **ItemCollection** is a [GeoJSON](http://geojson.org/) [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3)
that is augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC entity.
Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection must be a valid GeoJSON
FeatureCollection to allow interoperability with existing tools that support GeoJSON.
Item objects are represented in JSON format and are very flexible. Any JSON object that contains all the
required fields is a valid STAC ItemCollection.
- Examples:
- See the [minimal example](examples/itemcollection-sample-minimal.json), as well as a [more complete
example](examples/itemcollection-sample-full.json). There are more real world inspired samples in the [examples/](examples/) folder.
- [OpenAPI YAML](openapi.yaml)
## ItemCollection fields
This object describes a STAC ItemCollection. The fields `type` and `features` are inherited from GeoJSON FeatureCollection.
| Field Name | Type | Description |
| -------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| type | string | **REQUIRED.** Always "FeatureCollection" to provide compatibility with GeoJSON. |
| features | \[[STAC Item](../../stac-spec/item-spec/item-spec.md)] | **REQUIRED.** A possibly-empty array of Item objects. |
| links | \[[Link Object](../../stac-spec/item-spec/item-spec.md#link-object)] | An array of Links related to this ItemCollection. |
| numberMatched | integer | The number of Items that meet the selection parameters, possibly estimated. |
| numberReturned | integer | The number of Items in the `features` array. |
## Extensions
STAC API Extensions can be found [here](https://stac-api-extensions.github.io).
================================================
FILE: fragments/itemcollection/examples/itemcollection-sample-full.json
================================================
{
"type": "FeatureCollection",
"numberMatched": 10,
"numberReturned": 1,
"features": [
{
"stac_version": "1.0.0",
"stac_extensions": [],
"type": "Feature",
"id": "cs3-20160503_132131_05",
"bbox": [
-122.59750209,
37.48803556,
-122.2880486,
37.613537207
],
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-122.308150179,
37.488035566
],
[
-122.597502109,
37.538869539
],
[
-122.576687533,
37.613537207
],
[
-122.288048600,
37.562818007
],
[
-122.308150179,
37.488035566
]
]
]
},
"properties": {
"datetime": "2016-05-03T13:22:30.040Z",
"title": "A CS3 item",
"license": "PDDL-1.0",
"providers": [
{
"name": "CoolSat",
"roles": [
"producer",
"licensor"
],
"url": "https://stac-api.example.com"
}
]
},
"collection": "cs3",
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com/collections/cs3/items/CS3-20160503_132131_05"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com/"
},
{
"rel": "collection",
"type": "application/json",
"href": "https://stac-api.example.com/collections/cs3"
}
],
"assets": {
"analytic": {
"href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/analytic.tif",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"title": "4-Band Analytic"
},
"thumbnail": {
"href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/thumbnail.png",
"type": "image/png",
"title": "Thumbnail",
"roles": [
"thumbnail"
]
}
}
}
],
"links": [
{
"rel": "root",
"href": "http://stac.example.com/",
"type": "application/json"
}
]
}
================================================
FILE: fragments/itemcollection/examples/itemcollection-sample-minimal.json
================================================
{
"type": "FeatureCollection",
"features": []
}
================================================
FILE: fragments/itemcollection/openapi.yaml
================================================
openapi: 3.0.3
info:
title: The SpatioTemporal Asset Catalog API - Item Collection
description: The specification for a set of items, e.g. returned by a search.
version: v1.0.0
paths: {}
components:
schemas:
itemCollection:
description: >-
A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- features
- type
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: "../../core/commons.yaml#/components/schemas/item"
links:
type: array
description: >-
An array of links. Can be used for pagination, e.g. by providing a link
with the `next` relation type.
items:
$ref: "../../core/commons.yaml#/components/schemas/link"
example:
- rel: next
type: application/geo+json
href: >-
http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
numberMatched:
type: integer
minimum: 0
numberReturned:
type: integer
minimum: 0
================================================
FILE: implementation.md
================================================
# Implementation Recommendations
This document describes implementation recommendations for a STAC API.
## Identifiers
It is recommended that all items presented through a STAC API be part of a collection. STAC
allows items to not be contained in a collection, though this is rarely done in practice.
For each STAC Item, the Collection ID and Item ID must for a globally-unique tuple, e.g., item IDs are unique within a collection.
## CORS
Web browsers enforce a mechanism called [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to prevent
malicious access to APIs. It is recommended that public STAC APIs advertise a permissive [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
configuration so browser-based UIs running on a different domain may more easily access them.
APIs should acknowledge pre-flight request headers. In general, these header values should be set on responses:
```
access-control-allow-origin: *
access-control-allow-methods: OPTIONS, POST, GET
access-control-allow-headers: Content-Type
```
It is relatively safe to use these headers for all endpoints. However, one may want to restrict the methods to
only those that apply to each endpoint. For example, the `/collection/{collectionId}/items` endpoint should
only allow OPTIONS and GET, since POST is only used by the Transactions Extension, which presumably would
require authentication as it is mutating data.
Implementations that support the Transactions Extension or require credentials for some operations will need to
implement different behavior, for example, allowing credentials when requests are coming from a trusted domain,
allowing DELETE, PUT, or PATCH methods, or
permitting the `If-Match` request header.
## datetime Parameter Handling
The datetime parameter used by the Item Search and Features conformance classes allows the same values as the
[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for
either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`)
or a closed or single open ended interval that also uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`).
RFC 3339 is a profile of ISO 8601, adding these constraints to the allowed values:
- a complete representation of date and time (fractional seconds optional).
- requires 4-digit years
- only allows a period character to be used as the decimal point for fractional seconds
- requires the zone offset to be `Z` or like `+00:00`, while ISO8601 allows timezones like `+0000`
A simple regex for an RFC 3339 datetime is:
```regex
^(\d\d\d\d)\-(\d\d)\-(\d\d)(T|t)(\d\d):(\d\d):(\d\d)([.]\d+)?(Z|([-+])(\d\d):(\d\d))$
```
This is not a precise regex, as it matches some strings that violate semantics. There are additional restrictions, for example,
the month (01-12), the day (01-31), the hour (0-24), minute (0-60), seconds (0-9), and timezone offsets. However, the best
strategy is to use this regex to ensure the datetime conforms to the RFC 3339 profile and then us an ISO8601 parser to produce
a valid datetime object from the datetime string.
Thereby, the recommended process for parsing the datetime value (which may consist of a single
RFC 3339 datetime or an interval) is:
1. uppercase the string (this avoids needing to match on both (t|T) and (z|Z))
2. split the string on `/` to determine if it is a single datetime or an interval
3. For the single value or each value of the split, check if it is either an open interval
(the empty string or `..`), or a datetime value. Only one of the interval ends may be open.
4. Either use an RFC 3339 datetime parser like in [ciso8601](https://github.com/closeio/ciso8601), or
match the datetime value against the RFC 3339 regex, upper case the string, and use an
ISO8601 parser such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python) or
[Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into
language standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in
Python datetime library does not handle `Z` as a timezone.
Below are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, the use of `.`
as the fractional seconds separator, Z (recommended) or z as a timezone,
positive and negative arbitrary offset timezones, and T (recommended) or t as a separator between date and time. While
the RFC 3339 spec does not define the required number of fractional seconds, STAC API only requires up to
9 digits be supported.
- 1990-12-31T23:59:59Z (no fractional seconds, Z timezone)
- 1990-12-31T23:59:23.123Z (fractional seconds, Z timezone)
- 1996-12-19T16:39:57-08:00 (no fractional seconds, negative offset timezone)
- 1937-01-01T12:00:27.87+01:00 (fractional seconds, positive offset timezone)
- 1985-04-12t23:20:50.5202020z (lowercase t for separator, lowercase z for timezone)
These are several examples of datetime intervals:
- `/1990-12-31T23:59:59Z`
- `/1990-12-31T23:59:59Z`
- `../1990-12-31T23:59:59Z`
- `1990-12-31T23:59:59Z/`
- `1990-12-31T23:59:59Z/..`
- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z`
## Authentication Status Codes
When authentication is applied to a STAC API, it is recommended the following status codes be returned:
- 401 when no or invalid authentication information is provided
- 403 when valid authentication information is provided, but the principal does not have access (permissions)
on the requested resource
================================================
FILE: item-search/README.md
================================================
# STAC API - Item Search
- [STAC API - Item Search](#stac-api---item-search)
- [Summary](#summary)
- [Overview](#overview)
- [Link Relations](#link-relations)
- [Endpoints](#endpoints)
- [Query Parameters and Fields](#query-parameters-and-fields)
- [Query Examples](#query-examples)
- [Query Parameter Table](#query-parameter-table)
- [Response](#response)
- [Pagination](#pagination)
- [HTTP Request Methods and Content Types](#http-request-methods-and-content-types)
- [GET](#get)
- [POST](#post)
- [PUT / PATCH / DELETE](#put--patch--delete)
- [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search)
- [Extensions](#extensions)
## Summary
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/item-search))
- **Conformance URIs:**
- <https://api.stacspec.org/v1.0.0/item-search>
- **[Maturity Classification](../README.md#maturity-classification):** Candidate
- **Dependencies**: [STAC API - Core](../core)
- **Examples**: [examples.md](examples.md)
## Overview
The *STAC API - Item Search* specification defines the *STAC API - Item Search*
conformance class (<https://api.stacspec.org/v1.0.0/item-search>), which
provides the ability to search for STAC [Item](../stac-spec/item-spec/README.md)
objects across collections.
It retrieves a group of Item objects that match the provided parameters, wrapped in an
[ItemCollection](../fragments/itemcollection/README.md) (which is a
valid [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that contains STAC Item objects). Several core
query parameters are defined by [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), with
a few additions specified in this document.
The Item Search endpoint intentionally defines only a limited group of operations. It is expected that
most behavior will be defined in [Extensions](#extensions). These extensions can be composed by an implementer to
cover only the set of functionality the implementer requires. For example, the query capability defined by
Item Search is limited, and only adds cross-collection and spatial intersects query operators to the capabilities
already defined by OAFeat. For example, the Query Extension and Filter Extension
provide a more expressive set of operators.
Implementing `GET /search` is **required**, `POST /search` is optional, but recommended.
## Link Relations
The STAC definition of Link does not require the `type` field,
but it is **STRONGLY RECOMMENDED** that this field exists.
If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.
This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
The following Link relations are defined for the Landing Page (root).
| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------- | --------- | -------------------- | ---------------------- | ---------------------------------------- |
| `search` | `/search` | application/geo+json | STAC API - Item Search | **REQUIRED** URI for the Search endpoint |
This `search` link relation must have a `type` of `application/geo+json`. If no `method` attribute is
specified, it is assumed to represent a GET request. If the server supports both GET and POST requests, two links should be included, one with a `method` of `GET` one with a `method` of `POST`.
Other links with relation `search` may be included that advertise other content types the server may respond
with, but these other types are not part of the STAC API requirements.
The following Link relations are defined for the `/search` endpoint response.
| **rel** | **href** | **From** | **Description** |
| ------- | -------- | ---------------------- | ------------------------- |
| `root` | `/` | STAC API - Item Search | **REQUIRED** The root URI |
## Endpoints
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
| **Endpoint** | **Returns** | **Media Type** | **From** | **Description** |
| ------------ | --------------- | -------------------- | ---------------------- | --------------- |
| `/search` | Item Collection | application/geo+json | STAC API - Item Search | Search endpoint |
## Query Parameters and Fields
The following list of parameters is used to narrow search queries. They can all be represented as query
string parameters in a GET request, or as JSON entity fields in a POST request. For filters that represent
a set of values, query parameters must use comma-separated string values with no enclosing brackets
(\[ or \]) and no whitespace between values, and JSON entity attributes must use JSON Arrays.
### Query Examples
```
GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit=200&datetime=2017-05-05T00:00:00Z
```
```json
{
"collections": ["landsat8","sentinel"],
"bbox": [-10.415,36.066,3.779,44.213],
"limit": 200,
"datetime": "2017-05-05T00:00:00Z"
}
```
For more examples see [examples.md](examples.md).
### Query Parameter Table
The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience.
| **Parameter** | **Type** | **Source API** | **Description** |
| ------------- | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit | integer | OAFeat | The maximum number of results to return (page size). |
| bbox | \[number] | OAFeat | Requested bounding box. |
| datetime | string | OAFeat | Single date+time, or a range ('/' separator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Use double dots `..` for open date ranges. |
| intersects | GeoJSON Geometry | STAC | Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported. |
| ids | \[string] | STAC | Array of Item ids to return. |
| collections | \[string] | STAC | Array of one or more Collection IDs that each matching Item must be in. |
See [examples](examples.md) for some example requests.
**limit** The limit parameter follows the same semantics of the OAFeat Item resource limit parameter. The value is
a suggestion to the server as to the maximum number of Item objects the
client would prefer in the response. The server may return fewer Item objects, but
must not return more. The OpenAPI specification defines the default and maximum values
for this parameter. The base specifications define these with a default of 10 and a maximum of 10000, but implementers
may choose other values to advertise through their `service-desc` endpoint. If the limit parameter value is greater
than the advertised maximum limit, the server must act as if the request were for the maximum
and not return an error.
**datetime** The datetime parameter use the same allowed values as the
[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter.
This allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an
open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be
found in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling).
Only one of either **intersects** or **bbox** may be specified. If both are specified, a 400 Bad Request status code
must be returned.
**bbox** Represented using either 2D or 3D geometries. The length of the array must be 2\*n where
*n* is the number of dimensions. The array contains all axes of the southwesterly most extent
followed by all axes of the northeasterly most extent specified in Longitude/Latitude or
Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84).
When using 3D geometries, the elevation of the southwesterly most extent is the minimum elevation
in meters and the elevation of the northeasterly most extent is the maximum. When filtering with
a 3D bbox over Items with 2D geometries, it is assumed that the 2D geometries are at
elevation 0. Degenerate bboxes that form a point or line must be supported.
**intersects** It is at the discretion of the implementation to reject semantically-invalid
GeoJSON objects, e.g., a self-intersecting Polygon or a LineString with zero-length segments.
These should result in a 400 Bad Request status code and a specific error message, rather than
a 500 Server Error and generic or database-level error message.
## Response
The response to a request (GET or POST) to the search endpoint must always be an
[ItemCollection](../fragments/itemcollection/README.md) object - a valid [GeoJSON
FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that consists entirely of STAC
[Item](../stac-spec/item-spec/item-spec.md) objects.
### Pagination
OGC API supports paging through hypermedia links and STAC follows the same pattern for the cross collection search. For
GET requests, a link with `rel` type `next` is supplied. This link may contain any URL parameter that is necessary
for the implementation to understand how to provide the next page of results, eg: `page`, `next`, `token`, etc. The
parameter name is defined by the implementor and is not necessarily part of the API specification. For example:
```json
{
"type": "FeatureCollection",
"features": [],
"links": [
{
"rel": "next",
"href": "https://stac-api.example.com/search?page=3",
"type": "application/geo+json"
},
{
"rel": "prev",
"href": "https://stac-api.example.com/search?page=1",
"type": "application/geo+json"
},
{
"rel": "root",
"href": "https://stac-api.example.com/",
"type": "application/json"
}
]
}
```
The href may contain any arbitrary URL parameter:
- `https://stac-api.example.com/search?page=2`
- `https://stac-api.example.com/search?next=8a35eba9c`
- `https://stac-api.example.com/search?token=f32890a0bdb09ac3`
Implementations may also add link relations `prev`, `first`, and `last`, though these are not required and may
be infeasible to implement in some data stores.
OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed
for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has
decided to extend the Link object to support additional fields that provide hints to the client as to how it must
execute a subsequent request for the next page of results.
The following fields have been added to the Link object specification for the API spec:
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` |
| headers | object | A dictionary of header values that must be included in the next request |
| body | object | A JSON object containing fields/values that must be included in the body of the next request |
| merge | boolean | If `true`, the headers/body fields in the `next` link must be merged into the original request and be sent combined in the next request. Defaults to `false` |
The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination
mechanism. The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page
of results is purely up to the implementor and not defined in the API spec, if the implementor decides to use headers,
there are no specific or required header names defined in the specification. Implementors may use any names or fields
of their choosing. Pagination can be provided solely through header values, solely through body values, or through some
combination.
To avoid returning the entire original request body in a POST response which may be arbitrarily large, the `merge`
property can be specified. This indicates that the client must send the same post body that it sent in the original
request, but with the specified headers/body values merged in. This allows servers to indicate what needs to change
to get to the next page without mirroring the entire query structure back to the client.
See the [paging examples](examples.md#paging-examples) for additional insight.
## HTTP Request Methods and Content Types
STAC APIs follow the modern web API practices of using HTTP Request Methods ("verbs") and
the `Content-Type` header to drive behavior on resources ("nouns").
This section describes how these are used with the `/search` endpoint.
### GET
**Required**: STAC's cross-collection `/search` requires GET queries for all implementations, following OAFeat's precedent of
making GET required (it only specifies GET so far).
### POST
**Recommended** STAC `/search` is strongly recommended to implement POST `Content-Type: application/json`, where the content body is a JSON
object representing a query and filter, as defined in this document.
It is recommended that clients use POST for querying (if the STAC API supports it), especially when using the
`intersects` query parameter, for two reasons:
1. In practice, the allowed size for an HTTP GET request is significantly less than that allowed for a POST request,
so if a large geometry is used in the query it may cause a GET request to fail.
2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON
parameters (such as intersect, as well as additional filters from the query extension).
**STAC API extensions** allow for more sophisticated searching, such as the ability to sort, select which fields you want returned, and
searching on specific Item properties.
#### PUT / PATCH / DELETE
The other HTTP verbs are not supported in STAC Item Search. The [Transaction Extension](https://github.com/stac-api-extensions/transaction)
does implement them, for STAC and OAFeat implementations that want to enable writing and deleting items.
## Example Landing Page for STAC API - Item Search
This JSON is what would be expected from an api that only implements *STAC API - Item Search*. In practice,
most APIs will also implement other conformance classes, and those will be reflected in the `links` and
`conformsTo` fields. A more typical Landing Page example is in
the [overview](../overview.md#example-landing-page) document.
```json
{
"stac_version": "1.0.0",
"id": "example-stac",
"title": "A simple STAC API Example",
"description": "This Catalog aims to demonstrate the a simple landing page",
"type": "Catalog",
"conformsTo" : [
"https://api.stacspec.org/v1.0.0/core",
"https://api.stacspec.org/v1.0.0/item-search"
],
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stac-api.example.com/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stac-api.example.com/api.html"
},
{
"rel": "search",
"type": "application/geo+json",
"href": "https://stac-api.example.com/search",
"method": "GET"
},
{
"rel": "search",
"type": "application/geo+json",
"href": "https://stac-api.example.com/search",
"method": "POST"
}
]
}
```
## Extensions
STAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).
================================================
FILE: item-search/examples.md
================================================
## Item Search Examples
### Single Collection example
This example shows how you can request Item objects from a single collection from the `search` endpoint, without having to using
OGC API - Features. It requests 100 results in `mycollection` that is in New Zealand at anytime on January 1st, 2019:
```json
{
"collections": ["mycollection"],
"bbox": [160.6,-55.95,-170,-25.89],
"limit": 100,
"datetime": "2019-01-01T00:00:00Z/2019-01-01T23:59:59Z"
}
```
```
GET /search?collections=mycollection&bbox=160.6,-55.95,-170,-25.89&limit=100&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z
```
### Paging Examples
#### Simple GET based search
Request:
```
HTTP GET /search?bbox=-110,39.5,-105,40.5
```
Response with `200 OK`:
```json
{
"type": "FeatureCollection",
"features": [],
"links": [
{
"rel": "next",
"href": "https://stac-api.example.com/search?page=2",
"type": "application/geo+json"
},
{
"rel": "root",
"href": "https://stac-api.example.com/",
"type": "application/json"
}
]
}
```
Following the link `https://stac-api.example.com/search?page=2` will send the user to the next page of results.
#### POST search with body and merge fields
Request to `HTTP POST /search`:
```json
{
"bbox": [-110, 39.5, -105, 40.5]
}
```
Response with `200 OK`:
```json
{
"type": "FeatureCollection",
"features": [],
"links": [
{
"rel": "next",
"href": "https://stac-api.example.com/search",
"type": "application/geo+json",
"method": "POST",
"body": {
"page": 2,
"limit": 10
},
"merge": true
},
{
"rel": "root",
"href": "https://stac-api.example.com/",
"type": "application/json"
}
]
}
```
This tells the client to POST to the search endpoint using the original request with the `page` and `limit` fields
merged in to obtain the next set of results:
Request to `POST /search`:
```json
{
"bbox": [-110, 39.5, -105, 40.5],
"page": 2,
"limit": 10
}
```
This can be even more effective when using continuation tokens on the server, as the entire request body need not be
repeated in the subsequent request:
Response with `200 OK`:
```json
{
"rel": "next",
"href": "https://stac-api.example.com/search",
"type": "application/geo+json",
"method": "POST",
"body": {
"next": "a9f3kfbc98e29a0da23"
}
}
```
The above link tells the client not to merge (default of false) so it is only required to pass the next token in the body.
Request to `POST /search`:
```json
{
"next": "a9f3kfbc98e29a0da23"
}
```
#### POST search using headers
Request to `HTTP POST /search`:
```json
{
"bbox": [-110, 39.5, -105, 40.5],
"page": 2,
"limit": 10
}
```
Response with `200 OK`:
```json
{
"type": "FeatureCollection",
"features": [],
"links": [
{
"rel": "next",
"href": "https://stac-api.example.com/search",
"type": "application/geo+json",
"method": "POST",
"headers": {
"Search-After": "LC81530752019135LGN00"
}
},
{
"rel": "root",
"href": "https://stac-api.example.com/",
"type": "application/json"
}
]
}
```
This tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results:
Request:
```
POST /search
Search-After: LC81530752019135LGN00
```
================================================
FILE: item-search/openapi.yaml
================================================
openapi: 3.0.3
info:
title: STAC API - Item Search
version: v1.0.0
description: >-
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Item Search
specification.
contact:
name: STAC Specification
url: "http://stacspec.org"
license:
name: Apache License 2.0
url: "http://www.apache.org/licenses/LICENSE-2.0"
tags:
- name: Item Search
description: essential characteristics of a STAC API
x-conformance-classes: ["https://api.stacspec.org/v1.0.0/item-search"]
paths:
/search:
get:
summary: Search STAC items with simple filtering.
operationId: getItemSearch
description: |-
Retrieve Items matching filters. Intended as a shorthand API for simple
queries.
This method is required to implement.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` to the
`links` array in `GET /`. As `GET` is the default method, the `method`
may not be set explicitly in the link.
tags:
- Item Search
parameters:
- $ref: "#/components/parameters/bbox"
- $ref: "#/components/parameters/intersects"
- $ref: "#/components/parameters/datetime"
- $ref: "#/components/parameters/limit"
- $ref: "#/components/parameters/ids"
- $ref: "#/components/parameters/collectionsArray"
responses:
"200":
description: A feature collection.
content:
application/geo+json:
schema:
$ref: "../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection"
text/html:
schema:
type: string
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
post:
summary: Search STAC items with full-featured filtering.
operationId: postItemSearch
description: |-
Retrieve items matching filters. Intended as the standard, full-featured
query API.
This method is optional to implement, but recommended.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` and `method`
set to `POST` to the `links` array in `GET /`.
tags:
- Item Search
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/searchBody"
responses:
"200":
description: A feature collection.
content:
application/geo+json:
schema:
$ref: "../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection"
text/html:
schema:
type: string
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
components:
parameters:
ids:
name: ids
in: query
description: |-
Array of Item ids to return.
required: false
schema:
$ref: "#/components/schemas/ids"
explode: false
collectionsArray:
name: collections
in: query
description: |
Array of Collection IDs to include in the search for items.
Only Item objects in one of the provided collections will be searched
required: false
schema:
$ref: "#/components/schemas/collectionsArray"
explode: false
datetime:
name: datetime
in: query
description: |-
Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open 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.
required: false
schema:
type: string
style: form
explode: false
bbox:
name: bbox
in: query
description: |-
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)
The coordinate reference system of the values is WGS 84
longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
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.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.
required: false
schema:
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
style: form
explode: false
limit:
name: limit
in: query
description: |-
The optional limit parameter recommends the number of items that should be present 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 must not be counted.
Minimum = 1. Maximum = 10000. Default = 10.
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 10
style: form
explode: false
intersects:
name: intersects
in: query
description: |-
The optional intersects parameter filters the result Items in the same was as bbox, only with
a GeoJSON Geometry rather than a bbox.
required: false
schema:
$ref: "../core/commons.yaml#/components/schemas/geometryGeoJSON"
style: form
explode: false
schemas:
searchBody:
description: The search criteria
type: object
allOf:
- $ref: "#/components/schemas/bboxFilter"
- $ref: "#/components/schemas/datetimeFilter"
- $ref: "#/components/schemas/intersectsFilter"
- $ref: "#/components/schemas/collectionsFilter"
- $ref: "#/components/schemas/idsFilter"
- $ref: "#/components/schemas/limitFilter"
limit:
type: integer
minimum: 1
example: 10
default: 10
maximum: 10000
description: |-
The optional limit parameter limits the number of items that are presented in the response document.
If the limit parameter value is greater than advertised limit maximum, the server must return the
maximum possible number of items, rather than responding with an error.
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 must not be counted.
Minimum = 1. Maximum = 10000. Default = 10.
bboxFilter:
type: object
description: Only return items that intersect the provided bounding box.
properties:
bbox:
$ref: "../core/commons.yaml#/components/schemas/bbox"
collectionsArray:
type: array
description: |-
Array of Collection IDs to include in the search for items.
Only Item objects in one of the provided collections will be searched.
items:
type: string
ids:
type: array
description: |-
Array of Item ids to return.
items:
type: string
datetimeFilter:
description: An object representing a date+time based filter.
type: object
properties:
datetime:
$ref: "#/components/schemas/datetime_interval"
intersectsFilter:
type: object
description: Only returns items that intersect with the provided polygon.
properties:
intersects:
$ref: "../core/commons.yaml#/components/schemas/geometryGeoJSON"
limitFilter:
type: object
description: Only returns maximum number of results (page size)
properties:
limit:
$ref: "#/components/schemas/limit"
idsFilter:
type: object
description: Only returns items that match the array of given ids
properties:
ids:
$ref: "#/components/schemas/ids"
collectionsFilter:
type: object
description: Only returns the collections specified
properties:
collections:
$ref: "#/components/schemas/collectionsArray"
datetime_interval:
type: string
description: |-
Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open 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.
example: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
================================================
FILE: ogcapi-features/README.md
================================================
# STAC API - Collections and Features Specification
- [STAC API - Collections and Features Specification](#stac-api---collections-and-features-specification)
- [Summary](#summary)
- [Overview](#overview)
- [Conformance Classes](#conformance-classes)
- [STAC API - Features](#stac-api---features)
- [STAC API - Collections](#stac-api---collections)
- [OGC API - Features - Part 1: Core](#ogc-api---features---part-1-core)
- [OGC API - Features - Part 1: GeoJSON](#ogc-api---features---part-1-geojson)
- [OGC API - Features - Part 1: OpenAPI 3.0](#ogc-api---features---part-1-openapi-30)
- [Link Relations](#link-relations)
- [Landing Page (/)](#landing-page-)
- [Collections (/collections)](#collections-collections)
- [Collection (/collections/{collectionId})](#collection-collectionscollectionid)
- [Collection Items (/collections/{collectionId}/items)](#collection-items-collectionscollectioniditems)
- [Items (/collections/{collectionId}/items/{itemId})](#items-collectionscollectioniditemsitemid)
- [Endpoints](#endpoints)
- [Item Pagination](#item-pagination)
- [Collection Pagination](#collection-pagination)
- [Examples](#examples)
- [Example Landing Page](#example-landing-page)
- [Example Collection Endpoint](#example-collection-endpoint)
- [Extensions](#extensions)
## Summary
- **OpenAPI specifications:**
- [STAC API - Features](openapi-features.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/ogcapi-features))
- [STAC API - Collections](openapi-collections.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/collections))
- **Conformance Class URIs:**
- <https://api.stacspec.org/v1.0.0/ogcapi-features> - Features
- <https://api.stacspec.org/v1.0.0/collections> - Collections
- **[Maturity Classification](../README.md#maturity-classification):** Candidate
- **Dependencies**:
- [STAC API - Core](../core)
- [OGC API - Features](https://www.ogc.org/standards/ogcapi-features)
uses all the OGC API - Features openapi fragments to describe returning STAC Item objects.
## Overview
The *STAC API - Collections and Features* specification extends the
[OGC API - Features - Part 1: Core](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html)
(OAFeat) specification. OAFeat
allows returning any content type from its endpoints, whereas *STAC API - Features* requires support
for returning STAC [Item](../stac-spec/item-spec/README.md) and STAC [Collection](../stac-spec/item-spec/README.md)
entities. As these entities are also GeoJSON types, the GeoJSON conformance class of OGC API - Features is supported
(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson>).
## Conformance Classes
While OAFeat defines a single conformance class for its endpoints, STAC API divides these behaviors into two
conformance classes -- Collections and Features. The STAC API - Features
(<https://api.stacspec.org/v1.0.0/ogcapi-features>) conformance class includes and extends the behavior
of OAFeat, while the STAC API - Collections (<https://api.stacspec.org/v1.0.0/collections>) conformance
class is the subset of Features that pertains only to Collections.
### STAC API - Features
The *STAC API - Features* (<https://api.stacspec.org/v1.0.0/ogcapi-features>) conformance class
encompasses all of the behavior described in this specification, as
derived from OAFeat.
### STAC API - Collections
The *STAC API - Collections* (<https://api.stacspec.org/v1.0.0/collections>) conformance class
requires only the subset of the behavior of Features that relates to Collections.
This subset is:
- the `data` link relation on the landing page
- the `/collections` and `/collections/{collection_id}` endpoints
This subset of behavior is useful in conjunction
with the *STAC API - Item Search* conformance class to allow the description of STAC Collections
without needing to implement the entire *STAC API - Features* conformance class.
### OGC API - Features - Part 1: Core
A STAC API implementation that conforms to *STAC API - Features* (<https://api.stacspec.org/v1.0.0/ogcapi-features>)
also conforms to
[OGC API - Features - Part 1 Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core)
conformance class (<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core>).
This conformance class should be advertised to OAFeat clients so they will also work with the STAC API.
### OGC API - Features - Part 1: GeoJSON
A STAC API implementation that conforms to *STAC API - Features*
also conforms to [OGC API - Features - Part 1 Requirements Class GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson) (<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson>)
This conformance class should be advertised to OAFeat clients so they will know of the support for GeoJSON.
### OGC API - Features - Part 1: OpenAPI 3.0
If OpenAPI 3.0 is used for the endpoint referenced by the `service-desc` link relation in the landing page defined
by *STAC API - Core*, the
[OGC API - Features - Part 1 Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)
(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30>) can be advertised.
## Link Relations
These conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
The STAC definition of Link does not require the `type` field,
but it is **STRONGLY RECOMMENDED** that this field exists.
If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.
### Landing Page (/)
The following Link relations are defined for the Landing Page (root).
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------- | -------------- | ---------------- | -------- | -------------------------------- |
| `conformance` | `/conformance` | application/json | OAFeat | **REQUIRED** Conformance URI |
| `data` | `/collections` | application/json | OAFeat | **REQUIRED** List of Collections |
### Collections (/collections)
The following Link relations are defined for the `/collections` endpoint response.
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------- | -------------- | ---------------- | ------------------------------------------- | --------------------------- |
| `root` | `/` | application/json | STAC API - Features, STAC API - Collections | **REQUIRED** The root URI |
| `self` | `/collections` | application/json | OAFeat | **REQUIRED** Self reference |
### Collection (/collections/{collectionId})
The following Link relations are defined for the Collection object returned from the `/collections/{collectionId}` endpoint.
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ----------- | ----------------------------- | ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Features, STAC API - Collections | **REQUIRED** The root URI |
| `self` | `/collections/{collectionId}` | application/json | OAFeat | **REQUIRED** Self reference |
| `parent` | `/` | application/json | STAC Collection | Parent reference, usually the root Catalog |
| `canonical` | various | various | STAC API - Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |
Usually, the `self` link in a Collection must link to the same URL that was used to request
it. However, implementations may choose to have the canonical location of the Collection be
elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.
Note that the `parent` link for a Collection should be point to the parent Catalog (such as the root Catalog, `/`) or Collection
of that Collection, rather than the API sub-path of `/collections`.
### Collection Items (/collections/{collectionId}/items)
The following Link relations are defined for the ItemCollection object returned from the `/collections/{collectionId}/items` endpoint.
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------ | ----------------------------------- | -------------------- | ------------------- | --------------------------------- |
| `root` | `/` | application/json | STAC API - Features | **REQUIRED** The root URI |
| `self` | `/collections/{collectionId}/items` | application/geo+json | OAFeat | **REQUIRED** Self reference |
| `collection` | `/collections/{collectionId}` | application/json | OAFeat | **REQUIRED** Collection reference |
### Items (/collections/{collectionId}/items/{itemId})
The following Link relations are defined for the Item object returned from the `/collections/{collectionId}/items/{itemId}` endpoint.
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------ | -------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Features | **REQUIRED** The root URI |
| `self` | `/collections/{collectionId}/items/{itemId}` | application/geo+json | OAFeat | **REQUIRED** Self reference |
| `collection` | `/collections/{collectionId}` | application/json | STAC Item | **REQUIRED** The containing Collection |
| `parent` | `/collections/{collectionId}` | application/json | STAC Item | Parent reference, usually the containing Collection |
The `parent` link for an Item may point to a Collection or a Catalog. The
`collection` link for an Item will always point to the containing Collection.
Links to a Collection must point to the `/collections/{collectionId}` endpoint,
rather than the API sub-path of `/collections/{collectionId}/items/`.
## Endpoints
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
The *OGC API - Features* endpoints are shown below, with details provided in the OpenAPI specifications for [Features](openapi-features.yaml) or [Collections](openapi-collections.yaml).
| **Endpoint** | **Returns** | **Media Type** | **Description** |
| ----------------------------------------------- | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `/collections` | application/json | JSON | Object containing an array of Collection objects in the Catalog, and Link relations |
| `/collections/{collectionId}` | application/json | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON |
| `/collections/{collectionId}/items` | application/geo+json | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection |
| `/collections/{collectionId}/items/{featureId}` | application/geo+json | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) |
The OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface
to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry
plus any number of properties. The core [STAC Item spec](../stac-spec/item-spec/README.md)
enhances the core `Feature` with additional requirements and options to enable cataloging of spatiotemporal 'assets' like
satellite imagery.
OAFeat also defines the concept of a Collection, which contains Features. In OAFeat, a Collection is a set of data that can
be queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic
information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all
the data contained. A [STAC Collection](../stac-spec/collection-spec/README.md) contains this same
information, along with other STAC-specific fields to provide additional metadata for searching spatiotemporal assets, and
thus are compliant with both OAFeat Collection and STAC Collection, and are returned from the `/collections/{collectionId}`
endpoint.
In OAFeat, Features are the individual records within a Collection and are usually provided in GeoJSON format.
[STAC Item](../stac-spec/item-spec/README.md) objects are compliant with the OAFeat Features
[GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the
`/collections/{collectionId}/items/{itemId}` endpoint. The return of other encodings
([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0))
is outside the scope of STAC API, as the [STAC Item](../stac-spec/item-spec/item-spec.md) is
specified in GeoJSON.
A typical OAFeat will have multiple collections. Simple search for items within a collection can be done
with the resource endpoint `GET /collections/{collectionId}/items`. This endpoint must be exposed via a
link in the individual collection's endpoint with `rel=items`, as shown in the
[Example Landing Page diagram](../overview.md#example-landing-page). Note that this relation is `items`, which is
distinct from the `item` relation defined in STAC for linking to a single Item. The part of the API implementing OAFeat will usually not use
`item` relations directly, but instead rely on
the collection resource linking to a paginated endpoint returning items through a link relation
`items`, e.g., `/collections/{collectionId}` has a link with relation `items` linking
to `/collections/{collectionId}/items`. However, static catalogs and other parts of the API may contain `item` relations.
It is recommended to have each OAFeat Collection correspond to a STAC Collection,
and the `/collections/{collectionId}/items` endpoint can be used as a single collection search. Implementations may **optionally**
provide support for the full superset of STAC API query parameters to the `/collections/{collectionId}/items` endpoint,
where the collection ID in the path is equivalent to providing that single value in the `Collections* query parameter in
STAC API.
Implementing OAFeat enables a wider range of clients to access the API's STAC Item objects, as it is a more widely implemented
protocol than STAC.
## Item Pagination
OAFeat supports paging through hypermedia links for the Items resource
(`/collections/{collectionId}/items`). Since only GET requests are allowed for this endpoint,
it is possible
to provide a Link with `rel` type `next` and the href of the full URL of the next page of results.
This link href must contain any URL parameters that are necessary
for the implementation to understand how to provide the next page of results, e.g., the query parameters `page`, `next`,
or `token` and any additional filter parameters if given and required. For example, the links array will have an object like:
```json
"links": [
{
"rel": "next",
"type": "application/geo+json",
"href": "https://stac-api.example.com/collections/my_collection/items?page=2"
}
]
```
The href may contain any arbitrary URL parameter, which is implementation-specific:
- `https://stac-api.example.com/collections/my_collection/items?page=2`
- `https://stac-api.example.com/collections/my_collection/items?next=8a35eba9c`
- `https://stac-api.example.com/collections/my_collection/items?token=f32890a0bdb09ac3`
In addition to supporting query parameters in the URL value of the `href` field,
STAC has extended the Link object
with additional fields to support more complex HTTP requests. These include `method` to specify
an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either
the entire body for the request or only the body fields that must be changed from the previous
request, as determined by the `merge` field. These fields are described in detail in the
[Item Search](../item-search/README.md#pagination) spec.
Implementations may also add link relations `prev`, `first`, and `last`. Most API implementations
should be able to support `first`, though `last` may be infeasible to implement in some data
stores.
See the [paging examples](../item-search/examples.md#paging-examples) for additional insight.
## Collection Pagination
OAFeat does not define a specific mechanism for how clients may access all collections from servers
with many
collections. STAC API - Features adds support for this with pagination (similar to the Item pagination
mechanism) through hypermedia links for the Collections resource
(`/collections`). This mechanism aligns with pagination of collections in the
[OGC API - Common - Part 2: Geospatial Data](https://portal.ogc.org/files/99149) specification.
With this, a link with
relation `next` is included in the `links` array,
and this is used to navigate to the next page of Collection objects. The specific query
parameter used for paging is implementation specific and not defined by STAC API. For example,
an implementation may take a parameter (e.g., `page`) indicating the numeric page of results, a
base64-encoded value indicating the last result returned for the current page (e.g., `search_after` as
in Elasticsearch), or a cursor token representing backend state.
In our simple example of numerical pages, the response for `page=3` would have a
`links` array containing these two Links indicating the URLs for the next (page=4) and
previous (page=2) pages:
```json
{
"links": [
{
"rel": "prev",
"type": "application/json",
"href": "https://stac-api.example.com/collections?page=2"
},
{
"rel": "next",
"type": "application/json",
"href": "https://stac-api.example.com/collections?page=4"
}
]
}
```
In addition to supporting query parameters in the URL value of the `href` field,
STAC has extended the Link object
with additional fields to support more complex HTTP requests. These include `method` to specify
an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either
the entire body for the request or only the body fields that must be changed from the previous
request, as determined by the `merge` field. These fields are described in detail in the
[Item Search](../item-search/README.md#pagination) spec.
Implementations may also add link relations `prev`, `first`, and `last`. Most API implementations
should be able to support `first`, though `last` may be infeasible to implement in some data
stores.
## Examples
Note that the OAFeat endpoints *only* allow HTTP GET. HTTP POST requests are not supported. If POST is required,
it is recommended to use STAC Item Search, as it can be constrained to a single collection to act the same as
an OAFeat `items` endpoint.
Request all the data in `mycollection` that is in New Zealand:
```
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89
```
Request 100 results in `mycollection` from New Zealand:
```
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100
```
Request all the data in `mycollection` that is in New Zealand at anytime on January 1st, 2019:
```
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z
```
Request 10 results from the data in `mycollection` from between January 1st (inclusive) and April 1st, 2019 (exclusive):
```
GET /collections/mycollection/items?datetime=2019-01-01T00:00:00Z/2019-03-31T23:59:59Z&limit=10
```
## Example Landing Page
This JSON is what would be expected from an api that implements only *STAC API - Core* and
*STAC API - Features*. In practice,
most APIs will also implement other conformance classes, and those will be reflected in the `links` and
`conformsTo` fields. A more typical Landing Page example is in
the [overview](../overview.md#example-landing-page) document.
```json
{
"stac_version": "1.0.0",
"id": "example-stac",
"title": "A simple STAC API Example",
"description": "This Catalog aims to demonstrate the a simple landing page",
"type": "Catalog",
"conformsTo" : [
"https://api.stacspec.org/v1.0.0/core",
"https://api.stacspec.org/v1.0.0/ogcapi-features",
"https://api.stacspec.org/v1.0.0/collections",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
],
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "conformance",
"type": "application/json",
"href": "https://stac-api.example.com/conformance"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stac-api.example.com/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stac-api.example.com/api.html"
},
{
"rel": "data",
"type": "application/json",
"href": "https://stac-api.example.com/collections"
}
]
}
```
## Example Collection Endpoint
The landing page `data` relation points to an endpoint to retrieve all collections. Each collection then has
a link relation to its `items` resource through the link with a rel value `items`. Note here that, unlike
as is typical with a static STAC Collection, there are no links here with rel value `item`.
`https://stac-api.example.com/collections/aster-l1t`
```json
{
"id": "aster-l1t",
"type": "Collection",
"title": "ASTER L1T",
"links": [
{
"rel": "items",
"type": "application/geo+json",
"href": "https://stac-api.example.com/collections/aster-l1t/items"
},
{
"rel": "parent",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com/collections/aster-l1t"
}
]
}
```
## Extensions
STAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).
================================================
FILE: ogcapi-features/openapi-collections.yaml
================================================
openapi: 3.0.3
info:
title: STAC API - Collections
version: v1.0.0
description: >-
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Collections
specification. This is a subset of the STAC API - Features specification.
contact:
name: STAC Specification
url: "http://stacspec.org"
license:
name: Apache License 2.0
url: "http://www.apache.org/licenses/LICENSE-2.0"
x-conformance-classes: ["https://api.stacspec.org/v1.0.0/collections"]
tags:
- name: Core
description: essential characteristics of a STAC API
- name: Collections
description: All endpoints related to STAC API - Collections
paths:
"/":
get:
tags:
- Core
summary: landing page
description: |-
The landing page provides links to the sub-resources.
operationId: getLandingPage
responses:
"200":
description: |-
The landing page provides links to the API definition
(link relations `service-desc` and `service-doc`),
the Conformance declaration (path `/conformance`,
link relation `conformance`), and the Feature
Collections (path `/collections`, link relation
`data`).
content:
application/json:
schema:
$ref: "../core/openapi.yaml#/components/schemas/landingPage"
example:
stac_version: "1.0.0"
type: Catalog
id: sentinel
title: Copernicus Sentinel Imagery
description: Catalog of Copernicus Sentinel 1 and 2 imagery.
conformsTo:
- "https://api.stacspec.org/v1.0.0/core"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
links:
- href: "http://data.example.org/"
rel: self
type: application/json
title: this document
- href: "http://data.example.org/api"
rel: service-desc
type: application/vnd.oai.openapi+json;version=3.0
title: the API definition
- href: "http://data.example.org/api.html"
rel: service-doc
type: text/html
title: the API documentation
- href: "http://data.example.org/conformance"
rel: conformance
type: application/json
title: OGC API conformance classes implemented by this server
- href: "http://data.example.org/collections"
rel: data
type: application/json
title: Information about the feature collections
"/collections":
get:
tags:
- Collections
summary: the feature collections in the dataset
description: |-
A body of Feature Collections that belong or are used together with additional links.
Request may not return the full set of metadata per Feature Collection.
operationId: getCollections
responses:
"200":
$ref: "#/components/responses/Collections"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"/collections/{collectionId}":
get:
tags:
- Collections
summary: |-
describe the feature collection with id `collectionId`
description: |-
A single Feature Collection for the given if `collectionId`.
Request this endpoint to get a full list of metadata for the Feature Collection.
operationId: describeCollection
parameters:
- $ref: "#/components/parameters/collectionId"
responses:
"200":
$ref: "#/components/responses/Collection"
"404":
$ref: "#/components/responses/NotFound"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
components:
parameters:
collectionId:
name: collectionId
in: path
description: local identifier of a collection
required: true
schema:
type: string
schemas:
collections:
type: object
required:
- links
- collections
properties:
links:
$ref: "../core/commons.yaml#/components/schemas/links"
collections:
type: array
items:
$ref: "../core/commons.yaml#/components/schemas/collection"
responses:
Collections:
description: |-
The feature collections shared by this API.
The dataset is organized as one or more feature collections. This resource
provides information about and access to the collections.
The response contains the list of collections. For each collection, a link
to the items in the collection (path `/collections/{collectionId}/items`,
link relation `items`) as well as key information about the collection.
This information includes:
* A local identifier for the collection that is unique for the dataset;
* A list of coordinate reference systems (CRS) in which geometries may be returned by the server. The first CRS is the default coordinate reference system (the default is always WGS 84 with axis order longitude/latitude);
* An optional title and description for the collection;
* An optional extent that can be used to provide an indication of the spatial and temporal extent of the collection - typically derived from the data;
* An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').
content:
application/json:
schema:
$ref: "#/components/schemas/collections"
Collection:
description: |-
Information about the feature collection with id `collectionId`.
The response contains a link to the items in the collection
(path `/collections/{collectionId}/items`, link relation `items`)
as well as key information about the collection. This information
includes:
* A local identifier for the collection that is unique for the dataset;
* A list of coordinate reference systems (CRS) in which geometries may be returned by the server. The first CRS is the default coordinate reference system (the default is always WGS 84 with axis order longitude/latitude);
* An optional title and description for the collection;
* An optional extent that can be used to provide an indication of the spatial and temporal extent of the collection - typically derived from the data;
* An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').
content:
application/json:
schema:
$ref: "../core/commons.yaml#/components/schemas/collection"
NotFound:
description: |-
The requested URI was not found.
================================================
FILE: ogcapi-features/openapi-features.yaml
================================================
openapi: 3.0.3
info:
title: STAC API - Features
version: v1.0.0
description: >-
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Features
specification. This extends OGC API - Features - Part 1: Core.
contact:
name: STAC Specification
url: "http://stacspec.org"
license:
name: Apache License 2.0
url: "http://www.apache.org/licenses/LICENSE-2.0"
x-conformance-classes: ["https://api.stacspec.org/v1.0.0/ogcapi-features"]
tags:
- name: Features
description: |-
All endpoints related to OGC API - Features - Part 1: Core
paths:
"/":
get:
tags:
- Features
summary: landing page
description: |-
The landing page provides links to the sub-resources.
operationId: getLandingPage
responses:
"200":
description: |-
The landing page provides links to the API definition
(link relations `service-desc` and `service-doc`),
the Conformance declaration (path `/conformance`,
link relation `conformance`), and the Feature
Collections (path `/collections`, link relation
`data`).
content:
application/json:
schema:
$ref: "../core/openapi.yaml#/components/schemas/landingPage"
example:
stac_version: "1.0.0"
type: Catalog
id: sentinel
title: Copernicus Sentinel Imagery
description: Catalog of Copernicus Sentinel 1 and 2 imagery.
conformsTo:
- "https://api.stacspec.org/v1.0.0/core"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30"
- "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
links:
- href: "http://data.example.org/"
rel: self
type: application/json
title: this document
- href: "http://data.example.org/api"
rel: service-desc
type: application/vnd.oai.openapi+json;version=3.0
title: the API definition
- href: "http://data.example.org/api.html"
rel: service-doc
type: text/html
title: the API documentation
- href: "http://data.example.org/conformance"
rel: conformance
type: application/json
title: OGC API conformance classes implemented by this server
- href: "http://data.example.org/collections"
rel: data
type: application/json
title: Information about the feature collections
"/conformance":
get:
tags:
- Features
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: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"/collections":
get:
tags:
- Features
summary: the feature collections in the dataset
description: |-
A body of Feature Collections that belong or are used together with additional links.
Request may not return the full set of metadata per Feature Collection.
operationId: getCollections
responses:
"200":
$ref: "#/components/responses/Collections"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"/collections/{collectionId}":
get:
tags:
- Features
summary: |-
describe the feature collection with id `collectionId`
description: |-
A single Feature Collection for the given if `collectionId`.
Request this endpoint to get a full list of metadata for the Feature Collection.
operationId: describeCollection
parameters:
- $ref: "#/components/parameters/collectionId"
responses:
"200":
$ref: "#/components/responses/Collection"
"404":
$ref: "#/components/responses/NotFound"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"/collections/{collectionId}/items":
get:
tags:
- Features
summary: fetch features
description: |-
Fetch features of the feature collection with id `collectionId`.
Every feature in a dataset belongs to a collection. A dataset may
consist of multiple feature collections. A feature collection is often a
collection of features of a similar type, based on a common schema.
operationId: getFeatures
parameters:
- $ref: "#/components/parameters/collectionId"
- $ref: "#/components/parameters/limit"
- $ref: "#/components/parameters/bbox"
- $ref: "#/components/parameters/datetime"
responses:
"200":
$ref: "#/components/responses/Features"
"404":
$ref: "#/components/responses/NotFound"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"/collections/{collectionId}/items/{featureId}":
get:
tags:
- Features
summary: fetch a single feature
description: |-
Fetch the feature with id `featureId` in the feature collection
with id `collectionId`.
operationId: getFeature
parameters:
- $ref: "#/components/parameters/collectionId"
- $ref: "#/components/parameters/featureId"
responses:
"200":
$ref: "#/components/responses/Feature"
"404":
$ref: "#/components/responses/NotFound"
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
components:
parameters:
bbox:
name: bbox
in: query
description: |-
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 in
gitextract_tuehb0n8/
├── .circleci/
│ ├── .spectral-fragments.yml
│ ├── .spectral.yml
│ ├── build-openapi.sh
│ ├── config.yml
│ └── publish.js
├── .github/
│ └── pull_request_template.md
├── .gitignore
├── .nvmrc
├── .remarkignore
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── PRINCIPLES.md
├── README.md
├── build/
│ ├── index.html
│ ├── redoc_index.html
│ └── swagger-config.yaml
├── core/
│ ├── README.md
│ ├── commons.yaml
│ └── openapi.yaml
├── extensions.md
├── fragments/
│ └── itemcollection/
│ ├── README.md
│ ├── examples/
│ │ ├── itemcollection-sample-full.json
│ │ └── itemcollection-sample-minimal.json
│ └── openapi.yaml
├── implementation.md
├── item-search/
│ ├── README.md
│ ├── examples.md
│ └── openapi.yaml
├── ogcapi-features/
│ ├── README.md
│ ├── openapi-collections.yaml
│ └── openapi-features.yaml
├── overview.md
├── package.json
├── stac-api.gv
└── stac-spec/
├── .circleci/
│ ├── config.yml
│ ├── publish-schemas.js
│ └── rc.yaml
├── .github/
│ └── pull_request_template.md
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── STAC-UML.drawio
├── best-practices.md
├── catalog-spec/
│ ├── README.md
│ ├── catalog-spec.md
│ └── json-schema/
│ └── catalog.json
├── collection-spec/
│ ├── README.md
│ ├── collection-spec.md
│ └── json-schema/
│ └── collection.json
├── examples/
│ ├── README.md
│ ├── catalog.json
│ ├── collection-only/
│ │ ├── collection-with-schemas.json
│ │ └── collection.json
│ ├── collection.json
│ ├── collectionless-item.json
│ ├── core-item.json
│ ├── extended-item.json
│ ├── extensions-collection/
│ │ ├── collection.json
│ │ └── proj-example/
│ │ └── proj-example.json
│ └── simple-item.json
├── extensions/
│ └── README.md
├── item-spec/
│ ├── README.md
│ ├── common-metadata.md
│ ├── item-spec.md
│ └── json-schema/
│ ├── basics.json
│ ├── datetime.json
│ ├── instrument.json
│ ├── item.json
│ ├── licensing.json
│ └── provider.json
├── overview.md
├── package.json
├── principles.md
└── process.md
SYMBOL INDEX (1 symbols across 1 files)
FILE: stac-spec/.circleci/publish-schemas.js
function filterFn (line 6) | function filterFn (item) {
Condensed preview — 80 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (568K chars).
[
{
"path": ".circleci/.spectral-fragments.yml",
"chars": 187,
"preview": "extends: \"spectral:oas\"\nrules:\n openapi-tags: off\n info-contact: off\n oas3-api-servers: off\n oas3-unused-component: "
},
{
"path": ".circleci/.spectral.yml",
"chars": 133,
"preview": "extends: \"spectral:oas\"\nrules:\n oas3-api-servers: off\n oas3-schema: warn\n tag-description: true\n oas3-parameter-desc"
},
{
"path": ".circleci/build-openapi.sh",
"chars": 493,
"preview": "#!/bin/bash\n\nPATH=./node_modules/.bin:$PATH\n\n# find all OpenAPI docs that are not fragments\nFINS=(core/openapi.yaml item"
},
{
"path": ".circleci/config.yml",
"chars": 2557,
"preview": "version: 2.1\n\nreferences:\n restore_repo: &restore_repo\n restore_cache:\n keys:\n - v0-repo-{{ .Branch }}-{"
},
{
"path": ".circleci/publish.js",
"chars": 416,
"preview": "const ghpages = require('gh-pages');\n\nlet args = process.argv.slice(2);\nlet tag = 'main';\nif (args.length && args[0].tri"
},
{
"path": ".github/pull_request_template.md",
"chars": 506,
"preview": "**Related Issue(s):** \n\n- #\n\n**Proposed Changes:**\n\n1. \n2. \n\n**PR Checklist:**\n\n- [ ] This PR has **no** breaking change"
},
{
"path": ".gitignore",
"chars": 950,
"preview": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Runtime data\npids\n*.pid\n*.seed\n*.pid.lock\n\n# Directo"
},
{
"path": ".nvmrc",
"chars": 3,
"preview": "16\n"
},
{
"path": ".remarkignore",
"chars": 33,
"preview": "/CHANGELOG.md\n/CODE_OF_CONDUCT.md"
},
{
"path": "CHANGELOG.md",
"chars": 14016,
"preview": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Change"
},
{
"path": "CITATION.cff",
"chars": 683,
"preview": "cff-version: 1.2.0\nmessage: \"If you are referring to the STAC API specification in your publications, please cite it as "
},
{
"path": "CODE_OF_CONDUCT.md",
"chars": 5544,
"preview": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participa"
},
{
"path": "CONTRIBUTING.md",
"chars": 7954,
"preview": "## Contributing\n\nPull Requests are the primary method of contributing to the spec itself, and everyone is welcome to sub"
},
{
"path": "LICENSE",
"chars": 11357,
"preview": " Apache License\n Version 2.0, January 2004\n "
},
{
"path": "PRINCIPLES.md",
"chars": 4966,
"preview": "This project will be governed by a set of informal core principles. These principles are not set in stone,\nand indeed th"
},
{
"path": "README.md",
"chars": 10943,
"preview": "<!--lint disable no-html-->\r\n<img src=\"https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.pn"
},
{
"path": "build/index.html",
"chars": 680,
"preview": "<!DOCTYPE html>\n<html>\n\n<head>\n <title>STAC API</title>\n <!-- needed for adaptive design -->\n <meta charset=\"ut"
},
{
"path": "build/redoc_index.html",
"chars": 719,
"preview": "<!DOCTYPE html>\n<html>\n\n<head>\n <title>STAC API</title>\n <!-- needed for adaptive design -->\n <meta charset=\"utf-8\" /"
},
{
"path": "build/swagger-config.yaml",
"chars": 378,
"preview": "openapi: 3.0.3\ninfo:\n title: STAC API - Complete\n version: 1.0.0-rc.2\napis:\n - url: 'build/core/openapi.yaml'\n pat"
},
{
"path": "core/README.md",
"chars": 12562,
"preview": "# STAC API - Core Specification\n\n- [STAC API - Core Specification](#stac-api---core-specification)\n - [Summary](#summar"
},
{
"path": "core/commons.yaml",
"chars": 30100,
"preview": "openapi: 3.0.3\ninfo:\n title: The SpatioTemporal Asset Catalog API - Commons\n description: This is the OpenAPI version "
},
{
"path": "core/openapi.yaml",
"chars": 3202,
"preview": "openapi: 3.0.3\ninfo:\n title: STAC API - Core\n version: v1.0.0\n description: >-\n This is an OpenAPI definition of t"
},
{
"path": "extensions.md",
"chars": 2161,
"preview": "# STAC API Extensions\n\nSTAC API aims to define a core of functionality, with richer capabilities enabled by extensions. "
},
{
"path": "fragments/itemcollection/README.md",
"chars": 2488,
"preview": "# STAC API - ItemCollection Fragment\n\nThis document explains the structure and content of a SpatioTemporal Asset Catalog"
},
{
"path": "fragments/itemcollection/examples/itemcollection-sample-full.json",
"chars": 3292,
"preview": "{\n \"type\": \"FeatureCollection\",\n \"numberMatched\": 10,\n \"numberReturned\": 1,\n \"features\": [\n {\n "
},
{
"path": "fragments/itemcollection/examples/itemcollection-sample-minimal.json",
"chars": 52,
"preview": "{\n \"type\": \"FeatureCollection\",\n \"features\": []\n}\n"
},
{
"path": "fragments/itemcollection/openapi.yaml",
"chars": 1294,
"preview": "openapi: 3.0.3\ninfo:\n title: The SpatioTemporal Asset Catalog API - Item Collection\n description: The specification fo"
},
{
"path": "implementation.md",
"chars": 5603,
"preview": "# Implementation Recommendations\n\nThis document describes implementation recommendations for a STAC API.\n\n## Identifiers"
},
{
"path": "item-search/README.md",
"chars": 17797,
"preview": "# STAC API - Item Search\n\n- [STAC API - Item Search](#stac-api---item-search)\n - [Summary](#summary)\n - [Overview](#ov"
},
{
"path": "item-search/examples.md",
"chars": 3665,
"preview": "## Item Search Examples\n\n### Single Collection example\n\nThis example shows how you can request Item objects from a singl"
},
{
"path": "item-search/openapi.yaml",
"chars": 10980,
"preview": "openapi: 3.0.3\ninfo:\n title: STAC API - Item Search\n version: v1.0.0\n description: >-\n This is an OpenAPI definiti"
},
{
"path": "ogcapi-features/README.md",
"chars": 25573,
"preview": "# STAC API - Collections and Features Specification\n\n- [STAC API - Collections and Features Specification](#stac-api---c"
},
{
"path": "ogcapi-features/openapi-collections.yaml",
"chars": 7433,
"preview": "openapi: 3.0.3\ninfo:\n title: STAC API - Collections\n version: v1.0.0\n description: >-\n This is an OpenAPI definiti"
},
{
"path": "ogcapi-features/openapi-features.yaml",
"chars": 17096,
"preview": "openapi: 3.0.3\ninfo:\n title: STAC API - Features\n version: v1.0.0\n description: >-\n This is an OpenAPI definition "
},
{
"path": "overview.md",
"chars": 15071,
"preview": "# About\n\nThe STAC API family of specifications define a JSON-based web API to browse and query [SpatioTemporal Asset Cat"
},
{
"path": "package.json",
"chars": 4198,
"preview": "{\n \"name\": \"api-spec\",\n \"version\": \"v1.0.0\",\n \"description\": \"STAC API helpers to generate, serve and check the"
},
{
"path": "stac-api.gv",
"chars": 3012,
"preview": "# All have self link to self (self edge)\n# All have root link to root\n\ndigraph g {\n label = <STAC API Links>;\n lab"
},
{
"path": "stac-spec/.circleci/config.yml",
"chars": 1581,
"preview": "version: 2\njobs:\n test_examples_node:\n working_directory: ~/stac\n docker:\n - image: circleci/node:12\n ste"
},
{
"path": "stac-spec/.circleci/publish-schemas.js",
"chars": 1135,
"preview": "const klaw = require('klaw-sync');\nconst path = require('path');\nconst fs = require('fs');\nconst ghpages = require('gh-p"
},
{
"path": "stac-spec/.circleci/rc.yaml",
"chars": 1189,
"preview": "plugins:\n# Check links\n - validate-links\n# Apply some recommended defaults for consistency\n - remark-preset-lint-consi"
},
{
"path": "stac-spec/.github/pull_request_template.md",
"chars": 550,
"preview": "**Related Issue(s):** #\n\n\n**Proposed Changes:**\n\n1. \n2. \n\n**PR Checklist:**\n\n- [ ] This PR is made against the dev branc"
},
{
"path": "stac-spec/.gitignore",
"chars": 1026,
"preview": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Runtime data\npids\n*.pid\n*.seed\n*.pid.lock\n\n# Directo"
},
{
"path": "stac-spec/CHANGELOG.md",
"chars": 34139,
"preview": "<!--lint disable maximum-line-length-->\n# Changelog\nAll notable changes to this project will be documented in this file."
},
{
"path": "stac-spec/CODE_OF_CONDUCT.md",
"chars": 3415,
"preview": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, w"
},
{
"path": "stac-spec/CONTRIBUTING.md",
"chars": 3982,
"preview": "## Contributing\n\nPull Requests are the primary method of contributing to the spec itself, and everyone is welcome to sub"
},
{
"path": "stac-spec/LICENSE",
"chars": 11357,
"preview": " Apache License\n Version 2.0, January 2004\n "
},
{
"path": "stac-spec/README.md",
"chars": 7470,
"preview": "<!--lint disable no-html-->\n<img src=\"https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png"
},
{
"path": "stac-spec/STAC-UML.drawio",
"chars": 7225,
"preview": "<mxfile modified=\"2021-05-25T16:52:51.799Z\" host=\"app.diagrams.net\" agent=\"5.0 (X11; Linux x86_64) AppleWebKit/537.36 (K"
},
{
"path": "stac-spec/best-practices.md",
"chars": 61701,
"preview": "# STAC Best Practices\n\n## Table of Contents\n\n- **[Web Best Practices](#web-practices)**\n - [Enable Cross-origin resourc"
},
{
"path": "stac-spec/catalog-spec/README.md",
"chars": 2841,
"preview": "# STAC Catalog Specification\n\nA STAC [Catalog](catalog-spec.md) is a top-level object that logically groups other Catalo"
},
{
"path": "stac-spec/catalog-spec/catalog-spec.md",
"chars": 7646,
"preview": "# STAC Catalog Specification <!-- omit in toc --> \n\n- [Catalog fields](#catalog-fields)\n - [Additional Field Informatio"
},
{
"path": "stac-spec/catalog-spec/json-schema/catalog.json",
"chars": 2169,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/catalog-spec/jso"
},
{
"path": "stac-spec/collection-spec/README.md",
"chars": 2881,
"preview": "# STAC Collection Specification\n\nA STAC [Collection](collection-spec.md) object is used to describe a group of related \n"
},
{
"path": "stac-spec/collection-spec/collection-spec.md",
"chars": 24093,
"preview": "# STAC Collection Specification <!-- omit in toc --> \n\n- [Overview](#overview)\n- [Collection fields](#collection-fields)"
},
{
"path": "stac-spec/collection-spec/json-schema/collection.json",
"chars": 7209,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/collection-spec/"
},
{
"path": "stac-spec/examples/README.md",
"chars": 6607,
"preview": "# STAC Examples\n\nThis directory contains various examples for all parts of the STAC specification.\nIt is structured to b"
},
{
"path": "stac-spec/examples/catalog.json",
"chars": 1269,
"preview": "{\n \"id\": \"examples\",\n \"type\": \"Catalog\",\n \"title\": \"Example Catalog\",\n \"stac_version\": \"1.0.0\",\n \"description\": \"Th"
},
{
"path": "stac-spec/examples/collection-only/collection-with-schemas.json",
"chars": 6130,
"preview": "{\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n \""
},
{
"path": "stac-spec/examples/collection-only/collection.json",
"chars": 5830,
"preview": "{\n \"type\": \"Collection\",\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/v1"
},
{
"path": "stac-spec/examples/collection.json",
"chars": 2465,
"preview": "{\n \"id\": \"simple-collection\",\n \"type\": \"Collection\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/"
},
{
"path": "stac-spec/examples/collectionless-item.json",
"chars": 3496,
"preview": "{\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n \""
},
{
"path": "stac-spec/examples/core-item.json",
"chars": 3291,
"preview": "{\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [],\n \"type\": \"Feature\",\n \"id\": \"20201211_223832_CS2\",\n \"bbox\": [\n "
},
{
"path": "stac-spec/examples/extended-item.json",
"chars": 5167,
"preview": "{\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n \""
},
{
"path": "stac-spec/examples/extensions-collection/collection.json",
"chars": 1354,
"preview": "{\n \"id\": \"extensions-collection\",\n \"type\": \"Collection\",\n \"stac_version\": \"1.0.0\",\n \"description\": \"A heterogenous c"
},
{
"path": "stac-spec/examples/extensions-collection/proj-example/proj-example.json",
"chars": 6933,
"preview": "{\n \"type\": \"Feature\",\n \"stac_version\": \"1.0.0\",\n \"id\": \"proj-example\",\n \"properties\": {\n \"datetime\": \"2018-10-01T"
},
{
"path": "stac-spec/examples/simple-item.json",
"chars": 1782,
"preview": "{\n \"stac_version\": \"1.0.0\",\n \"stac_extensions\": [],\n \"type\": \"Feature\",\n \"id\": \"20201211_223832_CS2\",\n \"bbox\": [\n "
},
{
"path": "stac-spec/extensions/README.md",
"chars": 15730,
"preview": "# Extensions\n\n- [Overview](#overview)\n- [Using Extensions](#using-extensions)\n - [Extension IDs in `stac_extensions`](#"
},
{
"path": "stac-spec/item-spec/README.md",
"chars": 1171,
"preview": "# STAC Item Specification\n\nThe [STAC Item](item-spec.md) object is the most important object in a STAC system. An\n**Item"
},
{
"path": "stac-spec/item-spec/common-metadata.md",
"chars": 12160,
"preview": "# STAC Common Metadata\n\nThis document outlines commonly used fields in STAC.\nThey are often used in [STAC Item propertie"
},
{
"path": "stac-spec/item-spec/item-spec.md",
"chars": 23226,
"preview": "# STAC Item Specification <!-- omit in toc --> \n\n- [Overview](#overview)\n- [Item fields](#item-fields)\n - [Additional F"
},
{
"path": "stac-spec/item-spec/json-schema/basics.json",
"chars": 533,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/item-spec/json-schema/datetime.json",
"chars": 1472,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/item-spec/json-schema/instrument.json",
"chars": 696,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/item-spec/json-schema/item.json",
"chars": 6723,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/item-spec/json-schema/licensing.json",
"chars": 302,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/item-spec/json-schema/provider.json",
"chars": 1135,
"preview": "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-s"
},
{
"path": "stac-spec/overview.md",
"chars": 14734,
"preview": "# STAC Overview\n\nThere are three component specifications that together make up the core SpatioTemporal Asset Catalog sp"
},
{
"path": "stac-spec/package.json",
"chars": 940,
"preview": "{\n \"name\": \"stac-spec\",\n \"version\": \"1.0.0\",\n \"description\": \"STAC spec helpers to check the spec.\",\n \"repository\": "
},
{
"path": "stac-spec/principles.md",
"chars": 3613,
"preview": "This project will be governed by a set of informal core principles. These principles are not set in stone,\nand indeed th"
},
{
"path": "stac-spec/process.md",
"chars": 8560,
"preview": "## STAC Development & Release Process\n\n### Development Process\n\nThe SpatioTemporal Asset Catalog specification is under "
}
]
About this extraction
This page contains the full source code of the radiantearth/stac-api-spec GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 80 files (532.3 KB), approximately 130.9k tokens, and a symbol index with 1 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.