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 - 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 () - Filter Extension conformance classes refactored to better align with STAC API use cases. - Renamed conformance class "Queryable First Operand" () to "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]: [v1.0.0]: [v1.0.0-rc.4]: [v1.0.0-rc.3]: [v1.0.0-rc.2]: [v1.0.0-rc.1]: [v1.0.0-beta.5]: [v1.0.0-beta.4]: [v1.0.0-beta.3]: [v1.0.0-beta.2]: [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 (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 . 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 ================================================ stac-logo # 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 , 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 ================================================ STAC API

STAC API

Conformance Classes

================================================ FILE: build/redoc_index.html ================================================ STAC API ================================================ 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:** - - **[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 . 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 ****. 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 . 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:** - - **[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 (), 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:** - - Features - - 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 (). ## 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 () conformance class includes and extends the behavior of OAFeat, while the STAC API - Collections () conformance class is the subset of Features that pertains only to Collections. ### STAC API - Features The *STAC API - Features* () conformance class encompasses all of the behavior described in this specification, as derived from OAFeat. ### STAC API - Collections The *STAC API - 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* () 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 (). 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) () 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) () 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 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. required: false schema: type: array oneOf: - minItems: 4 maxItems: 4 - minItems: 6 maxItems: 6 items: type: number style: form explode: false collectionId: name: collectionId in: path description: local identifier of a collection required: true schema: type: string 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 featureId: name: featureId in: path description: local identifier of a feature required: true schema: type: string limit: name: limit in: query description: |- The optional limit parameter recommends the number of items that should be present 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. required: false schema: type: integer minimum: 1 maximum: 10000 default: 10 style: form explode: false 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" featureCollectionGeoJSON: allOf: - $ref: "../core/commons.yaml#/components/schemas/featureCollectionGeoJSON" - type: object required: - features properties: features: type: array items: $ref: "../core/commons.yaml#/components/schemas/item" links: $ref: "../core/commons.yaml#/components/schemas/links" timeStamp: $ref: "#/components/schemas/timeStamp" numberMatched: $ref: "#/components/schemas/numberMatched" numberReturned: $ref: "#/components/schemas/numberReturned" numberMatched: description: |- The number of features of the feature type that match the selection parameters like `bbox`. type: integer minimum: 0 example: 127 numberReturned: description: |- The number of features in the feature collection. A server may omit this information in a response, if the information about the number of features is not known or difficult to compute. If the value is provided, the value must be identical to the number of items in the "features" array. type: integer minimum: 0 example: 10 timeStamp: description: This property indicates the time and date when the response was generated. type: string format: date-time example: "2017-08-17T08:05:32Z" responses: ConformanceDeclaration: description: |- The URIs of all conformance classes supported by the server. To support "generic" clients that want to access multiple OGC API Features implementations - and not "just" a specific API / server, the server declares the conformance classes it implements and conforms to. content: application/json: schema: $ref: "../core/commons.yaml#/components/schemas/conformanceClasses" example: conformsTo: - "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" 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" Features: description: |- The response is a document consisting of features in the collection. The features included in the response are determined by the server based on the query parameters of the request. To support access to larger collections without overloading the client, the API supports paged access with links to the next page, if more features are selected that the page size. The `bbox` and `datetime` parameter can be used to select only a subset of the features in the collection (the features that are in the bounding box or time interval). The `bbox` parameter matches all features in the collection that are not associated with a location, too. The `datetime` parameter matches all features in the collection that are not associated with a time stamp or interval, too. The `limit` parameter may be used to control the subset of the selected features that should be returned in the response, the page size. Each page may include information about the number of selected and returned features (`numberMatched` and `numberReturned`) as well as links to support paging (link relation `next`). content: application/geo+json: schema: $ref: "#/components/schemas/featureCollectionGeoJSON" Feature: description: |- fetch the feature with id `featureId` in the feature collection with id `collectionId` content: application/geo+json: schema: $ref: "../core/commons.yaml#/components/schemas/item" NotFound: description: |- The requested URI was not found. ================================================ FILE: overview.md ================================================ # About The STAC API family of specifications define a JSON-based web API to browse and query [SpatioTemporal Asset Catalog](stac-spec/) (STAC) objects. While the core STAC specification provides a structure and language to describe assets, users usually want to access a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching metadata properties. STAC API extensions specify those query parameters, and compliant servers return STAC [Item](stac-spec/item-spec/README.md) objects that match the user's query. Additional functionality can be added through the [OGC API](https://ogcapi.ogc.org/) family of standards, particularly [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) (OAFeat, for our shorthand). Notes on implementation recommendations may be found [here](implementation.md). ## STAC API Description ### Core The [Core](core/) of STAC API returns a valid [STAC Catalog](stac-spec/catalog-spec/catalog-spec.md) and a description of STAC API specifications to which it conforms. The `links` section of the Catalog is the jumping-off point for the more powerful capabilities - it contains a list of URLs with link 'relationships' (`rel`) and descriptions to indicate their functionality. Note that the [STAC Core specification](stac-spec) provides most of the content of API responses - the STAC API is primarily concerned with the return of STAC [Item](stac-spec/item-spec/README.md) and [Collection](stac-spec/collection-spec/README.md) objects via a web API. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0/core) for more details. There are then two major sets of functionality that build on the core, [Item Search](item-search) and [Collection and Features](ogcapi-features) , which are designed to be complementary, letting implementations choose which parts they want to utilize. ### Item Search The [Item Search](item-search) functionality is one of the most common, provided by the `search` rel located at a `/search` endpoint. It re-uses all of the OAFeat [query parameters](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) specified in their 'core', and adds a few more. It does not require a full implementation of OAFeat, but it is instead a simplified construct that can run a search across any group of STAC [`Item`](stac-spec/item-spec/README.md) objects. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0/item-search) for more details. ### Collections and Features The other major functionality for a STAC API is to [serve STAC Collection and Item](ogcapi-features) objects through the [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) endpoints. This enables any OAFeat client to access STAC Item objects in the same way they do any other data. Every STAC Collection becomes available at the `/collections` endpoint (making this a superset of the Collections functionality), with each `/collections/{collectionId}/items` endpoint allowing search of the items in that single collection. For STAC, this means implementing [OGC API - Features Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_core), as well as the OAFeat [GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), since STAC objects are by definition also GeoJSON objects. Full compliance involves splitting STAC `Item` objects into individual `/collections/{collectionId}/items` endpoints that expose querying single collections, as OAFeat does not currently support cross-collection search. It also adds a few other requirements, which are highlighted in the [features description](ogcapi-features/), in order to help STAC implementors understand OAFeat without having to read the full specification from scratch. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0/ogcapi-features) for more details. ### Extensions & Fragments Both STAC API and OAFeat allow 'extensions' that can be added for additional functionality. The STAC community has created [a number of extensions](https://stac-api-extensions.github.io) to OAFeat in order to meet the requirements of its implementors. Additional details about extensions can be found in the [extensions document](extensions.md). These are specified in OpenAPI, which works cleanly when the new functionality is a new API location (a complete resource, or adding POST to an existing one). Many of the additions, however, are done at the parameter or response level, like adding a `sortby` field to return ordered results. Each *extension* is made specifically against a part of the STAC API, so that it can be specified as a conformance class (e.g., that Item Search is being extended to support `sortby` but not Features). We are working to fully align STAC's OAFeat extensions to be the same as the OGC API building blocks being worked on so that every STAC extension is specified at the OGC API level. The end goal is for STAC API to just present a curated set of extension options. ## STAC Core and OGC Versions This version of STAC API depends on OGC API - Features - Part 1: Core [Version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). Future versions will likely depend on [OGC API Common](https://github.com/opengeospatial/ogcapi-common) and additional parts of Features as components evolve and mature. This version of STAC API (1.x.x) is intended to work with any STAC core specification version 1.x.x (including betas), but is not designed to work with STAC 2.0 and above (since we use [SemVer](https://semver.org/) it may introduce backwards incompatible changes). The STAC API spec is released with the latest stable STAC core specification version included in the [`/stac-spec`](stac-spec/) directory as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). To determine which version it is, just check the [`/stac-spec/CHANGELOG.md`](stac-spec/CHANGELOG.md) for the topmost version & release date. ## Endpoints 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") in the endpoints listed below. The following table describes the service resources available in a STAC API implementation that supports all three of the foundation specifications. Note that the 'Endpoint' column is more of an example in some cases. OGC API makes some endpoint locations required, those will be bolded below. | Endpoint | Specified in | Link Relationship | Returns | Description | | ----------------------------------------------- | ------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `/` | [Core](core/) | root | [Catalog](stac-spec/catalog-spec/catalog-spec.md) | Extends `/` from OAFeat to return a full STAC catalog. | | `/search` | [Item Search](item-search/) | search | [ItemCollection](fragments/itemcollection/README.md) | Retrieves a group of Item objects matching the provided search predicates, probably containing search metadata from the `search` extension | | `/collections` | [Features](ogcapi-features/), [Collections](ogcapi-features/) | data | JSON | Object with a list of Collection objects contained in the catalog and links | | `/conformance` | [Features](ogcapi-features/) | conformance | JSON | Info about standards to which the API conforms | | `/api` | [Features](ogcapi-features/) | service-desc | any | The description of the endpoints in this service | | `/collections/{collectionId}` | [Features](ogcapi-features/), [Collections](ogcapi-features/) | collection | Collection | Returns single Collection JSON | | `/collections/{collectionId}/items` | [Features](ogcapi-features/) | items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Item objects in collection | | `/collections/{collectionId}/items/{featureId}` | [Features](ogcapi-features/) | item | Returns single Item (GeoJSON Feature). This relation is usually not used in OAFeat implementations. | ## Conformance Classes STAC API is evolving to utilize OAFeat's [Conformance](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes) JSON structure. For STAC API, we declare new STAC conformance classes, with the core ones detailed in the table below. [STAC Features](ogcapi-features/) requires the core OAFeat conformance classes and declares that those endpoints return STAC Collection and Feature objects. The core STAC conformance classes communicate the conformance JSON only in the root (`/`) document, while OGC API requires they also live at the `/conformance` endpoint. STAC's conformance structure is detailed in the [core](core/). Note all conformance URIs serve up a rendered HTML version of the corresponding OpenAPI document at the given location. ### Conformance Class Table | **Name** | **Specified in** | **Conformance URI** | **Description** | | ---------------------- | ------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | STAC API - Core | [Core](core) | | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. | | STAC API - Item Search | [Item Search](item-search) | | Enables search of all STAC Item objects on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | | STAC API - Features | [Collections and Features](ogcapi-features) | | Specifies the use of OGC API - Features to serve STAC Item and Collection objects | | STAC API - Collections | [Collections and Features](ogcapi-features) | | Specifies the use of a subset of STAC API - Features to serve Collection objects | Additional conformance classes can be specified by [STAC API Extensions](extensions.md). ## Example Landing Page When all three conformance classes (Core, Features, Item Search) are implemented, the relationships among various resources are shown in the following diagram. In each node, there is also a `self` and `root` link that are not depicted to keep the diagram more concise. ![Diagram of STAC link relations](stac-api.png) The Landing Page will at least have the following `conformsTo` and `links`: ```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/collections", "https://api.stacspec.org/v1.0.0/ogcapi-features", "https://api.stacspec.org/v1.0.0/item-search", "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" }, { "rel": "child", "type": "application/json", "href": "https://stac-api.example.com/collections/sentinel-2", }, { "rel": "child", "type": "application/json", "href": "https://stac-api.example.com/collections/landsat-8", }, { "rel": "search", "type": "application/geo+json", "href": "https://stac-api.example.com/search" } ] } ``` ================================================ FILE: package.json ================================================ { "name": "api-spec", "version": "v1.0.0", "description": "STAC API helpers to generate, serve and check the API spec.", "repository": "https://github.com/radiantearth/stac-api-spec", "license": "Apache-2.0", "scripts": { "serve": "redoc-cli serve core/openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", "check": "npm run check-markdown && npm run check-openapi", "check-markdown": "remark . --frail --ignore-pattern stac-spec/", "check-openapi": "npm run check-openapi-core && npm run check-openapi-commons && npm run check-openapi-ogcapi-features && npm run check-openapi-item-search && npm run check-openapi-fragments", "check-openapi-core": "spectral lint core/openapi.yaml --ruleset .circleci/.spectral.yml", "check-openapi-commons": "spectral lint core/commons.yaml --ruleset .circleci/.spectral-fragments.yml", "check-openapi-ogcapi-features": "spectral lint ogcapi-features/openapi-features.yaml ogcapi-features/openapi-collections.yaml --ruleset .circleci/.spectral.yml", "check-openapi-item-search": "spectral lint item-search/openapi.yaml --ruleset .circleci/.spectral.yml", "check-openapi-fragments": "spectral lint fragments/*/openapi.yaml --ruleset .circleci/.spectral-fragments.yml", "build-openapi": ".circleci/build-openapi.sh", "publish-openapi": "node .circleci/publish.js", "check-stac-spec-changes": "git diff --quiet HEAD ${npm_config_compare_to} -- stac-spec" }, "dependencies": { "@redocly/openapi-cli": "^1.0.0-beta.94", "@stoplight/spectral-cli": "^6.6.0", "gh-pages": "^5.0.0", "redoc-cli": "^0.13.21", "remark-cli": "^11.0.0", "remark-lint": "^9.1.1", "remark-gfm": "^3.0.1", "remark-lint-no-html": "^3.1.1", "remark-preset-lint-consistent": "^5.1.1", "remark-preset-lint-markdown-style-guide": "^5.1.2", "remark-preset-lint-recommended": "^6.1.2", "remark-validate-links": "^12.1.0" }, "remarkConfig": { "plugins": [ "remark-gfm", "validate-links", "remark-preset-lint-consistent", "remark-preset-lint-markdown-style-guide", "remark-preset-lint-recommended", "lint-no-html", [ "remark-lint-emphasis-marker", "*" ], "remark-lint-hard-break-spaces", "remark-lint-blockquote-indentation", "remark-lint-no-consecutive-blank-lines", [ "remark-lint-maximum-line-length", 150 ], [ "remark-lint-fenced-code-flag", false ], "remark-lint-fenced-code-marker", "remark-lint-no-shell-dollars", [ "remark-lint-code-block-style", "fenced" ], "remark-lint-heading-increment", "remark-lint-no-multiple-toplevel-headings", "remark-lint-no-heading-punctuation", [ "remark-lint-maximum-heading-length", 70 ], [ "remark-lint-heading-style", "atx" ], [ "remark-lint-no-shortcut-reference-link", false ], "remark-lint-list-item-bullet-indent", "remark-lint-ordered-list-marker-style", "remark-lint-ordered-list-marker-value", "remark-lint-checkbox-character-style", [ "remark-lint-unordered-list-marker-style", "-" ], [ "remark-lint-list-item-indent", "space" ], "remark-lint-table-pipes", "remark-lint-no-literal-urls", [ "remark-lint-no-file-name-irregular-characters", false ], [ "remark-lint-list-item-spacing", false ] ] } } ================================================ FILE: stac-api.gv ================================================ # All have self link to self (self edge) # All have root link to root digraph g { label = ; labelloc = "t"; fontsize = "24" graph [ rankdir = "LR" ]; node [ fontsize = "16" shape = "ellipse" ]; edge [ ]; "/" [ label = "Landing Page\n/|links[rel=conformance]\l|links[rel=service-doc]\l|links[rel=service-desc]\l|links[rel=data]\l|links[rel=child]\l|links[rel=child]\l|links[rel=search]\l" shape = "record" ]; "collections" [ label = " Collections\n/collections|collections[0].links[rel=self]\l|collections[1].links[rel=self]\l" shape = "record" ]; "collectionY" [ label = " Collection y\n/collections/y|links[rel=items]\l" shape = "record" ]; "collectionX" [ label = " Collection x\n/collections/x|links[rel=items]\l" shape = "record" ]; "service-desc" [ label = "OpenAPI Spec\n/api" shape = "record" ]; "service-doc" [ label = "Service Doc\n/api.html" shape = "record" ]; "conformance" [ label = "Conformance\n/conformance" shape = "record" ]; "collectionY-items" [ label = " Collection y Items\n/collections/y/items| features[0].links[rel=self]" shape = "record" ]; "collectionX-items" [ label = " Collection x Items\n/collections/x/items| features[0].links[rel=self]" shape = "record" ]; "collectionY-item1" [ label = " Item y:1\n/collections/y/items/1|links[rel=parent]\l|links[rel=collection]\l" shape = "record" ]; "collectionX-item1" [ label = " Item x:1\n/collections/x/items/1|links[rel=parent]\l|links[rel=collection]\l" shape = "record" ]; "item-search" [ label = " Item Search\n/items|features[0].links[rel=self]\l|features[1].links[rel=self]\l" shape = "record" ]; "/":l3 -> "collections":f0; "/":l4 -> "collectionX":f0; "/":l5 -> "collectionY":f0; "/":l6 -> "item-search":f0; "/":l7 -> "service-desc"; "/":l8 -> "service-doc"; "/":l9 -> "conformance"; "item-search":f1 -> "collectionX-item1":f0; "item-search":f2 -> "collectionY-item1":f0; "collections":c2 -> "collectionY":f0; "collections":c1 -> "collectionX":f0; "collectionY":l0 -> "collectionY-items":f0; "collectionY-items":f1 -> "collectionY-item1":f0; cxi2 [shape=point,width=0.01,height=0.01]; cxi2 -> "collectionY":f0; "collectionY-item1":l0 -> cxi2 [dir=none]; "collectionY-item1":l1 -> cxi2 [dir=none]; "collectionX":l0 -> "collectionX-items":f0; "collectionX-items":f1 -> "collectionX-item1":f0; cxi1 [shape=point,width=0.01,height=0.01]; cxi1 -> "collectionX":f0; "collectionX-item1":l0 -> cxi1 [dir=none]; "collectionX-item1":l1 -> cxi1 [dir=none]; } ================================================ FILE: stac-spec/.circleci/config.yml ================================================ version: 2 jobs: test_examples_node: working_directory: ~/stac docker: - image: circleci/node:12 steps: - checkout - run: name: install command: npm install - run: name: validate command: npm run check-examples # test_examples_python: # working_directory: ~/stac # docker: # - image: circleci/python:3.8 # steps: # - checkout # - run: # name: install # command: pip install stac-validator # - run: # name: validate # command: find ./examples -type f -name "*.json" | xargs -L1 stac_validator test_docs: working_directory: ~/stac docker: - image: circleci/node:12 steps: - checkout - run: name: install command: npm install - run: name: validate command: npm run check-markdown publish_schemas: working_directory: ~/stac docker: - image: circleci/node:12 steps: - checkout - run: name: install command: npm install - add_ssh_keys: fingerprints: - "9b:0a:88:ff:12:d1:29:9a:ff:bb:72:ab:7d:81:df:59" - run: name: publish command: npm run publish-schemas -- $CIRCLE_TAG workflows: version: 2 ci: jobs: - test_examples_node # - test_examples_python - test_docs - publish_schemas: filters: tags: only: /^v.*/ branches: ignore: /^((?!dev).)*$/ ================================================ FILE: stac-spec/.circleci/publish-schemas.js ================================================ const klaw = require('klaw-sync'); const path = require('path'); const fs = require('fs'); const ghpages = require('gh-pages'); function filterFn (item) { const basename = path.basename(item.path); return basename === '.' || basename === 'node_modules' || basename[0] !== '.'; } let args = process.argv.slice(2); let tag = 'dev'; if (args.length && args[0].trim().length > 0) { tag = args[0]; } var folder = '.'; var jsonSchemaFolderPattern = path.sep + 'json-schema' + path.sep; for (let file of klaw(folder, {filter: filterFn})) { if (file.path.includes(jsonSchemaFolderPattern) && path.extname(file.path) === '.json') { let source = file.path; let target = 'schemas' + path.sep + tag + path.sep + path.relative(folder, file.path); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.copyFileSync(source, target); console.log(target); } } ghpages.publish('schemas/' + tag, { 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: stac-spec/.circleci/rc.yaml ================================================ plugins: # Check links - validate-links # Apply some recommended defaults for consistency - remark-preset-lint-consistent - remark-preset-lint-recommended - lint-no-html # General formatting - - remark-lint-emphasis-marker - '*' - remark-lint-hard-break-spaces - remark-lint-blockquote-indentation - remark-lint-no-consecutive-blank-lines - - remark-lint-maximum-line-length - 150 # Code - remark-lint-fenced-code-flag - remark-lint-fenced-code-marker - remark-lint-no-shell-dollars - - remark-lint-code-block-style - 'fenced' # Headings - remark-lint-heading-increment - remark-lint-no-multiple-toplevel-headings - remark-lint-no-heading-punctuation - - remark-lint-maximum-heading-length - 70 - - remark-lint-heading-style - atx - - remark-lint-no-shortcut-reference-link - false # Lists - remark-lint-list-item-bullet-indent - remark-lint-ordered-list-marker-style - remark-lint-ordered-list-marker-value - remark-lint-checkbox-character-style - - remark-lint-unordered-list-marker-style - '-' - - remark-lint-list-item-indent - space # Tables - remark-lint-table-pipes - remark-lint-no-literal-urls ================================================ FILE: stac-spec/.github/pull_request_template.md ================================================ **Related Issue(s):** # **Proposed Changes:** 1. 2. **PR Checklist:** - [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master). - [ ] This PR has **no** breaking changes. - [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-spec/blob/dev/CHANGELOG.md) **or** a CHANGELOG entry is not required. - [ ] This PR affects the [STAC API spec](https://github.com/radiantearth/stac-api-spec), and I have opened issue/PR #XXX to track the change. ================================================ FILE: stac-spec/.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/ package-lock.json # 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 # Folder created when CI puhlishes JSON Schemas schemas/ ================================================ FILE: stac-spec/CHANGELOG.md ================================================ # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [v1.0.0] - 2021-05-25 ### Added - Updated best practices to add a recommendation to include title in links where possible. ([#1133](https://github.com/radiantearth/stac-spec/pull/1133)) ### Changed - Updated version numbers for 1.0.0 release. - Final UML tweaks for latest changes. ([#1134](https://github.com/radiantearth/stac-spec/pull/1134)) - Removed ItemCollection from the STAC detection heuristic in Best Practices. It can't easily be differentiated from GeoJSON FeatureCollections any longer. ([API#141](https://github.com/radiantearth/stac-api-spec/issues/141)) ## [v1.0.0-rc.4] - 2021-05-11 ### Changed - An empty Catalog is now allowed, removed the requirement that it must have a child or item link. ([#1115](https://github.com/radiantearth/stac-spec/issues/1115)) - An open date range to both sides is now allowed in the Collection's temporal extents. ([#1125](https://github.com/radiantearth/stac-spec/issues/1125)) - Catalog and Collection JSON Schemas don't have a common JSON Schema any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122)) ### Removed - Catalogs don't support summaries any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122)) ### Fixed - Added clarification around when an extension should be included in `stac_extensions`. ([#1123](https://github.com/radiantearth/stac-spec/pull/1123)) - JSON Schemas don't allow "shortcuts" for core extensions any longer. ([#1121](https://github.com/radiantearth/stac-spec/pull/1121)) - Various examples fixes. ## [v1.0.0-rc.3] - 2021-04-29 ### Added - Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045)) - Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090)) - Recommendation to include both `root` and `parent` relation types when they point at the same file. ([#1098](https://github.com/radiantearth/stac-spec/issues/1098)) - Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) ### Changed - The first extent in a Collection is always the overall extent, followed by more specific extents. ([#1064](https://github.com/radiantearth/stac-spec/issues/1064), [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520)) - Updated examples for automatic collection creation from code and validation ([#1080](https://github.com/radiantearth/stac-spec/pull/1080)) - Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077)) - The Stats Object for Summaries has been renamed to Range Object (no functional change). ([#1093](https://github.com/radiantearth/stac-spec/pull/1093)) - `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095)) - Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106)) - Clarified that gsd should only be used on an asset to represent the sensor, not just different processing. ([#1105](https://github.com/radiantearth/stac-spec/pull/1105)) - Clarified that leaving a field out is not equivalent to setting it as null. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) ## [v1.0.0-rc.2] - 2021-03-30 ### Changed - Required properties of type `string` require a minimum length of `1`. ([#1065](https://github.com/radiantearth/stac-spec/pull/1065)) - `gsd` must be greater than 0. ([#1068](https://github.com/radiantearth/stac-spec/pull/1068)) ### Removed - The remaining extensions in the spec (EO, Projection, Scientific Citation and View) have been moved out of the core specification, into their own repos in the [stac-extensions](https://github.com/stac-extensions/) GitHub organization. They must now be referred to by their schemas directly - the name shortcuts for them are no longer valid. The concept of the 'named shortcut' also goes away entirely. ([#1070](https://github.com/radiantearth/stac-spec/pull/1070)) ### Fixed - Examples - Collection Assets were specified as required (only in written text, not in JSON Schema), but that was incorrectly copied over from the former `collection-assets` extension. Collection Assets are not required. - Clarified that the values in summaries (both for ranges and sets of values) must follow the data type of the property they summarize. ([#1069](https://github.com/radiantearth/stac-spec/pull/1069)) ## [v1.0.0-rc.1] - 2021-03-03 ### Added - Catalog and Collection now require a `type` parameter, to be set to `Catalog` or `Collection` for clients to more easily distinguish them easily. ([#971](https://github.com/radiantearth/stac-spec/pull/971)) - Collection specification adds Assets (previously needed Collections Asset extension to do that). ([#1008](https://github.com/radiantearth/stac-spec/pull/1008)) - 'via' and 'canonical' rel types are now options in Items. ([#884](https://github.com/radiantearth/stac-spec/pull/884)) - In Extensions list there is now reference to three new (non-core) extensions: [processing](https://github.com/stac-extensions/processing), [file info](https://github.com/stac-extensions/file) and [card4l](https://github.com/stac-extensions/card4l). These would have been added to the stac-spec repo, except all non-core extensions were moved to [stac-extensions](https://github.com/stac-extensions/) org. ([#1024](https://github.com/radiantearth/stac-spec/pull/1024)) - 'summaries' are now available in the Catalog spec, so both catalogs and collections can make use of it. ([#903](https://github.com/radiantearth/stac-spec/issues/903)) - There is a new recommendation to enable CORS. ([#940](https://github.com/radiantearth/stac-spec/pull/940)) - A Best Practice section on 'requester pays' cloud buckets was added. ([#1021](https://github.com/radiantearth/stac-spec/pull/1021)) - A new Best Practice section explains Asset Roles, plus some lists of potential roles for people to use (in best practices, sar and eo). ([#989](https://github.com/radiantearth/stac-spec/pull/989)) - There is a new Best Practice recommendation to keep collections at consistent levels. ([#1009](https://github.com/radiantearth/stac-spec/pull/1009)) ### Changed - The [Stats Object](collection-spec/collection-spec.md#range-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema. ([#967](https://github.com/radiantearth/stac-spec/pull/967)) - URIs (usually found int properties like `href`, `url`) are now validated using the `iri-reference` format in JSON Schema (allows international characters in URIs) ([#953](https://github.com/radiantearth/stac-spec/pull/953)) - Enhanced the way the spec talks about ID's to encourage more global uniqueness. ([#883](https://github.com/radiantearth/stac-spec/pull/883)) - Clarified how collection-level asset object properties do not remove the need for item-level asset object properties in the `item-assets` extension ([#880](https://github.com/radiantearth/stac-spec/pull/880)) - Made `summaries` to be *strongly recommended* - everyone should strive to implement them, as they are very useful. ([#985](https://github.com/radiantearth/stac-spec/pull/985)) - Moved examples from individual directories into a single /examples folder at the root, and evolved them to be more representative. ([#955](https://github.com/radiantearth/stac-spec/pull/955)) - Renamed "Scientific Extension" to "Scientific Citation Extension" ([#990](https://github.com/radiantearth/stac-spec/issues/990)) - Relaxed the regular expression for DOIs in the scientific extension ([#910](https://github.com/radiantearth/stac-spec/issues/910)) - `proj:geometry` allows all GeoJSON geometries instead of just a polygon. ([#995](https://github.com/radiantearth/stac-spec/pull/995)) ### Removed - Checksum extension (field `checksum:multihash`). Use File Info extension (field `file:checksum`) instead for assets. There's no replacement for links. ([#934](https://github.com/radiantearth/stac-spec/pull/934)) - Collection Assets extension, as the core construct of Assets in a Collection is now part of the core Collection spec. No change is required except removing `collection-assets` from the list of `stac_extensions`. ([#1008](https://github.com/radiantearth/stac-spec/pull/1008)) - Numerous extensions (Data Cube, Item Assets, Point Cloud, SAR, Single File STAC, Tiled Assets, Timestamps & Versioning) have been moved out of the core specification, into their own repos in the [stac-extensions](https://github.com/stac-extensions/) GitHub organization. They must now be referred to by their schemas directly - the name shortcuts for them are no longer valid. ([#1024](https://github.com/radiantearth/stac-spec/pull/1024)) ### Fixed - Fixed JSON Schema for `providers` (Collections and Items) to be an object and require a `name`. ([#924](https://github.com/radiantearth/stac-spec/pull/924)) ## [v1.0.0-beta.2] - 2020-07-08 ### Added - JSON-schema file in the Point Cloud extension. ### Changed - Clarification on null geometries, making bbox not required if a null geometry is used. - Multiple extents (bounding boxes / intervals) are allowed per Collection - In the scientific extension, a link with the rel-type 'cite-as' SHOULD be used for the main publication of the dataset (the same as the one described in `sci:doi`), and not for the DOIs referenced in the `sci:publications` property. ### Removed - Validation instructions ### Fixed - Fixed several JSON Schemas - Fixed examples ## [v1.0.0-beta.1] - 2020-05-29 ### Removed - The API portion of STAC has been split off into a [new repository: stac-api-spec](https://github.com/radiantearth/stac-api-spec) and will start being versioned and released separately than the core STAC spec. - proj4 string from proj extension - Various warnings about how the spec is very early and likely will change. - implementations.md (migrated to ) and how-to-help.md (migrated to ). - `commons` extension completely removed: Items should contain all properties and not default to a common set at the Collection level - ItemCollection removed from stac-spec core repo, will migrate to [stac-api-spec](https://github.com/radiantearth/stac-api-spec) as that is the only place it is used. ### Added - 'alternate' as a listed 'rel' type with recommended 'text/html' to communicate there is an html version. - Added a code of conduct based on github's template. - Overview document that gives a more explanatory discussion of the various parts of the spec and how they relate - Several new sections to 'best practices' document. - Added the ability to define Item properties under Assets (item-spec/item-spec.md) - Add `proj:shape` and `proj:transform` to the projections extension. - Collection-level assets extension - Instructions on how to run check-markdown locally - Timestamps extensions (adds fields `published`, `expires` and `unpublished`) - `created` and `updated` can be used in the assets to specify the creation / update times of the assets. - [Tiled Assets extension](https://github.com/stac-extensions/tiled-assets/blob/main/README.md), for representing data that has been split into tiles ### Changed - [Label extension](https://github.com/stac-extensions/label/blob/main/README.md) types were clarified and types in README and JSON schema were brought into alignment - Moved item recommendations to best practices, and added a bit more in item spec about 'search' - Moved `eo:gsd` from `eo` extension to core `gsd` field in Item common metadata - `asset` extension renamed to `item-assets` and renamed `assets` field in Collections to `item_assets` - `item-assets` extension only requires any two fields to be available, not the two specific fields `title` and `type` - `datetime` allows `null` as value, but requires `start_datetime` and `end_datetime` then - Extensions `sat`, `scientific` and `view`: At least one field is required to be specified. - [Single File STAC extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) changed to be a complete STAC catalog + GeoJSON FeatureCollection that contains collections and items. - Improved several JSON Schemas ### Fixed - Datacube extension: `cube:dimensions` was not flagged as required. ## [v0.9.0] - 2020-02-26 ### Added - ItemCollection requires `stac_version` field, `stac_extensions` has also been added - A `description` field has been added to Item assets (also Asset definitions extension) - Field `mission` to [Common Metadata fields](item-spec/common-metadata.md) - Extensions: - [Version Indicators extension](https://github.com/stac-extensions/version/blob/main/README.md), new `version` and `deprecated` fields in STAC Items and Collections - Data Cube extension can be used in Collections, added new field `description` - [Asset Extension](https://github.com/stac-extensions/item-assets/blob/main/README.md): new `description` and `roles` fields - New [Projection Extension](https://github.com/stac-extensions/projection/blob/main/README.md) to describe Items with Assets that have an associated geospatial projection - New [View Geometry Extension](https://github.com/stac-extensions/view/blob/main/README.md) - STAC API: - Added the [Item and Collection API Version extension](https://github.com/radiantearth/stac-api-spec/tree/master/extensions/version/README.md) to support versioning in the API specification - Run `npm run serve` or `npm run serve-ext` to quickly render development versions of the OpenAPI spec in the browser - [Basics](item-spec/common-metadata.md#basics) added to Common Metadata definitions with new `description` field for Item properties - New fields to the `link` object to facilitate [pagination support for POST requests](https://github.com/radiantearth/stac-api-spec/tree/master/api-spec.md#paging-extension) - `data` role, as a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics - Clarification text on HTTP verbs in STAC API ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html) - Collection field `property` and the merge ability moved to a new extension 'Commons' - Added field `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel` - Updated API yaml to clarify bbox filter should be implemented without brackets. Example: `bbox=160.6,-55.95,-170,-25.89` - Collection `summaries` merge array fields now - Several fields have been moved from extensions or item fields to the [Common Metadata fields](item-spec/common-metadata.md): - `eo:platform` / `sar:platform` => `platform` - `eo:instrument` / `sar:instrument` => `instruments`, also changed from string to array of strings - `eo:constellation` / `sar:constellation` => `constellation` - `dtr:start_datetime` => `start_datetime` - `dtr:end_datetime` => `end_datetime` - Moved angle definitions from extensions `eo` and new `view` extension - `eo:off_nadir` -> `view:off_nadir` - `eo:azimuth` -> `view:azimuth` - `eo:incidence_angle` -> `view:incidence_angle` - `eo:sun_azimuth` -> `view:sun_azimuth` - `eo:sun_elevation` -> `view:sun_elevation` - Extensions: - Data Cube extension: Changed allowed formats (removed PROJ string, added PROJJSON / WKT2) for reference systems - [Checksum extension](https://github.com/stac-extensions/checksum/blob/main/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)) - Changed `sar:type` to `sar:product_type` and `sar:polarization` to `sar:polarizations` in the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` - Sort Extension - added non-JSON query/form parameter format - Fields extension has a simplified format for GET parameters - `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context` - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support - Query Extension - type restrictions on query predicates are more accurate, which may require additional implementation support - Item `title` definition moved from core Item fields to [Common Metadata Basics](item-spec/common-metadata.md#basics) fields. No change is required for STAC Items. - `putFeature` can return a `PreconditionFailed` to provide more explicit information when the resource has changed in the server - [Sort extension](https://github.com/radiantearth/stac-api-spec/tree/master/extensions/sort) now uses "+" and "-" prefixes for GET requests to denote sort order. - Clarified how `/search` links must be added to `/` and changed that links to both GET and POST must be provided now that the method can be specified in links ### Removed - `version` field in STAC Collections. Use [Version Extension](https://github.com/stac-extensions/version/blob/main/README.md) instead - `summaries` field from Catalogs. Use Collections instead - Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `roles` instead - `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead - Extensions: - `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - Removed from EO extension field `eo:epsg` in favor of `proj:epsg` - `gsd` and `accuracy` from `eo:bands` in the [EO extension](https://github.com/stac-extensions/eo/blob/main/README.md) - `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - Datetime Range (`dtr`) extension. Use the [Common Metadata fields](item-spec/common-metadata.md) instead - STAC API: - `next` from the search metadata and query parameter - In API, removed any mention of using media type `multipart/form-data` and `x-www-form-urlencoded` ### Fixed - The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private - Clarified how to fill `stac_extensions` - More clarifications; typos fixed - Fixed Item JSON Schema now `allOf` optional Common Metadata properties are evaluated - Clarified usage of optional Common Metadata fields for STAC Items - Clarified usage of paging options, especially in relation to what OGC API - Features offers - Allow Commonmark in asset description, as it's allowed everywhere else - Put asset description in the API - Fixed API spec regarding license expressions - Added missing schema in the API Version extension - Fixed links in the Landsat example in the collection-spec ## [v0.8.1] - 2019-11-01 ### Changed - Updated specification to base on OGC API - Features - Part 1: Core, v1.0.0 instead of OGC API - Features - Part 1: Core, v1.0.0-draft.2 (fka WFS3 draft 2). ### Fixed - Numerous typos, clarifications and fixes for documentation and examples. - Fixed STAC API definition to include STAC-related fields and examples in *OGC API - Features*-derived endpoints. - Fixed JSON schemas for extensions: `$id` field matches file name. ## [v0.8.0] - 2019-10-11 ### Changed - Updated specification to base on WFS3 draft 2 (OGC API - Features - Part 1: Core, v1.0.0-draft.2). This leads to many changes in the API and one change in STAC collections, notably: - The structure of the field `extent` in STAC and WFS Collections changed. - Query parameter `time` was renamed to `datetime` and accepts slightly different values. - WFS links have additional fields `hreflang` and `length`. - WFS Collections have additional fields `crs` and `itemType`. - `time` API parameter changed to `datetime` - The API intersects parameter now accepts a GeoJSON Geometry (any type) *instead* of a GeoJSON Feature. - API: Clarification on `include` and `exclude` parameters in the field extension and notes on default values. - API: queries should contain either `bbox` or `intersects`. - API: Core API now has reserved parameters to prevent overlap with extensions - Updated bbox definitions in API, Item, and Collection specs to include support for optional elevation values. - Moved Single Item Extension to core (`license` and `providers` properties for Items). - Allow `various` for the `license` fields. - Clarified meaning of SAR and EO platform, constellation, and instrument - Numerous typos, clarification and general word-smithing - Changed GeoTIFF media type from `image/vnd.stac.geotiff` to `image/tiff; application=geotiff`, changed Cloud-optimized GeoTiff media type from `image/vnd.stac.geotiff; cloud-optimized=true` to `image/tiff; application=geotiff; profile=cloud-optimized`. ### Added - **stac_version**: Each Item must specify the STAC version. - **stac_extensions**: Introduced this field for Items, Catalogs and Collections. - Property `summaries` have been added to catalogs and collections. - API Transaction extension supports optimistic locking through use of the ETag header. - Asset Definition Extension added to Collections to allow specifying details about Assets that may appear in member Items. - [Single File Catalog extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) added as a format to have a set of Collections and Items in a single file. - [Label extension](https://github.com/stac-extensions/label/blob/main/README.md) added with additional fields for describing labeled data, such as used for training data or from the output of a classification - Timestamp fields added to `Item`: `created` and `updated` to refer to the datetime the metadata file was created or updated. - Added Search Metadata API extension which adds fields to a response from a STAC API such as the number of items found and how many were returned. - ItemCollection class added to spec that is a GeoJSON FeatureCollection of Items, such as what would be returned from a search. Located in item directory. - `in` operator added to the query extension (to check if value is in a list of values) - New bands added to the [common band names](https://github.com/stac-extensions/eo/blob/main/README.md#common-band-names) for the EO extension: yellow, rededge, and 2 narrow NIR bands - [Scientific extension](https://github.com/stac-extensions/scientific/blob/main/README.md) can be used in Collections. ### Fixed - Updated language, fixed typos and examples. - Renamed `pc:schema` to `pc:schemas` in the Point Cloud extension. ### Changes since 0.8.0rc1 - [Label extension](https://github.com/stac-extensions/label/blob/main/README.md): - moved label:classes to be a list of Class Objects from a single Class Object in spec markdown and json schema (matching previous example JSON). - moved label:overview to be a list of Overview Objects from a single Overview Object in spec markdown and json schema (matching previous example JSON). - Renamed fields to use plural forms (`label:property` -> `label:properties`, `label:task` -> `label:tasks`, `label:method` -> `label:methods` and `label:overview` -> `label:overviews`) ## [v0.7.0] - 2019-05-06 ### Fixed - Updated language / fixed typos - Moved static vs dynamic discussion text to catalog best practices document - Moved hosting of interactive api docs from swaggerhub to [stacspec.org](http://stacspec.org) - JSON Schemas are now all following the latest JSON Schema version, draft 07. ### Changed - No longer require an absolute self link for Items, Collections and Catalogs. - Reorganized api-spec, added extensions folder to hold API extensions - Change the fields parameter in the API to allow filtering on any property. - Refinements to SAR extension, changed several fields from a single array-based field (`sar:absolute_orbit`, `sar:resolution`, `sar:pixel_spacing`, `sar:looks`) to multiple fields with exactly one value. - Commons extension ability to 'merge' properties is now in the core specification ### Added - Catalog best practices document, including recommendations for catalog layouts, html, and self-contained catalogs. - `page` parameter for STAC API - Optional `collection` property field in Items (previously part of the Commons extension) - It is now required to link to `/stac/search/` from `/stac/` - Added new fields to SAR extension: `sar:incidence_angle`, `sar:relative_orbit`, `sar:observation_direction` - Added new filter parameters `ids` and `collections` to `/stac/search/` ### Removed - Removed the field `sar:off_nadir` from the SAR extension - JavaScript-based validation ## [v0.6.2] - 2019-03-01 ### Fixed - Fixed several examples and typos, improved descriptions - Strictly checking the STAC version numbers in the JSON schemas - Added missing required fields in Item JSON schema - Changed `id` to `$id` in JSON schemas (draft-06 compatibility) ### Changed - Extensions require examples and a JSON schema to get to the maturity level 'Pilot' - Updated ISERV implementation ### Added - Checksum extension - Data Cube extension - Point Cloud extension - SAR extension ## [v0.6.1] - 2019-01-25 ### Fixed - Added `null` as potential data type to `eo:epsg` in the EO extension. - Fixed several examples and typos. - Updated JSON Schema versions for uniformity - Added OpenEO GEE implementation - Clarified 'intersects' behavior for STAC API ## [v0.6.0] - 2018-11-06 ### Fixed - Reorganized and cleaned up repository. - Fixed examples throughout. ### Added - **Changelog**: This changelog added. - **Collections added**: Collections are a type of Catalog with additional fields, such as provider and license. Items must belong to a single Collection. - **Extension maturity**: Protocol for providing maturity classification for extensions based on stability and implementations. - **Commons extension**: The previous 'Collections' extension is now the 'Commons' extension and allows an Item to inherit properties from its Collection. - **Datetime-range extension**: Extension for providing start and end datetimes. - **Scientific extension**: Extension for providings links to scientific publications relating to the data. - **rel types**: A list of supported `rel` types are provided for use when specifying links, `derived_from` and `license` types added. - **eo:constellation**: A new field in the EO specification to specify a grouping of platforms. - **stac_version**: The `stac_version` field is required on all Catalogs (and Collections). - **JSON schemas**: Added JSON schemas where they were missing. - **Single Item extension**: Extension to supply License and Providers for single Items when no collection is used. - **UML Diagram**: See STAC-060-uml.pdf. - **Development Process**: See process.md for information on the STAC development process. ### Changed - **API**: Main catalog endpoint at `/stac`, search endpoint now at `/stac/search`. - **eo:bands**: The `eo:bands` field is now an array rather than a dictionary, and has been moved inside of `properties` in a STAC Item. - **Catalog fields**: Catalogs have a smaller number of basic fields: `id`, `stac_version`, `title` (optional), `description`, and `links`. The new Collections type contains additional fields. - **links**: The links fields are now an array rather than a dictionary. - **properties**: Fields with the data type array or objects are allowed inside the `properties` in a STAC Item. - **description**: Description fields now allow formatting with CommonMark. - **assets**: Fields changed names: `name` to `title` and `mime_type` to `type`. ### Removed - **provider**: Provider field in Items got removed. Use Collections or the Single Item extension instead. - **license**: License field in Items got removed. Use Collections or the Single Item extension instead. ## [v0.5.2] - 2018-07-12 Minor bug fixes on 0.5.1 for the schema files. Thanks @francbartoli ## [v0.5.1] - 2018-07-06 Minor bug fixes from 0.5.1 release - [Update openapi / swagger specs for new 'links'](https://github.com/radiantearth/stac-spec/commit/480d4fb02b4a7e880c7ca01320fe2773260ba595) - [minor fixes on collection extension](https://github.com/radiantearth/stac-spec/pull/124) - thanks @m-mohr - [minor cbers example updates](https://github.com/radiantearth/stac-spec/pull/123) - thanks @fredliporace ## [v0.5.0] - 2018-07-01 The 0.5.0 release of the STAC spec is an iteration forward on the spec, with a number of core improvements. Highlights include: - **Links is now a dictionary** - This is the most core change done. It aligns the structure with the 'asset' change in 0.5.0, making it easier for clients to look up the link that they want more easily. The schema is updated to this (and actually checks assets better now, thanks @mojodna ) - **Transactions Extension** - There is now a transaction extension for the STAC API, thanks to @hgs-msmith and @hgs-trutherford - **Collections iterations** @matthewhanson has evolved the collections extension, adding in some namespace type hints on it, and explaining it more clearly. - **eo:crs to eo:epsg** In the EO profile @matthewhanson brought in a change to use EPSG code, instead of full Well Known Text, to make it easy to reference. Full list of issues and pull requests at ## [v0.4.1] - 2018-04-24 A few minor improvements on the release. ([issues](https://github.com/radiantearth/stac-spec/issues?utf8=%E2%9C%93&q=milestone%3A0.4.1+)) - @hgs-msmith got a swagger version of the spec, and made some minor improvements to the openapi version #103 and #102 - @francbartoli and @m-mohr pointed out some inconsistencies with landsat, so got the openapi updated #106 - @m-mohr pointed out some issues with landsat example, so updated those #105 - @hgs-trutherford pointed out that the planet example was a bit confusing, so updated it to the EO profile. ## [v0.4.0] - 2018-04-06 The 0.4.0 is the first 'official' release of the SpatioTemporal Asset Catalog (STAC) specification! It is the result of the [ft. collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co), the second in person meeting of the STAC community. But it also includes a number of improvements from remote contributors. Highlights include: - Updates to the core **`Item` JSON specification**, including simplifying to a single datetime, moving thumbnails from 'links' to 'assets', making assets a dictionary for easier lookup and requiring `self` links to be absolute links. - Alignment of **STAC API** with the new [WFS3](https://github.com/opengeospatial/WFS_FES/) specification - Cleanup of the **static catalog** specification for greater clarity around the catalog - A first cut of an **Earth Observation Profile**, as well as a new collections extension to support it. - Numerous small improvements and bug fixes. See the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/stac-spec/milestone/3) for the complete lists of improvements. Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkamin, @hemphillda, @jeffnaus and @fredliporace for contributing to the spec directly, and to [everyone](https://github.com/opengeospatial/wfs3hackathon/blob/master/notes/introductions.md#participants) who participated in the [Ft Collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) and brought great ideas. [Unreleased]: [v1.0.0]: [v1.0.0-rc.4]: [v1.0.0-rc.3]: [v1.0.0-rc.2]: [v1.0.0-rc.1]: [v1.0.0-beta.2]: [v1.0.0-beta.1]: [v0.9.0]: [v0.8.1]: [v0.8.0]: [v0.7.0]: [v0.6.2]: [v0.6.1]: [v0.6.0]: [v0.5.2]: [v0.5.1]: [v0.5.0]: [v0.4.1]: [v0.4.0]: ================================================ FILE: stac-spec/CODE_OF_CONDUCT.md ================================================ # Contributor Covenant Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members Examples of unacceptable behavior by participants include: - The use of sexualized language or imagery and unwelcome sexual attention or advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information, such as a physical or electronic address, without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers 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, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [homepage]: For answers to common questions about this code of conduct, see ================================================ FILE: stac-spec/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 has been built that can highlight the problem. If the changes can be done as an [extension](extensions/) instead of modifying the core files then that route is recommended first, and once there is uptake for the extension it will be considered for core. 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. The next phase of STAC's evolution will be mostly focused on this broader ecosystem, while keeping the core spec as stable as we can. ### Submitting Pull Requests Any proposed changes to the specification should be done as pull requests. Please make these requests against the [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch (this will require you to switch from the default of 'master', which we keep so it displays first). Creating a Pull Request will show our PR template, which includes checkbox reminders for a number of things. - Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this is not required, but any change to the actual specification should definitely have one. - Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds you to change the base in GitHub's PR creation page. - Make a ticket in the STAC API repo if anything here affects there. - Highlight if the PR makes breaking changes to the specification (in beta there can still be select breaking changes, but after 1.0 this will change) 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 dev to master (and require 3 approvals), see the [process](process.md) document for more details. ### Check files The same check-markdown and check-examples 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/). Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of `npm` with `yarn` below. First you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on your command line run: ```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 check the examples run: ```bash npm run check-examples ``` To automatically format / pretty-print the examples run: ```bash npm run format-examples ``` ================================================ FILE: stac-spec/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: stac-spec/README.md ================================================ stac-logo [![CircleCI](https://circleci.com/gh/radiantearth/stac-spec.svg?style=svg)](https://circleci.com/gh/radiantearth/stac-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 at a certain place and time. The original focus was on scenes of satellite imagery, but the specifications now cover a broad variety of uses, including sources such as aircraft and drone and data such as hyperspectral optical, synthetic aperture radar (SAR), video, point clouds, lidar, digital elevation models (DEM), vector, machine learning labels, and composites like NDVI and mosaics. STAC is intentionally designed with a minimal core and flexible extension mechanism to support a broad set of use cases. This specification has matured over the past several years, and is used in [numerous production deployments](https://stacindex.org/catalogs). This is advantageous to providers of geospatial data, as they can simply use a well-designed, standard format and API without needing to design their own proprietary one. This is advantageous to consumers of geospatial data, as they can use existing libraries and tools to access metadata, instead of needing to write new code to interact with each data provider's proprietary formats and APIs. The STAC specifications define related JSON object types connected by link relations to support a [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)-style traversable interface and a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API providing additional browse and search interfaces. Typically, several STAC specifications are composed together to create an implementation. The **Item**, **Catalog**, and **Collection** specifications define a minimal core of the most frequently used JSON object types. Because of the hierarchical structure between these objects, a STAC catalog can be implemented in a completely 'static' manner as a group of hyperlinked Catalog, Collection, and Item URLs, enabling data publishers to expose their data as a browsable set of files. If more complex query abilities are desired, such as spatial or temporal predicates, the **STAC API** [specification](https://github.com/radiantearth/stac-api-spec/) can be implemented as a web service interface to query over a group of STAC objects, usually held in a database. To the greatest extent possible, STAC uses and extends existing specifications. The most important object in STAC is an **Item**, which is simply a [GeoJSON](http://geojson.org) **Feature** with a well-defined set of additional attributes ("foreign members"). The **STAC API** extends the **[OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)** with additional web service endpoints and object attributes. ## Current version and branches The [master branch](https://github.com/radiantearth/stac-spec/tree/master) is the 'stable' version of the spec. It is currently version **1.0.0** of the specification. The STAC specification follows [Semantic Versioning](https://semver.org/), so any breaking change will require the spec to go to 2.0.0. The [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development takes place, and may have inconsistent examples. Whenever dev stabilizes, a release is cut and we merge `dev` in to `master`. So `master` should be stable at any given time. More information on how the STAC development process works can be found in [process.md](process.md). ## Communication Our [gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby) is the best place to ask questions or provide feedback. The majority of communication about the evolution of the specification takes place in the [issue tracker](https://github.com/radiantearth/stac-spec/issues) and in [pull requests](https://github.com/radiantearth/stac-spec/pulls). ## In this Repository This repository contains the core object type specifications, [examples](examples/), validation schemas, and documentation about the context and plans for the evolution of the specification. Each folder contains a README explaining the layout of the folder, the main specification document, examples, and validating schemas. Additionally, the [STAC API specification](https://github.com/radiantearth/stac-api-spec/) provides API endpoints, based on the [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) standard, that enable clients to search for Item objects that match their filtering criteria. The **Item**, **Catalog**, **Collection**, and **STAC API** specifications are intended to be used together, but are designed so each piece is small, self-contained, and reusable in other contexts. - **[Overview](overview.md)** describes the three core object type specifications and how they relate to one another. - **[Item Specification](item-spec/)** defines a STAC **Item**, which is a [GeoJSON](http://geojson.org) **Feature** with additional fields ("foreign members") for attributes like time and links to related entities and assets (including thumbnails). This is the core entity that describes the data to be discovered. - **[Catalog Specification](catalog-spec/)** specifies a structure to link various STAC Items together to be crawled or browsed. It is a simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways. - **[Collection Specification](collection-spec/)** provides additional information about a spatio-temporal collection of data. In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider. It includes things like the spatial and temporal extent of the data, the license, keywords, etc. It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data. - **[Examples](examples/):** The *[examples/](examples/)* folder contains examples for all three specifications, linked together to form two complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts. - **[Extensions](extensions/README.md)** describe how STAC can use extensions that extend the functionality of the core spec or add fields for specific domains. Extensions can be published anywhere, although the preferred location for public extensions is in the [GitHub `stac-extensions` organization](https://github.com/stac-extensions). - **Additional documents:** The supporting documents include a complementary [best practices](best-practices.md) document, and information on contributing (links in the next section). We also maintain a [changelog](CHANGELOG.md) of what was modified in each version. ## Contributing Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate. Beforehand, please review our [guidelines for contributions](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md). You may also be interested in our overall [process](process.md), and the [principles](principles.md) that guide our collaboration ================================================ FILE: stac-spec/STAC-UML.drawio ================================================ 7V1pc5vIuv41rrrnVomiu1k/eomTScaTOM7+JYUEljhBQkHIS379aRCN6AUEUoOQB09VxqA2IJ63n373PkOX86fXkbOc3YSuF5xB1X06Q1dnEAIEAP5fcuZ5c8ZW7c2JaeS7m1Pq9sSd/8fL/pKcXfuut8rObU7FYRjE/pI+OQkXC28SU+ecKAof6WH3YeBSJ5bO1ONO3E2cgD/71XfjWXYWqOr2gzeeP51lt7b07IO5QwZnJ1Yzxw0fC6fQqzN0GYVhvPlt/nTpBcnLo9/Ldcmn+YNF3iKu8wdv1n99//nJ+A2n7t8jdP7mFbr5PALA3FznwQnW2VdWFeX/s0eOn8l78BbuefI68dEiXOCTF7N4HuAjgH/FH2bIAfy1LlaxE8VktOs783Dhfpr5C/IRGauRE9d+kF/Kxa8/u20YxbNwGi6c4NX27IUT+FN8qavAu8ff++LBi2If43WenR6HcRzO04eKo+dv+IxKDr4nB4pODq+eih9ePedHbvY8yRH/lrMXvwrX0cSreLVGJq1ONPXiinFQ3wxMvnnhDhmIr71w7uHHwwOyOTVSFQvB7OrZrBolB8lx5AVO7D/Qwutkc2CaXyu//IfQx98rvzYCqqIWfgB1F2hr9AU37yC7RlH0mMvqmqpAZKm2nv1LXVYDlgJsVTON7F+dvsvmDVbchQwM7+9XHjUG/1J4hdtT6dRoNE0sbpoE/uLXipsnsfcU05Mj8lb+H2ecDkgkapk8dfrE+sWZflWQ6AmWMS8SyPTcd91U9gNn7AUXzuTXNArXC/cyDMIovS+6T3+EArtj4uN7eU+UvGRcmj0zRVcigcQio0NaUojwHyiOtJDb9J+3iDaH9cSJnSCccmivHv154KR0eB8uYkJcCeyTmR+4fzvP4TqBAdPc5Bc5upiFkf8Hj3eIjBRpEX9rfDXMQEV09eQ/6i/vkitmIpWKmPeBYA6YUzfOEzXwb2cVZycmYRA4y5U/zp97jmebv7jIWDQdtIqj8JdXeBwj/cm+dOH85qeKNTlpK5WqXAPI0AeEJx8LyzBZhWeFFRhYsFzOKFFpKheQk4sE1p/4O638cHGWiCsm0PTrF34VEwT9TrMltYh6dmrHaheHy+RiS2fiL6Z/p2OutO2Zj9lrSU6F+G/vg3RNnmE+8ZLlOApjJy7lpgv8di+TBROzFLzEx2B7nBLXEq/Ql+ECfxfHT4H2sGQ9eol01eah2nJBFiGjnhiQcYdIwVXsvnv/KgDXj8vb6epzAPAUHyFOCuLnpTfgLBlnoiR0gfPjyLgG2oe7wHKNH98eVPUbvBkBHuh0umNcvUUy4UsX/wHzPTE3re4wFz4xDzkePqAsF2WgakeGWecp3I+DgcOlI43UIyNtcEi73moS+cs41dgGvOXirXeonIkfmdyNMdTP0Dm2RfFxapZxwBe8W+MgTOyqghsIMM6uQz1UG7nwnvw4907h3wvOKXy09U0lB1vX1H4urWZ4Fz1blZrRTtdWc88WVI3sj3LPVrZYHOhKwNcueJhsFRmmTd0IGIx/oa5za0R7KYDJmJ8l7issb85zYVg2vcu/gMF4Q8COp2IeS0PM5No8QPeuNJV3r/xf4nL+DzcrWc9ZYRLWdQLXcJiljpvMI91kshCmEXvLmrg6yMQ7VMRZv6pFX6FNTHnXCMW6Ky+4P4NGkGA1jvBv0+Q3akgaCKkekmHSB/LeN7ZASF+BepH3K1l/f/auGlck7yo/x07yzon6QCnOrmOZ+9EwQJZSiDAgi5oL0FJbYWXIrFYI7mBl+6Dx2eLYAxLnLeWExMHJkTjsG4kzaomuKzb10xWn83FhP/bmHLxDBKS1CIhusBGQDJNHKhHhjLOugFlhXmW3+5hI+2KaOD3I/TSTuR/g3XFGDWPOCWIvWjixd5HM1lUbwslHY+lIzGDXV7FeWeS3UcxFJHjEVpPui+fVy8EV3y7kusBz1ynkvJU4uOKlo2wKPPFtoSx8Yk2cV8MYjj0w+HLDzbaLllviVsIWS6XTDh988CIfv7AkuaeJSZfhudOky15iAz8bUE3acpGTsAM0WoVgfWF1jTmtXgpYU2stj0c8U2JdblLSw0fQqvXU4uHHs9Y0m5tkp2isEa7oja1GcpuZpLf2AeXxHFJQWlgdbUE6gnB1bC2axStB43H4NAAtGWgA6+pB7cUtOaQTxwSmucGebQHv2tZNa3kJvEVL6b0uVhgfPPfnfRTyPrdjBjxAs4BHMwSLMYkqo7CBomvYJh0JyKfaoYu/Sjtq2Whb7bgFm+dcs/yhse7LeBO1al2WHW4Z/dBlDXHg4dSix2T+90aXRbQuC5hwWYuhJN4DULHyDeGGFgsuaPNVA6KCC120SKrl0naYVsQbOoOfvz7J5FPrsOIKIeQtIQ55vWgwbdtAWlhe0RLSb8eXt8/a2vQvL5fz8/err1d3psC/P4R0WsZcWF7RJeb85B5iOvJhFtdXdImzoERuqK9oBWphgUWXUGsc1EOBRZuACyssugScr5365T0/hpE7LNjy0Sal7EdDm88CDPwJVtAGLpdve6nHVs/4YrnVej53It8b5rZ8uFGHWtr958n45vzux/n1u89f9N+vrWtrPkL82t20aINUZBxU2THqXbAjS/ZJknvShlbb+jzVsM6aJvu0XbWXid7uwo9sYDHKUmWaNynb0wETZUHZynFoOrxtMtfdswXViHZuAvZRZFXp2YwfvTrKwg6ni/o6ibKIqYHX8nqeMVTJcL2JsuBpoQC6MBNiIkD0daTg6nxB4Jvz4eKbe2lZT6P/zr7HbwVOt6E4+gCarXJy7WTZuvV1VNImw7KanFj2iOQB5zHofWuhTaiYWmkDQWBDBcHCx5JD3czjlz6lZQu/bu3xR6ilFk5n3p/a81h4FSn9G0laHAPj3acpS7OgDrHw1mLhGpP5jUi+xo5SuNwfKz8wymtks8jjayMGu1w8lw4JgdcpepQHNG+VJ8rZgLNknAUB8G5x5r1tQ6ZDG0ALot7dAs370IdoaCtIiwLf3ULN5zJS1x60t060N9Ng+tZjhb7Y1Z40Lyl63om/signZImQLyd8XiNxkONv8/bu/T/4w+3dNg7zgS928IWUbEeRHLTXbpZfGpZRuEyQEYTcBsYQM0Ymocm3kcQfOmP9qYLGK7pgYTGtlgSF+PkEhIHRXLhO5CauxELu5MAZdTgDSWmFIhKF1jhD4334RBQWycsYpKFDaRBlUXcqDTovDaUa5ylu4VTciokEhcBZ/aBQ6WqwO1ou6JNYqXc0COSgfI+jQzfIsZmVCjIRlbqBG4Np3AHt/m3CRCZbPW3pFKV9z6aikjYsIzV/DQRZtRGzERmSE5E0ICPY1p6CzelyNdsz1xHspskhJmQnmVr97OxLyJ5dGHeUNsv46NNL2xCwYQ27eBVSlaQ/YnElsg1YuRbVawTVdLa2sb+gbuu0ByVv+X7gtNYtNq6273qFhRJo0NLNzb+IuqwJkWIWPmbMsj6sZeLcy9PdT1Av89b2aDtBWkhGbKOFFtHmg7fOitxrcPF0002XtE4m1EO6ohVsN1OQfp1X3Mi33fgI4BDSr8E0em3oy302IqTbM9L5sNAQAWwFaYE/plukeYf+UA7ZIt6C2H5beMP3P//yV/fANBcfXRS653/CkWiPyCGJow2gRaH9TpGGfAQmCoOhMK4FqAU17Z2SuMFD/dI8IAWnR77/0OEext37wTV0RWBTUNVoqw3I2Q7OYJpdIbYUoXanambTDI1tlb7T2ZB3i6b/rsUWenzMKLVGT9f5kM/YHjsfdMWii2x0BVjUzj6duSNsPpBy9+kcX0sFCn4B+P83oSvIOU5h8twM+seZH3t3eB1KPn2MnCUtKcViEIEHwkt/ShfKgvND5QmulIEaZPgz01a4Ua3FrzqtJfgDVdRr4VQ3yCtFqD71a6Tn6JYh5dQUc/sq6XtWuyEAqy8kqai47IF31J+Rvo5MI9euWAaovNuj50XE1ROzRwVqzEYTHXZrFbSkpyhIuEncESuIpSeLVO6I3KRlgkbX8kpSbBGj2GIdQ5j73JTrdJ12n0PAmF+yuK7kPkdvPA0I2Z9OtW31DO4NnTFhuc7qbPNO66XtEAp9qF/i3sXNnACl7LjT7AfNM+Q0TWcbykjKQGB0KWyw70eIiC0RZjOUJBGixuzqTR64fBMqejzKslrLxkPDOmg8aRPeA4Lm46knqW8SWuoNQY8YUQfMFt1tYspXSqV57UPqRIepE8CmdUqTbH1S9NALst5bq58DgiJ5wEnE4J9vnFMo6BBXPS/ru3N0oDHuHFkb8TAZvibaN1WY8ZRoLa3okKFTw+rLCipoMrKMwgff9aKBb7vjW02l+VY3eL61BHwL2tueTtCtYuHMh0SHXboclJGsJsK6vX23eQffkMLUJuCCvQjbArzkkXk//ZDa0g7Wgv3WhVi3x+N8kHEdDd2l5CMN1JrTuj2oedP5xaQxUQVZ0vq+HmImVa6lDRyfVo5bHvWWk38CgdjqaF56xZovbEvuxmbSMQqw8ixDga1zuolQ20nf40yoEVI0g8p8Et5FqgwIpydv07xMgjykmfbB+z0LSFWYYI14Tq1WV5uQqmmx9axyRNkyaZ+WZjOu8dpppExhrCm7NTZ5YJ2OthqgugSdG4+MyvEGPHC83n24X8gNws5cp7M6VPJdn9cGCBXVKOarQGbiMpeUIgHi2h5OAibhfJ64QFR8acfFNgknCYNTtKMWbbbKRKFJesCuTkxIk2BwaRfgZvoYfbl3ltc/5h+81fmPpWAnxLxF29JZkKSQrPBz8wG+T/GzGsSyQwPISaMGAa3jcJVpI0JMKieF/H5pEvKqr2L33ftXAbh+XN5OV58DgGegYBqLYKFcnP8acLQOwbm9NX6fv7nWPv5B34N/bj58v7VvBeBgWvVivzyycMqv2+jwdQufmPcITSIPv3C37G3/Cx2AcqC26kLdWmUy795YL90B6xawzjODjwY25LBOFcifu8h0gHxfyJFgr9ZOIecbD3gLdwB8l6EhCX6Dj+N1C7+ofdiwL3MrWNt8IK9brAVJWYET34cRX2g1gH2gtQqOrbfxMQk/eQXrubcoL9Af8N4Xb1L9cTS8eT/zJHkH+C+dId+qFX/UsTU3Pttq7q9WA9YtYG13qKYJnY+8YTZdDQa4bJwRPLaKJqgN5lAWl3oWW6TQYfuSXip0D2oSxc+rRGpsj62YaUymENXPOldXVpjgo72aV1dBvDPYTzY72RnrLyJPKjwPbRFFmjkS7+2+eytYTEm7zjYelhTbty06ls5UZvLjmfYlu8ZbTOlsZeWnrChsHhos+LaWGFYn+cuhFLDr0hS2vYRJCsGoPdREtYBtxTQgT73jcfg0LLLVi2wD6CsiuSKkZRQqiB+ZD1/F3hy/i4EL+sEFpEvnIVyQ3e1jko20mCapEtsqZKaRlaBPKIA1tD4nwCrMwom9iySfasXJpYRVS5Bc7Cd5Xg/OUGuxi5jKMpj7S0yI11FeRjV6nTILVTV22Q57tOLa396orlcvWhyV6kSD7GJsTtHJaNm9Di3Y0GzFti3V1iFK/gW0OWLaBvUxpK9f1zjZcRfLhooJsjsgi/kSsgriLdpAIhX8pc/Mjte6L6AXEwGvi+bGipj1+5QzXM1tPU4apkUWaArb06lFxPk4/Eum/qQfN03/mPrqsb+qwKKzCvSU/hv2NcH0byBS1ZvnqEM5C4CavO+ce1WboWbNwsy93eZszya2my7r5XexkQKt7UZrLa0AjCvKzDz3x2d0PtFia3OeKqWfwFZteF7Z9A99G02xzWKVSBtVIcKIDp+M8SJrBku5tkkPR11jetHKccwjtk8T2zl/30pmvWbRXRt7w5Z9qdL2k/ph43VYPZ57N1Cus184ufjkl9PZmKKSLXrMtMfZl0JYDcJbT6QWZ02qcO5iZ+E6kYuHnW920FQ/hqmX8NPzMmlZk9furLeFO2xj3ni2no8Xjh/wHyU+sQffe+Q/2dT7sWfJGdd/YE8Vi4e2BYMltUX5aepCjNQ323+jxD9d7SouRpnLXMfyN+MwmOpnDdX0JJsSokpCUeTNurL82tXMWXrpMh97u1EZ56zyfh0H/oL49LFM/3qfuGjj542dlUJVyA2Q8Zbp8LCoq5zWUuRO+I5FOcyFjtllL/yoLbMp45eyfDXa9N2mWLBm7D7tGErRL5q+b8eXt8/a2vQvL5fz8/err1d3JlmBioZvlcA36OdpIaZxO/GvH9rP0xRrHo3VO3whRWXMBhMoEIHt2sa0a5BkzgKGz3Z1WeDGZ1XvXZq/QqngrZ2ed9SuIpr+9NNmNjZiPDdS4BSSgaC344uxXjOGHiVz3izSND4D7N35baKOOceMWAk8lsKBJPrZxGNpmbpIAA+1y7mtEPfdU5GJ9OskriLBLpc2lXhjJdFeTsJUreaGHtuqZFK0yJv3nyfjm/O7H+fX7z5/0X+/tq6t+Qjxjol993+pHJRmJFWxcde7ZzFBm7oZxnSIqNtGjOINQptxpKpoQKVljdzqUAlm3Xxoz4ZhbDtHxDaNkBWZ0eiZjLLdY8uVbnTQeHiEyI94zvOVWT3XfSupqz/KL7IUSKsfozY8jOK3waeQ9nP3wj2pdMvbZn3eLuXfJjlQusZkYcjZqxXTgcIoqxpbPlF7C0ODpjJot0SZzHY5SKsOteTq7Z7jyfc4OmVqfNZrz3dIrCSJ3lCmxhEm2SxUKqb65eP3u59vR+ifp4u/7N+Lr/fTmaBDV7811sT+h5TZrm5SlMrVVnwgttsZ/ttPRzUqJURVAKZOGlxJmiagnUx5MWxzTZMtK2O2kJblNGUf2IKVz8WOJ8/VJQ0KpwzvGeghC9YmN1rqyzmidb2R2ddSa2Mjc+HX42OBLwfPaugAYqeYXg5bSSwQH6bukQIkkbOc3YRusoC8+h8= ================================================ FILE: stac-spec/best-practices.md ================================================ # STAC Best Practices ## Table of Contents - **[Web Best Practices](#web-practices)** - [Enable Cross-origin resource sharing (CORS)](#enable-cross-origin-resource-sharing-cors) - [STAC on the Web](#stac-on-the-web) - [Schema.org, JSON-LD, DCAT, microformats, etc](#schemaorg-json-ld-dcat-microformats-etc) - [Deploying STAC Browser](#deploying-stac-browser) - [Requester Pays](#requester-pays) - **[Item Best Practices](#item-practices)** - [Field and ID formatting](#item-ids) - [Searchable Identifiers](#searchable-identifiers) - [Field selection and Metadata Linking](#field-selection-and-metadata-linking) - [Datetime selection](#datetime-selection) - [Unlocated Items](#unlocated-items) - [Unrectified Satellite Data](#unrectified-satellite-data) - [Data that is not spatial](#data-that-is-not-spatial) - [Representing Vector Layers in STAC](#representing-vector-layers-in-stac) - **[Asset Best Practices](#asset-practices)** - [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets) - [Working with Media Types](#working-with-media-types) - [Common Media Types in STAC](#common-media-types-in-stac) - [Formats with no registered media type](#formats-with-no-registered-media-type) - [Asset Roles](#asset-roles) - [List of Asset Roles](#list-of-asset-roles) - [Thumbnail](#thumbnail) - [Overview](#overview) - [Visual](#visual) - **[Catalog & Collection Best Practices](#catalog--collection-practices)** - [Static and Dynamic Catalogs](#static-and-dynamic-catalogs) - [Static Catalogs](#static-catalogs) - [Dynamic Catalogs](#dynamic-catalogs) - [Catalog Layout](#catalog-layout) - [Dynamic Catalog Layout](#dynamic-catalog-layout) - [Mixing STAC Versions](#mixing-stac-versions) - [Using Summaries in Collections](#using-summaries-in-collections) - [Use of links](#use-of-links) - [Self-contained Catalogs](#self-contained-catalogs) - [Published Catalogs](#published-catalogs) - [Using Relation Types](#using-relation-types) - [Versioning for Catalogs](#versioning-for-catalogs) - [Example](#example) - [Static to Dynamic best practices](#static-to-dynamic-best-practices) - [Ingestion and links](#ingestion-and-links) - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services) - [How to Differentiate STAC Files](#how-to-differentiate-stac-files) This document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them are required to meet the core specification, but following these practices will make life easier for client tooling and for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for those who are creating STAC objects representing their data or creating tools to work with STAC. While the current goal of the core is to remain quite flexible and simple to meet a wide variety of use cases, in time some of these may evolve to become part of the core specification. ## Web Practices ### Enable Cross-origin resource sharing (CORS) STAC strives to make geospatial information more accessible, by putting it on the web. Fundamental to STAC's vision is that different tools will be able to load and display public-facing STAC data. But the web runs on a [Same origin policy](https://en.wikipedia.org/wiki/Same-origin_policy), preventing web pages from loading information from other web locations to prevent malicious scripts from accessing sensitive data. This means that by default a web page would only be able to load STAC [Item](item-spec/item-spec.md) objects from the same server the page is on. [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), also known as 'CORS' is a protocol to enable safe communication across origins. But most web services turn it off by default. This is generally a good thing, but unfortunately if CORS is not enabled then any browser-based STAC tool will not work. So to enable all the great web tools (like [stacindex.org](http://stacindex.org)) to work with your STAC implementation it is essential to 'enable CORS'. Most services have good resources on how to do this, like on [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html), [Google Cloud Storage](https://cloud.google.com/storage/docs/cross-origin), or [Apache Server](https://enable-cors.org/server_apache.html). Many more are listed on [enable-cors.org](https://enable-cors.org/server.html). We recommend enabling CORS for all requests ('\*'), so that diverse online tools can access your data. If you aren't sure if your server has CORS enabled you can use [test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) or [Collection](collection-spec/collection-spec.md) JSON and make sure it gets a response. ### STAC on the Web One of the primary goals of STAC is to make spatiotemporal data more accessible on the web. One would have a right to be surprised that there is nothing about HTML in the entire specification. This is because it is difficult to specify what should be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions of every STAC Item is paramount. The main recommendation is to have an HTML page for every single STAC Item, Catalog and Collection. They should be visually pleasing, crawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called [STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid STAC implementation and generate unique web pages for each Item and Catalog (or Collection). While it has a default look and feel, the design can easily be modified to match an existing web presence. And it will automatically turn any Item with a [Cloud Optimized GeoTIFF](http://cogeo.org) asset into an interactive, zoomable web map (using [tiles.rdnt.io](http://tiles.rdnt.io/) to render the tiles on a [leaflet](https://leafletjs.com/) map). It also attempts to encapsulate a number of best practices that enable STAC Items to show up in search engines, though that part is still a work in progress - contributions to STAC Browser to help are welcome! Implementors are welcome to generate their own web pages, and additional tools that automatically transform STAC JSON into html sites are encouraged. In time there will likely emerge a set of best practices from an array of tools, and we may be able to specify in the core standard how to make the right HTML pages. But for now it is useful for STAC implementations to focus on making data available as JSON, and then leverage tools that can evolve at the same time to make the best HTML experience. This enables innovation on the web generation and search engine optimization to evolve independently from the core data. #### Schema.org, JSON-LD, DCAT, microformats, etc There is a strong desire to align STAC with the various web standards for data. These include [schema.org](http://schema.org) tags, [JSON-LD](https://json-ld.org/) (particularly for Google's [dataset search](https://developers.google.com/search/docs/data-types/dataset)), [DCAT](https://www.w3.org/TR/vocab-dcat/) and [microformats](http://microformats.org/wiki/about). STAC aims to work with as many as possible. Thusfar it has not seemed to make sense to include any of them directly in the core STAC standard. They are all more intended to be a part of the HTML pages that search engines crawl, so the logical place to do the integration is by leveraging a tool that generates HTML from STAC like [STAC Browser](https://github.com/radiantearth/stac-browser/). STAC Browser has implemented a [mapping to schema.org](https://github.com/radiantearth/stac-spec/issues/378) fields using JSON-LD, but the exact output is still being refined. It is on the roadmap to add in more mapping and do more testing of search engines crawling the HTML pages. #### Deploying STAC Browser Most public STAC implementations have a STAC Browser hosted at [stacindex.org](https://stacindex.org/catalogs). Anyone with a public STAC implementation is welcome to have a STAC Browser instance hosted for free, just submit it to [stacindex.org](https://stacindex.org/add). But the stronger recommendation is to host a STAC Browser on your own domain, and to customize its design to look and feel like your main web presence. STAC aims to be decentralized, so each STAC-compliant data catalog should have its own location and just be part of the wider web. ### Requester Pays It is very common that large, freely available datasets are set up with a 'requester pays' configuration. This is an option [on AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) and [on Google Cloud](https://cloud.google.com/storage/docs/requester-pays), that enables data providers to make their data available to everyone, while the cloud platform charges access costs (such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data. For popular datasets that are large in size the egress costs can be substantial, to the point where much less data would be available if the cost of distribution was always on the data provider. For data providers using STAC with requester pays buckets, there are two main recommendations: 1. Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open data as requestor pays and aren't able to pay the costs of a completely open STAC bucket, as they are most all supportive of STAC (but no guarantees and it may be on an alternate cloud). 2. For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url. Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication, so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs that will add a requestor pays parameter and will apply appropriate authentication to the request. Using cloud-specific protocols will at least give users an option to register a paid account and allow the data provider to properly charge for access. STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform. ## Item Practices ### Item IDs When defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's data. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) endpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices. ### Searchable Identifiers When coming up with values for fields that contain searchable identifiers of some sort, like `constellation` or `platform`, it is recommended that the identifiers consist of only lowercase characters, numbers, `_`, and `-`. Examples include `sentinel-1a` (Sentinel-1), `landsat-8` (Landsat-8) and `envisat` (Envisat). This is to provide consistency for search across Collections, so that people can just search for `landsat-8`, instead of thinking through all the ways providers might have chosen to name it. ### Field selection and Metadata Linking In general STAC aims to be oriented around **search**, centered on the core fields that users will want to search on to find imagery. The core is space and time, but there are often other metadata fields that are useful. While the specification is flexible enough that providers can fill it with tens or even hundreds of fields of metadata, that is not recommended. If providers have lots of metadata then that can be linked to in the [Asset Object](item-spec/item-spec.md#asset-object) (recommended) or in a [Link Object](item-spec/item-spec.md#link-object). There is a lot of metadata that is only of relevance to loading and processing data, and while STAC does not prohibit providers from putting those type of fields in their items, it is not recommended. For very large catalogs (hundreds of millions of records), every additional field that is indexed will cost substantial money, so data providers are advised to just put the fields to be searched in STAC and [STAC API](https://github.com/radiantearth/stac-api-spec) providers don't have bloated indices that no one actually uses. ### Datetime selection The `datetime` field in a STAC Item's properties is one of the most important parts of a STAC Item, providing the T (temporal) of STAC. And it can also be one of the most confusing, especially for data that covers a range of times. For many types of data it is straightforward - it is the capture or acquisition time. But often data is processed from a range of captures - drones usually gather a set of images over an hour and put them into a single image, mosaics combine data from several months, and data cubes represent slices of data over a range of time. For all these cases the recommended path is to use `start_datetime` and `end_datetime` fields from [common metadata](item-spec/common-metadata.md#date-and-time-range). The specification does allow one to set the `datetime` field to `null`, but it is strongly recommended to populate the single `datetime` field, as that is what many clients will search on. If it is at all possible to pick a nominal or representative datetime then that should be used. But sometimes that is not possible, like a data cube that covers a time range from 1900 to 2000. Setting the datetime as 1950 would lead to it not being found if you searched 1990 to 2000. Extensions that describe particular types of data can and should define their `datetime` field to be more specific. For example a MODIS 8 day composite image can define the `datetime` to be the nominal date halfway between the two ranges. Another data type might choose to have `datetime` be the start. The key is to put in a date and time that will be useful for search, as that is the focus of STAC. If `datetime` is set to `null` then it is strongly recommended to use it in conjunction with an extension that explains why it should not be set for that type of data. ### Unlocated Items Though the [GeoJSON standard](https://tools.ietf.org/html/rfc7946) allows null geometries, in STAC we strongly recommend that every item have a geometry, since the general expectation of someone using a SpatioTemporal Catalog is to be able to query all data by space and time. But there are some use cases where it can make sense to create a STAC Item before it gets a geometry. The most common of these is 'level 1' satellite data, where an image is downlinked and cataloged before it has been geospatially located. The recommendation for data that does not yet have a location is to follow the GeoJSON concept that it is an ['unlocated' feature](https://tools.ietf.org/html/rfc7946#section-3.2). So if the catalog has data that is not located then it can follow GeoJSON and set the geometry to null. Though normally required, in this case the `bbox` field should not be included. Note that this recommendation is only for cases where data does not yet have a geometry and it cannot be estimated. There are further details on the two most commonly requested desired use cases for setting geometry to null: #### Unrectified Satellite Data Most satellite data is downlinked without information that precisely describes where it is located on Earth. A satellite imagery processing pipeline will always attempt to locate it, but often that process takes a number of hours, or never quite completes (like when it is too cloudy). It can be useful to start to populate the Item before it has a geometry. In this case the recommendation is to use the 'estimated' position from the satellite, to populate at least the bounding box, and use the same broad bounds for the geometry (or leaving it null) until there is precise ground lock. This estimation is usually done by onboard equipment, like GPS or star trackers, but can be off by kilometers or more. But it is very useful for STAC users to be able to at least find approximate area in their searches. A commonly used field for communicating ground lock is not yet established, but likely should be (an extension proposal would be appreciated). If there is no way to provide an estimate then the data can be assigned a null geometry and no `bbox`, as described above. But the data will likely not show up in STAC API searches, as most will at least implicitly use a geometry. Though this section is written with satellite data in mind, one can easily imagine other data types that start with a less precise geometry but have it refined after processing. #### Data that is not spatial The other case that often comes up is people who love STAC and want to use it to catalog everything they have, even if it is not spatial. This use case is not currently supported by STAC, as we are focused on data that is both temporal and spatial in nature. The [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) is an emerging standard that likely will be able to handle a wider range of data than STAC. It builds on [OGC API - Features](https://github.com/opengeospatial/ogcapi-features) just like [STAC API](https://github.com/radiantearth/stac-api-spec/) does. Using [Collection Assets](collection-spec/collection-spec.md#asset-object) may also provide an option for some use cases. ### Representing Vector Layers in STAC Many implementors are tempted to try to use STAC for 'everything', using it as a universal catalog of all their 'stuff'. The main route considered is to use STAC to describe vector layers, putting a shapefile or [geopackage](http://geopackage.org) as the `asset`. Though there is nothing in the specification that *prevents* this, it is not really the right level of abstraction. A shapefile or geopackage corresponds to a Collection, not a single Item. The ideal thing to do with one of those is to serve it with [OGC API - Features](https://github.com/opengeospatial/ogcapi-features) standard. This allows each feature in the shapefile/geopackage to be represented online, and enables querying of the actual data. If that is not possible then the appropriate way to handle Collection-level search is with the [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API. Both are compliant with OGC API - Features, adding richer search capabilities to enable finding of data. ## Asset Practices ### Common Use Cases of Additional Fields for Assets As [described in the Item spec](item-spec/item-spec.md#additional-fields-for-assets), it is possible to use fields typically found in Item properties at the asset level. This mechanism of overriding or providing Item Properties only in the Assets makes discovery more difficult and should generally be avoided. However, there are some core and extension fields for which providing them at at the Asset level can prove to be very useful for using the data. - `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, but an Asset is for one specific time. - `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets that represent instruments with different spatial resolution than the overall best resolution. Note this should not be used for different spatial resolutions due to specific processing of assets - look into the [raster extension](https://github.com/stac-extensions/raster) for that use case. - `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset. - `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): Specify different projection for some assets. If the projection is different for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the Item and the alternate projection for the affected asset(s). - `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): If assets have different spatial resolutions and slightly different exact bounding boxes, specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection. - `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): Provide the polarization content and ordering of a specific asset, similar to `eo:bands`. - `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset. ### Working with Media Types [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for clients. The best practice is to use as specific of a media type as is possible (so if a file is a GeoJSON then don't use a JSON media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible. The following table lists types that commonly show up in STAC assets. And the the [section](#formats-with-no-registered-media-type) past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type. #### Common Media Types in STAC The following table lists a number of commonly used media types in STAC. The first two (GeoTIFF and COG) are not fully standardized yet, but reflect the community consensus direction. There are many IANA registered types that commonly show up in STAC. The following table lists some of the most common ones you may encounter or use. | Media Type | Description | | ------------------------------------------------------- | ------------------------------------------------------------ | | `image/tiff; application=geotiff` | GeoTIFF with standardized georeferencing metadata | | `image/tiff; application=geotiff; profile=cloud-optimized` | [Cloud Optimized GeoTIFF](https://www.cogeo.org/) (unofficial). Once there is an [official media type](http://osgeo-org.1560.x6.nabble.com/Media-type-tc5411498.html) it will be added and the custom media type here will be deprecated. | | `image/jp2` | JPEG 2000 | | `image/png` | Visual PNGs (e.g. thumbnails) | | `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | | `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | | `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | | `text/plain` | Plain text (often metadata) | | `application/geo+json` | [GeoJSON](https://geojson.org/) | | `application/geopackage+sqlite3` | [GeoPackage](https://www.geopackage.org/) | | `application/x-hdf5` | Hierarchical Data Format version 5 | | `application/x-hdf` | Hierarchical Data Format versions 4 and earlier. | *Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and Cloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`. Both can still appear in old STAC implementations, but are deprecated and should be replaced. This will, unfortunately, likely shift in the future as [OGC sorts out the media types](https://github.com/opengeospatial/geotiff/issues/34).* #### Formats with no registered media type Ideally every media type used is on the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml). If you are using a format that is not on that list we recommend you use [custom content type](https://restcookbook.com/Resources/using-custom-content-types/). These typically use the `vnd.` prefix, see [RFC 6838 section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). Ideally the format provider will actually register the media type with IANA, so that other STAC clients can find it easily. But if you are only using it internally it is [acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory) it. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type. ### Asset Roles [Asset roles](item-spec/item-spec.md#asset-roles) are used to describe what each asset is used for. They are particular useful when several assets have the same media type, such as when an Item has a multispectral analytic asset, a 3-band full resolution visual asset, a down-sampled preview asset, and a cloud mask asset, all stored as Cloud Optimized GeoTIFF (COG) images. It is recommended to use at least one role for every asset available, and using multiple roles often makes sense. For example you'd use both `data` and `reflectance` if your main data asset is processed to reflectance, or `metadata` and `cloud` for an asset that is a cloud mask, since a mask is considered a form of metadata (it's information about the data). Or if a single asset represents several types of 'unusable data' it might include `metadata`, `cloud`, `cloud-shadow` and `snow-ice`. If there is not a clear role in the [Asset Role Types](item-spec/item-spec.md#asset-role-types) or the following list then just pick a sensible name for the role. And you are encouraged to add it to the list below and/or in an extension if you think the new role will have broader applicability. #### List of Asset Roles In addition to the thumbnail, data and overview [roles listed](item-spec/item-spec.md#asset-role-types) in the Item spec, there are a number of roles that are emerging in practice, but don't have enough widespread use to justify standardizing them. So if you want to re-use other roles then try to find them on the list below, and also feel free to suggest more to include here. The 'source' field lists where the role comes from. The ones the say Item Spec are the only 'official' roles that are fully standardized. In time others on this list may migrate to a more 'official' list. Those that say 'best practice' are just from this doc, the listing is the table below. The ones from extensions are mostly just 'best practices' in the extensions, as there are few actual role requirements. | Role Name | Source | Description | | --------- | -------------|----------------------------------------------------------------------- | | thumbnail | [Item Spec](item-spec/item-spec.md#asset-role-types) | An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | | data | [Item Spec](item-spec/item-spec.md#asset-role-types) | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | | metadata | [Item Spec](item-spec/item-spec.md#asset-role-types) | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | | overview | Best Practice | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | | visual | Best Practice | An asset that is a full resolution version of the data, processed for visual use (RGB only, often sharpened ([pan-sharpened](https://en.wikipedia.org/wiki/Pansharpened_image) and/or using an [unsharp mask](https://en.wikipedia.org/wiki/Unsharp_masking))). | | date | Best Practice | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset | | graphic | Best Practice | Supporting plot, illustration, or graph associated with the Item | | data-mask | Best Practice | File indicating if corresponding pixels have Valid data and various types of invalid data | | snow-ice | Best Practice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. | | land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. | | water-mask | Best Practice | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | iso-19139 | Best Practice | Points to an [ISO 19139](https://www.iso.org/standard/67253.html) metadata xml file | | iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file | | reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. | | incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. | | local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. | Some of the particular asset roles also have some best practices: ##### Thumbnail Thumbnails are typically used to give quick overview, often embedded in a list of items. So think small with these, as keeping the size down helps it load fast, and the typical display of a thumbnail won't benefit from a large size. Often 256 by 256 pixels is used as a default. Generally they should be no more than 600 by 600 pixels. Some implementors provide different sizes of thumbnails - using something like thumbnail-small and thumbnail-large, with a small one being 100x100 pixels or less, for truly fast rendering in a small image. Be sure to name one just 'thumbnail' though, as that's the default most STAC clients will look for. Thumbnails should be PNG, JPEG, or WebP, so that they can easily display in browsers, and they should be a true color composite (red, green, and blue bands) if there are multiple bands. If your data for the Item does not come with a thumbnail already we do recommend generating one, which can be done quite easily. [GDAL](https://gdal.org/) and [Rasterio](https://rasterio.readthedocs.io/en/latest/) both make this very easy - if you need help just ask on the [STAC Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). ##### Overview An overview is a high-definition browse image of the dataset, giving the user more of a sense of the data than a thumbnail could. It's something that can be easily displayed on a map without tiling, or viewed at full screen resolution (but not zoomed in). Similar to a thumbnail it should be PNG, JPEG or WebP, for easy display in browsers, and should be a true color composite (red, green, and blue bands) if there are multiple bands. The sizes could range from the high end of a thumbnail (600 by 600 pixels) to a few thousand pixels on each side. ###### Visual A visual asset is a full-resolution version of the data, but one that is optimized for display purposes. It can be in any file format, but Cloud Optimized GeoTIFF's are preferred, since the inner pyramids and tiles enable faster display of the full resolution data. It is typically an composite of red, blue and green bands, often with a nice color curve and sharpening for enhanced display. It should be possible to open up on non-specialist software and display just fine. It can complement assets where one band is per file (like landsat), by providing the key display bands combined, or can complement assets where many non-visible bands are included, by being a lighter weight file that just has the bands needed for display ## Catalog & Collection Practices *Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the [Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, which can be any mix of Catalogs Collections and Items.* ### Static and Dynamic Catalogs As mentioned in the main [overview](overview.md), there are two main types of catalogs - static and dynamic. This section explains each of them in more depth and shares some best practices on each. #### Static Catalogs A static catalog is an implementation of the STAC specification that does not respond dynamically to requests. It is simply a set of files on a web server that link to one another in a way that can be crawled, often stored in an cloud storage service like [Amazon S3](https://aws.amazon.com/s3/), [Azure Storage](https://azure.microsoft.com/en-us/services/storage/) and [Google Cloud Storage](https://cloud.google.com/storage/). But any http server could expose a static catalog as files. The core JSON documents and link structures are encoded in the file, and work as long as things are structured properly. A static catalog can only really be crawled by search engines and active catalogs; it can not respond to queries. But it is incredibly reliable, as there are no moving parts, no clusters or databases to maintain. The goal of STAC is to expose as much asset metadata online as possible, so the static catalog offers a very low barrier to entry for anyone with geospatial assets to make their data searchable. Static catalogs tend to make extensive use of *sub-catalogs* to organize their Items into sensible browsing structures, as they can only have a single representation of their catalog, since the static nature means the structure is baked in. While it is up to the implementor to organize the catalog, it is recommended to arrange it in a way that would make sense for a human to browse a set of STAC Items in an intuitive matter. Users indicate their intent for a file to be parsed as a Collection or Catalog using the required `type` field on each entity. For Collections, this field must have the value `Collection`, while for Catalogs, it must have the value `Catalog`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json` or `collection.json` to distinguish the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice is to place the Catalog file in namespaces "directories". For example: - current/catalog.json - archive/catalog.json #### Dynamic Catalogs A dynamic catalog is implemented in software as an HTTP-based API, following the same specified JSON structure for Items, Catalogs and Collections. Its structure and responses are usually generated dynamically, instead of relying on a set of already defined files. But the result is the same, enabling the same discovery from people browsing and search engines crawling. It generally indexes data for efficient responses, and aims to be easy for existing APIs to implement as a more standard interface for clients to consume. A dynamic catalog will sometimes be populated by a static catalog, or at least may have a 'backup' of its fields stored as a cached static catalog. Dynamic catalogs often also implement the [STAC API](https://github.com/radiantearth/stac-api-spec/) specification, that responds to search queries (like "give me all imagery in Oahu gathered on January 15, 2017"). But they are not required to. One can have a dynamic service that only implements the core STAC specification, and is crawled by STAC API implementations that provide 'search'. For example a Content Management Service like Drupal or an open data catalog like CKAN could choose to expose its content as linked STAC Items by implementing a dynamic catalog. One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same Items in different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location (or at least use a `rel` link that indicates the location of the canonical one). ### Catalog Layout Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, Items and assets, and how to name them. The specification leaves this totally open, and you can link things as you want. But it is recommended to be thoughtful about the organization of sub-catalogs, putting them into a structure that a person might reasonably browse (since they likely will with [STAC on the Web](#stac-on-the-web) recommendations). For example start with location, like a normal grid (path+row in Landsat) or administrative boundaries (country -> state-level) and then year, month, day. Or do the opposite - date and then location. Making a huge unordered list is technically allowed, but not helpful for discovery of data. Thus it is generally considered a best practice to make use of sub-catalogs to keep the size of each sub-catalog under a megabyte. If your sub-catalog lists tens of thousands of child items then you should consider an additional way to break it up. We encourage people to explore new structures of linking data, but the following list is what a number of implementors ended up doing. Following these recommendations makes for more legible catalogs, and many tools operate more efficiently if you follow these recommendations. 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog. 2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`. 3. Items should be named `.json`. 4. Sub-Catalogs or sub-Collections should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent, e.g. `.../sample/sub1/catalog.json`). 5. Items should be stored in subdirectories of their parent Catalog or Collection. This means that each Item and its assets are contained in a unique subdirectory. 6. Limit the number of Items in a Catalog or Collection, grouping / partitioning as relevant to the dataset. 7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy. For example, if levels 2 and 4 of the hierarchy only contain Collections, don't add a Catalog at levels 2 and 4. One further recommendation to help tools is to always include the 'title' field when including a link, especially in the `item`, `child`, `parent` and `root` links, even if it repeats several times. This should be the same as the 'title' in the link destination. Having this enables clients to display a nice human readable name of the link without having to open the link destination. #### Dynamic Catalog Layout While these recommendations were primarily written for [static catalogs](#static-catalogs), they apply equally well to [dynamic catalogs](#dynamic-catalogs). Subdirectories of course would just be URL paths generated dynamically, but the structure would be the same as is recommended. One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same Items in different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location (or at least use a rel link that indicates the location of the canonical one). It is recommended that dynamic catalogs provide multiple 'views' to allow users to navigate in a way that makes sense to them, providing multiple 'sub-catalogs' from the root that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the canonical 'rel' link should be used to designate the primary location of the Item to search engine crawlers. #### Mixing STAC Versions Although it is allowed to mix STAC versions, it should be used carefully as clients may not support all versions so that the catalog could be of limited use to users. A Catalog or Collection linking to differently versioned Sub-Catalogs or Sub-Collections is a common use case when multiple data source are combined. Client developers should be aware of this use case. Nevertheless, it is strongly recommended that Catalogs don't contain differently versioned Items so that users/clients can at least use and/or download consistent (Sub-)Catalogs containing either all or no data. Collections that are referenced from Items should always use the same STAC version. Otherwise some behaviour of functionality may be unpredictable (e.g. merging common fields into Items or reading summaries). ### Using Summaries in Collections One of the strongest recommendations for STAC is to always provide [summaries](collection-spec/collection-spec.md#summaries) in your Collections. The core team decided to not require them, in case there are future situations where providing a summary is too difficult. The idea behind them is not to exhaustively summarize every single field in the Collection, but to provide a bit of a 'curated' view. Some general thinking on what to summarize is as follows: - Any field that is a range of data (like numbers or dates) is a great candidate to summarize, to give people a sense what values the data might be. For example in overhead imagery, a [`view:off_nadir`](https://github.com/stac-extensions/view/blob/main/README.md#item-properties-and-item-asset-fields) with a range of 0 to 3 would tell people this imagery is all pretty much straight down, while a value of 15 to 40 would tell them that it's oblique imagery, or 0 to 60 that it's a Collection with lots of different look angles. - Fields that have only one or a handful of values are also great to summarize. Collections with a single satellite may use a single [`gsd`](item-spec/common-metadata.md#instrument) field in the summary, and it's quite useful for users to know that all data is going to be the same resolution. Similarly it's useful to know the names of all the [`platform` values](item-spec/common-metadata.md#instrument) that are used in the Collection. - It is less useful to summarize fields that have numerous different discrete values that can't easily be represented in a range. These will mostly be string values, when there aren't just a handful of options. For example if you had a 'location' field that gave 3 levels of administrative region (like 'San Francisco, California, United States') to help people understand more intuitively where a shot was taken. If your Collection has millions of Items, or even hundreds, you don't want to include all the different location string values in a summary. - Fields that consist of arrays are more of a judgement call. For example [`instruments`](item-spec/common-metadata.md#instrument) is straightforward and recommended, as the elements of the array are a discrete set of options. On the other hand [`proj:transform`](https://github.com/stac-extensions/projection/blob/main/README.md#projtransform) makes no sense to summarize, as the union of all the values in the array are meaningless, as each Item is describing its transform, so combining them would just be a bunch of random numbers. So if the values contained in the array are independently meaningful (not interconnected) and there aren't hundreds of potential values then it is likely a good candidate to summarize. We do highly recommend including an [`eo:bands`](https://github.com/stac-extensions/eo/blob/main/README.md#eobands) summary if your Items implement `eo:bands`, especially if it represents just one satellite or constellation. This should be a union of all the potential bands that you have in assets. It is ok to only add the summary at the Collection level without putting an explicit `eo:bands` summary at the `properties` level of an Item, since that is optional. This gives users of the Collection a sense of the sensor capabilities without having to examine specific Items or aggregate across every Item. Note that the ranges of summaries don't have to be exact. If you are publishing a catalog that is constantly updating with data from a high agility satellite you can put the `view:off_nadir` range to be the expected values, based on the satellite design, instead of having it only represent the off nadir angles that are Items for assets already captured in the catalog. We don't want growing catalogs to have to constantly check and recalculate their summaries whenever new data comes in - its just meant to give users a sense of what types of values they could expect. ### Use of links The STAC specifications allow both relative and absolute links, and says that `self` links are not required, but are strongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it is essential to use different link types. The best practice is to use one of the below catalog types, applying the link recommendations consistently, instead of just haphazardly applying relative links in some places and absolute ones in other places. #### Self-contained Catalogs A 'self-contained catalog' is one that is designed for portability. Users may want to download a catalog from online and be able to use it on their local computer, so all links need to be relative. Or a tool that creates catalogs may need to work without knowing the final location that it will live at online, so it isn't possible to set absolute 'self' URL's. These use cases should utilize a catalog that follows the listed principles: - **Only relative href's in structural `links`**: The full catalog structure of links down to sub-catalogs and Items, and their links back to their parents and roots, should be done with relative URL's. The structural rel types include `root`, `parent`, `child`, `item`, and `collection`. Other links can be absolute, especially if they describe a resource that makes less sense in the catalog, like [sci:doi](https://github.com/stac-extensions/scientific/blob/main/README.md#item-and-collection-fields), `derived_from` or even `license` (it can be nice to include the license in the catalog, but some licenses live at a canonical online location which makes more sense to refer to directly). This enables the full catalog to be downloaded or copied to another location and to still be valid. This also implies no `self` link, as that link must be absolute. - **Use Asset `href` links consistently**: The links to the actual assets are allowed to be either relative or absolute. There are two types of 'self-contained catalogs'. #### Self-contained Metadata Only These consist of just the STAC metadata (Collection, Catalog and Item files), and uses absolute href links to refer to the online locations of the assets. #### Self-contained with Assets These use relative href links for the assets, and includes them in the folder structure. This enables offline use of a catalog, by including all the actual data, referenced locally. Self-contained catalogs tend to be used more as static catalogs, where they can be easily passed around. But often they will be generated by a more dynamic STAC service, enabling a subset of a catalog or a portion of a search criteria to be downloaded and used in other contexts. That catalog could be used offline, or even published in another location. Self-contained catalogs are not just for offline use, however - they are designed to be able to be published online and to live on the cloud in object storage. They just aim to ease the burden of publishing, by not requiring lots of updating of links. Adding a single `self` link at the root is recommended for online catalogs, turning it into a 'relative published catalog', as detailed below. This anchors it in an online location and enables provenance tracking. #### Published Catalogs While STAC is useful as a portable format to move between systems, the goal is really to enable search. While any combination of absolute and relative links is technically allowed by the specification, it is strongly recommended to follow one of the patterns described below when publishing online. Many clients will not properly handle arbitrary mixes of absolute and relative href's. We refer to a 'published catalog' as one that lives online in a stable location, and uses `self` links to establish its location and enable easy provenance tracking. There are two types of published catalogs: #### Absolute Published Catalog This is a catalog that uses absolute links for everything, both in the `links` objects and in the `asset` hrefs. It includes `self` links for every Item. Generally these are implemented by dynamic catalogs, as it is quite easy for them to generate the proper links dynamically. But a static catalog that knows its published location could easily implement it. #### Relative Published Catalog This is a self-contained catalog as described above, except it includes an absolute `self` link at the root to identify its online location. This is designed so that a self-contained catalog (of either type, with its assets or just metadata) can be 'published' online by just adding one field (the self link) to its root (Catalog or Collection). All the other links should remain the same. The resulting catalog is no longer compliant with the self-contained catalog recommendations, but instead transforms into a 'relative published catalog'. With this, a client may resolve Item and sub-catalog self links by traversing parent and root links, but requires reading multiple sources to achieve this. So if you are writing a STAC client it is recommended to start with just supporting these two types of published catalogs. In turn, if your data is published online publicly or for use on an intranet then following these recommendations will ensure that a wider range of clients will work with it. ### Using Relation Types Implementors of STAC are highly recommended to be quite liberal with their `links`, and to use the `rel` field (in conjunction with the `type` field) to communicate the structure and content of related entities. While each STAC spec describes some of the 'custom' relations STAC has set, the ideal is to reuse official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes a number of the common official relations that are used in production STAC implementations. | Type | Description | | --------- | ------------------------------------------------------------ | | alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | | canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | | via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel tileInfo.json, etc) | | prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | | next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | | preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#thumbnail) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. | Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the `parent` and `root` relation types will point at the same file when the child is directly below the root, and it is recommended to include both. ### Versioning for Catalogs In the Item and Collection STAC JSON, versions and deprecation can be indicated with the [Versioning Indicators Extension](https://github.com/stac-extensions/version). The [Items and Collections API Version Extension](https://github.com/stac-extensions/version/) provides endpoints and semantics for keeping and accessing previous versions of Collections and Items. The same semantics can be used in static catalogs to preserve previous versions of the documents and link them together. In order to achieve this, the static catalog must make sure that for every record created, a copy of the record is also created in a separate location and it is named with the version id adopted by the catalog. See [here](https://github.com/stac-extensions/version/blob/main/README.md#version-id) for recommendations on versioning schema. The main record should also provide a link to the versioned record following the linking patterns described [here](https://github.com/stac-extensions/version/blob/main/README.md#relation-types). For every update to the record, the same cycle is repeated: 1. Add link from the updated record to the previous version 2. Create a copy of the updated record and name it correctly #### Example When the record `my_item.json` is created, a copy of it is also created. `my_item.json` includes `permalink` to `my_item_01.json`. The version suffix of the file name is taken from the version field of the record when it is available. - `root / collections / example_collection / items / my_item / my_item.json` - `root / collections / example_collection / items / my_item / my_item_01.json` When `my_item.json` is updated, the new `my_item.json` includes a link to `my_item_01.json` and is also copied to `my_item_02.json`. This ensures that `my_item_02.json` includes a link to `my_item_01.json` - `root / collections / example_collection / items / my_item / my_item.json` - `root / collections / example_collection / items / my_item / my_item_01.json` - `root / collections / example_collection / items / my_item / my_item_02.json` ### Static to Dynamic best practices Many implementors are using static catalogs to be the reliable core of their dynamic services, or layering their STAC API on top of any static catalog that is published. These are some recommendations on how to handle this: #### Ingestion and links Implementors have found that it's best to 'ingest' a static STAC into an internal datastore (often elasticsearch, but a traditional database could work fine too) and then generate the full STAC API responses from that internal representation. There are instances that have the API refer directly to the static STAC Items, but this only works well if the static STAC catalog is an 'absolute published catalog'. So the recommendation is to always use absolute links - either in the static published catalog, or to create new absolute links for the STAC search/ endpoint responses, with the API's location at the base url. The `/` endpoint with the catalog could either link directly to the static catalog, or can follow the 'dynamic catalog layout' recommendations above with a new set of URL's. Ideally each Item would use its `links` to provide a reference back to the static location. The location of the static Item should be treated as the canonical location, as the generated API is more likely to move or be temporarily down. The spec provides the `derived_from` rel field, which fits well enough, but `canonical` is likely the more appropriate one as everything but the links should be the same. #### Keep catalogs in sync with cloud notification and queue services There is a set of emerging practices to use services like Amazon's Simple Queue Service (SQS) and Simple Notification Service (SNS) to keep catalogs in sync. There is a great [blog post](https://aws.amazon.com/blogs/publicsector/keeping-a-spatiotemporal-asset-catalog-stac-up-to-date-with-sns-sqs/) on the CBERS STAC implementation on AWS. The core idea is that a static catalog should emit a notification whenever it changes. The recommendation for SNS is to use the STAC Item JSON as the message body, with some fields such as a scene’s datetime and geographic bounding box that allows basic geographic filtering from listeners. The dynamic STAC API would then listen to the notifications and update its internal datastore whenever new data comes into the static catalog. Implementors have had success using AWS Lambda to do a full 'serverless' updating of the elasticsearch database, but it could just as easily be a server-based process. ## How to Differentiate STAC Files Any tool that crawls a STAC implementation or encounters a STAC file in the wild needs a clear way to determine if it is an Item, Collection or Catalog. As of 1.0.0 this is done primarily with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. ```shell if type is 'Collection' => Collection else if type is 'Catalog' => Catalog else if type is 'Feature' and stac_version is defined => Item else => Invalid (JSON) ``` When crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or `root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the the `type` field in the Catalog or Collection JSON that is linked to. Note that there is also a `type` field in STAC Link and Asset objects, but that is for the Media Type, but there are not specific media types for Catalog and Collection. See the sections on [STAC media types](catalog-spec/catalog-spec.md#media-types), and [Asset media types](item-spec/item-spec.md#asset-media-type) for more information. In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works for older STAC versions. ================================================ FILE: stac-spec/catalog-spec/README.md ================================================ # STAC Catalog Specification A STAC [Catalog](catalog-spec.md) is a top-level object that logically groups other Catalog, Collection, and [Item](../item-spec/item-spec.md) objects. A Catalog contains an array of Link objects to these other objects and can include additional metadata to describe the objects contained therein. It is defined in full in the [STAC Catalog Specification](catalog-spec.md). For more information on how the parts of STAC fit together see the [overview](../overview.md) document. A Catalog is typically the "entry point" into a STAC object hierarchy. For example, the root endpoint ("landing page") of a STAC API implementation is a Catalog. For many static STAC catalogs (e.g., those defined only by a set of files on disk or in a cloud object store), the root URL points to a Catalog that acts as the starting point to traverse the entire catalog of Catalog, Collection, and Item objects. While STAC Catalogs mostly describe a structure of links and Items, a key related specification is the [STAC Collection Specification](../collection-spec/collection-spec.md), which contains fields that further describe the group of Items in a Catalog. A STAC Catalog requires a subset of the fields required by a Collection. These are distinguished from one another by the `type` field, which will have the value `Catalog` or `Collection`. This means that a Collection can be changed to a Catalog simply by changing this `type` field. The parent-child relationships among Catalogs and Collections are for objects of these types, as there is no subtyping relationship between the Collection and Catalog types, even through they share field names. Catalogs are designed so that a simple file server on the web or object store like Amazon S3 can store JSON that defines a full Catalog. More dynamic services can also return a Catalog structure, and the [STAC API](https://github.com/radiantearth/stac-api-spec) specification contains an OpenAPI definition of the standard way to do this, at the `/` endpoint. ## In this directory **Specification:** The main Catalog specification is in *[catalog-spec.md](catalog-spec.md)*. It includes in depth explanation of the structures and fields. **Schemas:** The schemas to validate the core Catalog definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[catalog.json](json-schema/catalog.json)*. ## Catalog Evolution The Catalog specification is maturing, but it is still relatively early days. The core of Catalog has been defined very narrowly, to just describe a structure that can be followed by people or machines, so most additional functionality will be defined in additional specifications and extensions. The only anticipated changes to the core of Catalog are to add in additional extension mechanisms for others to use. ================================================ FILE: stac-spec/catalog-spec/catalog-spec.md ================================================ # STAC Catalog Specification - [Catalog fields](#catalog-fields) - [Additional Field Information](#additional-field-information) - [stac_version](#stac_version) - [stac_extensions](#stac_extensions) - [Link Object](#link-object) - [Relation types](#relation-types) - [Media Types](#media-types) - [Media Type for STAC Catalogs](#media-type-for-stac-catalogs) - [STAC Media Types](#stac-media-types) - [Extensions](#extensions) This document explains the structure and content of a STAC **Catalog** object. A STAC Catalog object represents a logical group of other Catalog, [Collection](../collection-spec/collection-spec.md), and [Item](../item-spec/item-spec.md) objects. These Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-catalogs) that contain links to Collections and Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of online browsing by people. A Catalog object will typically be the entry point into a STAC catalog. Their purpose is discovery: to be browsed by people or be crawled by clients to build a searchable index. Any JSON object that contains all the required fields is a valid STAC Catalog object. - [Examples](../examples/) - See an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid Catalog file, demonstrating linking to items (it is also a Collection, so has additional fields) - [JSON Schema](json-schema/catalog.json) The [Catalog section of the Overview](../overview.md#catalog-overview) document provides background information on the structure of Catalogs as well as links to best practices. This specification lays out the requirements and fields to be compliant. This Catalog specification primarily defines a structure for information to be discoverable. Any use that is publishing a set of related spatiotemporal assets is strongly recommended to also use the STAC Collection specification to provide additional information about the set of Items contained in a Catalog, in order to give contextual information to aid in discovery. STAC Collections all have the same fields as STAC Catalogs, but with different allowed values for `type` and `stac_extensions`. ## Catalog fields | Element | Type | Description | | --------------- | ------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | | stac_version | string | **REQUIRED.** The STAC version the Catalog implements. | | stac_extensions | \[string] | A list of extension identifiers the Catalog implements. | | id | string | **REQUIRED.** Identifier for the Catalog. | | title | string | A short descriptive one-line title for the Catalog. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the Catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | ### Additional Field Information #### stac_version In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. #### stac_extensions A list of extensions the Catalog implements. The list consists of URLs to JSON Schema files that can be used for validation. This list must only contain extensions that extend the Catalog specification itself, see the 'Scope' for each of the extensions. This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal with links. | Field Name | Type | Description | | ---------- | ------ | ----------- | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | | type | string | [Media type](#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. #### Relation types The following types are commonly used as `rel` types in the Link Object of a STAC Catalog: | Type | Description | | ------- | ----------- | | self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | | parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | | child | URL to a child STAC entity (Catalog or Collection). | | item | URL to a STAC Item. | **Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are allowed if there is an intent to populate it or its children were removed. There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use the ones above. ## Media Types One of the best ways to help inform web clients about the content in a link is to use a common [Media Type](https://en.wikipedia.org/wiki/Media_type) in the `type` field. In STAC the `type` field is used in both the '[Link](#link-object)'' and '[Asset](../item-spec/item-spec.md#asset-object)' Objects. It is quite useful for STAC browsers to better determine what to render and display to users searching and browsing the Catalog. Media types are often referred to by the now deprecated term "MIME types". ### Media Type for STAC Catalogs A STAC Catalog is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the [`application/json`](https://tools.ietf.org/html/rfc8259#section-11) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) (previously known as the MIME Type). ### STAC Media Types The following table lists the Media Types to use for STAC structures. | Media Type | Description | | ---------------------- | ---------------------------------------------------------- | | `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | | `application/json` | A STAC Catalog | | `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | ## Extensions The [extensions page](../extensions/) gives an overview about relevant extensions for STAC Catalogs. ================================================ FILE: stac-spec/catalog-spec/json-schema/catalog.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/catalog-spec/json-schema/catalog.json#", "title": "STAC Catalog Specification", "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.", "allOf": [ { "$ref": "#/definitions/catalog" } ], "definitions": { "catalog": { "title": "STAC Catalog", "type": "object", "required": [ "stac_version", "type", "id", "description", "links" ], "properties": { "stac_version": { "title": "STAC version", "type": "string", "const": "1.0.0" }, "stac_extensions": { "title": "STAC extensions", "type": "array", "uniqueItems": true, "items": { "title": "Reference to a JSON Schema", "type": "string", "format": "iri" } }, "type": { "title": "Type of STAC entity", "const": "Catalog" }, "id": { "title": "Identifier", "type": "string", "minLength": 1 }, "title": { "title": "Title", "type": "string" }, "description": { "title": "Description", "type": "string", "minLength": 1 }, "links": { "title": "Links", "type": "array", "items": { "$ref": "#/definitions/link" } } } }, "link": { "type": "object", "required": [ "rel", "href" ], "properties": { "href": { "title": "Link reference", "type": "string", "format": "iri-reference", "minLength": 1 }, "rel": { "title": "Link relation type", "type": "string", "minLength": 1 }, "type": { "title": "Link type", "type": "string" }, "title": { "title": "Link title", "type": "string" } } } } } ================================================ FILE: stac-spec/collection-spec/README.md ================================================ # STAC Collection Specification A STAC [Collection](collection-spec.md) object is used to describe a group of related Items. It builds on fields defined for a [Catalog](../catalog-spec/catalog-spec.md) object by further defining and explaining logical groups of [Items](../item-spec/item-spec.md). A Collection can have parent Catalog and Collection objects, as well as child Item, Catalog, and Collection objects. These parent-child relationships among objects of these types, as there is no subtyping relationship between the Collection and Catalog types, even through they share field names. A Collection provides a flexible mechanism to provide additional metadata about a set of Items. Generally, is used to describe a set of assets that are defined with the same properties and share higher-level metadata. There is no standardized name for this sort of logical grouping, but other places it is called a " dataset series" (ESA, ISO 19115), "collection" (CNES, NASA), "dataset" (JAXA), or "product" (JAXA). In GIS terms, the Items are '[features](https://en.wikipedia.org/wiki/Simple_Features)' (that link to assets) and a Collection is the 'layer'. STAC uses the same terms as the [OGC Features API](https://ogcapi.ogc.org/features/). A STAC Collection is a valid [Feature API Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4), extending it with additional fields. Thus, the additional fields in a Collection detail the type of information a user would want to know about the group of Items it contains. Items are required to provide a link back to their collection definition. But the Collection is independent of STAC Items and STAC Catalogs, and thus other parties can also use this specification standalone, as a way to describe collections in a lightweight way. For more details on how the STAC specs fit together see the [overview](../overview.md) document. ## In this directory **Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*. It includes an overview and in depth explanation of the structures and fields. **Schemas:** The schemas to validate the STAC Collection definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[collection.json](json-schema/collection.json)*. ## Collection Flexibility STAC Collections are defined for flexibility. They only require a handful of fields, and implementors are free to add most any JSON field or object that they want via extensions. This flexibility and extensibility is a design goal, so that it is quite easy to implement a collection and be able to adapt it to most any data model. Implementors are encouraged to do what makes sense for them, and to check out the [examples](../examples/) and [other implementations](https://stacindex.org/catalogs) for current best practices. ================================================ FILE: stac-spec/collection-spec/collection-spec.md ================================================ # STAC Collection Specification - [Overview](#overview) - [Collection fields](#collection-fields) - [Additional Field Information](#additional-field-information) - [stac_version](#stac_version) - [stac_extensions](#stac_extensions) - [id](#id) - [license](#license) - [summaries](#summaries) - [assets](#assets) - [Extent Object](#extent-object) - [Spatial Extent Object](#spatial-extent-object) - [Temporal Extent Object](#temporal-extent-object) - [Provider Object](#provider-object) - [Link Object](#link-object) - [Relation types](#relation-types) - [Asset Object](#asset-object) - [Range Object](#range-object) - [JSON Schema Object](#json-schema-object) - [Media Type for STAC Collections](#media-type-for-stac-collections) - [Standalone Collections](#standalone-collections) ## Overview The STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata. The Collection Specification shares all fields with the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) (with different allowed values for `type` and `stac_extensions`) and adds fields to describe the whole dataset and the included set of Items. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. A STAC Collection is represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. STAC Collections are compatible with the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4) JSON specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they are extended with additional fields. - [Examples](../examples/): - Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. - Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. - Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight various [extension](../extensions) functionality, but serves as another example. - [JSON Schema](json-schema/collection.json) ## Collection fields | Element | Type | Description | | --------------- | ------------------------------------------------ | ------------------------------------------------------------ | | type | string | **REQUIRED.** Must be set to `Collection` to be a valid Collection. | | stac_version | string | **REQUIRED.** The STAC version the Collection implements. | | stac_extensions | \[string] | A list of extension identifiers the Collection implements. | | id | string | **REQUIRED.** Identifier for the Collection that is unique across the provider. | | title | string | A short descriptive one-line title for the Collection. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the Collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | keywords | \[string] | List of keywords describing the Collection. | | license | string | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. | | providers | \[[Provider Object](#provider-object)] | 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. | | extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | | summaries | Map | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). | | links | \[[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | | assets | Map | Dictionary of asset objects that can be downloaded, each with a unique key. | ### Additional Field Information #### stac_version In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. #### stac_extensions A list of extensions the Collection implements. The list consists of URLs to JSON Schema files that can be used for validation. This list must only contain extensions that extend the Collection specification itself, see the the 'Scope' for each of the extensions. This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. #### id It is important that Collection identifiers are unique across the provider. And providers should strive as much as possible to make their Collection ids 'globally' unique, prefixing any common information with a unique string. This could be the provider's name if it is a fairly unique name, or their name combined with the domain they operate in. #### license Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the `license` link relation type. If no link to a license is included and the `license` field is set to `proprietary`, the Collection is private, and consumers have not been granted any explicit right to use the data. #### summaries Collections are *strongly recommended* to provide summaries of the values of fields that they can expect from the `properties` of STAC Items contained in this Collection. This enables users to get a good sense of what the ranges and potential values of different fields in the Collection are, without having to inspect a number of Items (or crawl them exhaustively to get a definitive answer). Summaries are often used to give users a sense of the data in [Standalone Collections](#standalone-collections), describing the potential values even when it can't be accessed as Items. They also give clients enough information to build tailored user interfaces for querying the data, by presenting the potential values that are available. Fields selected to be included in summaries should capture all the potential values of the field that appear in every Item underneath the collection, including in any nested sub-Catalogs. A summary for a field can be specified in three ways: 1. A set of all distinct values in an array: The set of values must contain at least one element and it is strongly recommended to list all values. If the field summarizes an array (e.g. [`instruments`](../item-spec/common-metadata.md#instrument)), the field's array elements of each Item must be merged to a single array with unique elements. 2. A Range in a [Range Object](#range-object): Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range specified by the `minimum` and `maximum` properties can specify the potential range of values, but it is recommended to be as precise as possible. 3. Extensible JSON Schema definitions for fine-grained information, see the [JSON Schema Object](#json-schema-object) section for more. All values must follow the schema of the property field they summarize, unless the field is an array as described in (1) above. So the values in the array or the values given for `minimum` and `maximum` must comply to the original data type and any further restrictions that apply for the property they summarize. For example, the `minimum` for `gsd` can't be lower than zero and the summaries for `platform` and `instruments` must each be an array of strings (or alternatively minimum and maximum values, but that's not very meaningful). It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. Nevertheless, it is not very useful to list all potential `title` values of the Items. Also, a range for the `datetime` property may be better suited to be included in the STAC Collection's `extent` field. In general, properties that are covered by the Collection specification should not be repeated in the summaries. See the [examples folder](../examples) for Collections with summaries to get a sense of how to use them. #### assets This provides an optional mechanism to expose assets that don't make sense at the Item level. It is a dictionary of [Asset Objects](#asset-object) associated with the Collection that can be downloaded or streamed, each with a unique key. In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers. Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them. To communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object). The definition provided here, at the Collection level, is the same as the [Asset Object in Items](../item-spec/item-spec.md#asset-object). There are a few guidelines for using the asset construct at the Collection level: - Collection-level assets SHOULD NOT list any files also available in Items. - If possible, item-level assets are always the preferable way to expose assets. Collection-level assets can be useful in some scenarios, for example: 1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes. 2. Individual Items can't properly be distinguished for some data structures, e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files. 3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)". Oftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use Items as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another option. ### Extent Object The object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified. | Element | Type | Description | | -------- | ------------------------------------------------- | --------------------------------------------------------------------- | | spatial | [Spatial Extent Object](#spatial-extent-object) | **REQUIRED.** Potential *spatial extents* covered by the Collection. | | temporal | [Temporal Extent Object](#temporal-extent-object) | **REQUIRED.** Potential *temporal extents* covered by the Collection. | #### Spatial Extent Object The object describes the spatial extents of the Collection. | Element | Type | Description | | ------- | ------------ | -------------------------------------------------------------------- | | bbox | \[\[number]] | **REQUIRED.** Potential *spatial extents* covered by the Collection. | **bbox**: Each outer array element can be a separate spatial extent describing the bounding boxes of the assets represented by this Collection using either 2D or 3D geometries. The first bounding box always describes the overall spatial extent of the data. All subsequent bounding boxes can be used to provide a more precise description of the extent and identify clusters of data. Clients only interested in the overall spatial extent will only need to access the first item in each array. It is recommended to only use multiple bounding boxes if a union of them would then include a large uncovered area (e.g. the union of Germany and Chile). The length of the inner 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 depth/height in meters and the elevation of the northeasterly most extent is the maximum. The coordinate reference system of the values is WGS 84 longitude/latitude. Example that covers the whole Earth: `[[-180.0, -90.0, 180.0, 90.0]]`. Example that covers the whole earth with a depth of 100 meters to a height of 150 meters: `[[-180.0, -90.0, -100.0, 180.0, 90.0, 150.0]]`. #### Temporal Extent Object The object describes the temporal extents of the Collection. | Element | Type | Description | | -------- | ------------------ | --------------------------------------------------------------------- | | interval | \[\[string\|null]] | **REQUIRED.** Potential *temporal extents* covered by the Collection. | **interval**: Each outer array element can be a separate temporal extent. The first time interval always describes the overall temporal extent of the data. All subsequent time intervals can be used to provide a more precise description of the extent and identify clusters of data. Clients only interested in the overall extent will only need to access the first item in each array. It is recommended to only use multiple temporal extents if a union of them would then include a large uncovered time span (e.g. only having data for the years 2000, 2010 and 2020). Each inner array consists of exactly two elements, either a timestamp or `null`. Timestamps consist of a date and time in UTC and MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). The temporal reference system is the Gregorian calendar. Open date ranges are supported by setting the start and/or the end time to `null`. Example for data from the beginning of 2019 until now: `[["2019-01-01T00:00:00Z", null]]`. It is recommended to provide at least a rough guideline on the temporal extent and thus it's not recommended to set both start and end time to `null`. Nevertheless, this is possible if there's a strong use case for an open date range to both sides. ### Provider Object The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the Collection and therefore influences the data offered by this Collection. May also include information about the final storage provider hosting the data. | Field Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------ | | name | string | **REQUIRED.** The name of the organization or the individual. | | description | string | 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. | | roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | | url | string | Homepage on which the provider describes the dataset and publishes contact information. | **roles**: 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. ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal with links. | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. | | type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. #### Relation types STAC Collections use a variety of `rel` types in the link object, to describe the exact nature of the link between this Collection and the entity it is linking to. It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. The following table explains places where custom STAC `rel` types are used for ollections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. | Type | Description | | ------- | ------------------------------------------------------------ | | self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | | parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | | child | URL to a child STAC entity (Catalog or Collection). | | item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | | license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. **Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). ### Asset Object An Asset is an object that contains a URI to data associated with the Collection that can be downloaded or streamed. The definition provided here, at the Collection level, is the same as the [Asset Object in Items](../item-spec/item-spec.md#asset-object). It is allowed to add additional fields. | Field Name | Type | Description | | ----------- | --------- | ----------- | | href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. | | title | string | The displayed title for clients and users. | | description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | type | string | [Media type](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | | roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | ### Range Object For summaries that would normally consist of a lot of continuous values, statistics can be added instead. By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) 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`. | Field Name | Type | Description | | ---------- | -------------- | ----------- | | minimum | number\|string | **REQUIRED.** Minimum value. | | maximum | number\|string | **REQUIRED.** Maximum value. | ### JSON Schema Object For a full understanding of the summarized field, a JSON Schema can be added for each summarized field. This allows very fine-grained information for each field and each value as JSON Schema is also extensible. Each schema must be valid against all corresponding values available for the property in the sub-Items. It is recommended to use [JSON Schema draft-07](https://json-schema.org/specification-links.html#draft-7) to align with the JSON Schemas provided by STAC. Empty schemas are not allowed. For an introduction to JSON Schema, see "[Learn JSON Schema](https://json-schema.org/learn/)". ## Media Type for STAC Collections A STAC Collection is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the [`application/json`](https://tools.ietf.org/html/rfc8259#section-11) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) (previously known as the MIME Type). ## Standalone Collections STAC Collections which don't link to any Item are called **standalone Collections**. To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by extensions for Items in the `summaries` field. This makes much sense for fields such as `platform` or `proj:epsg`, which are often the same for a whole Collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. The data provider is free to decide, which fields are reasonable to be used. ================================================ FILE: stac-spec/collection-spec/json-schema/collection.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json#", "title": "STAC Collection Specification", "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", "allOf": [ { "$ref": "#/definitions/collection" } ], "definitions": { "collection": { "title": "STAC Collection", "description": "These are the fields specific to a STAC Collection. All other fields are inherited from STAC Catalog.", "type": "object", "required": [ "stac_version", "type", "id", "description", "license", "extent", "links" ], "properties": { "stac_version": { "title": "STAC version", "type": "string", "const": "1.0.0" }, "stac_extensions": { "title": "STAC extensions", "type": "array", "uniqueItems": true, "items": { "title": "Reference to a JSON Schema", "type": "string", "format": "iri" } }, "type": { "title": "Type of STAC entity", "const": "Collection" }, "id": { "title": "Identifier", "type": "string", "minLength": 1 }, "title": { "title": "Title", "type": "string" }, "description": { "title": "Description", "type": "string", "minLength": 1 }, "keywords": { "title": "Keywords", "type": "array", "items": { "type": "string" } }, "license": { "title": "Collection License Name", "type": "string", "pattern": "^[\\w\\-\\.\\+]+$" }, "providers": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "title": "Organization name", "type": "string" }, "description": { "title": "Organization description", "type": "string" }, "roles": { "title": "Organization roles", "type": "array", "items": { "type": "string", "enum": [ "producer", "licensor", "processor", "host" ] } }, "url": { "title": "Organization homepage", "type": "string", "format": "iri" } } } }, "extent": { "title": "Extents", "type": "object", "required": [ "spatial", "temporal" ], "properties": { "spatial": { "title": "Spatial extent object", "type": "object", "required": [ "bbox" ], "properties": { "bbox": { "title": "Spatial extents", "type": "array", "minItems": 1, "items": { "title": "Spatial extent", "type": "array", "oneOf": [ { "minItems":4, "maxItems":4 }, { "minItems":6, "maxItems":6 } ], "items": { "type": "number" } } } } }, "temporal": { "title": "Temporal extent object", "type": "object", "required": [ "interval" ], "properties": { "interval": { "title": "Temporal extents", "type": "array", "minItems": 1, "items": { "title": "Temporal extent", "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": [ "string", "null" ], "format": "date-time", "pattern": "(\\+00:00|Z)$" } } } } } } }, "assets": { "$ref": "../../item-spec/json-schema/item.json#/definitions/assets" }, "links": { "title": "Links", "type": "array", "items": { "$ref": "#/definitions/link" } }, "summaries": { "$ref": "#/definitions/summaries" } } }, "link": { "type": "object", "required": [ "rel", "href" ], "properties": { "href": { "title": "Link reference", "type": "string", "format": "iri-reference", "minLength": 1 }, "rel": { "title": "Link relation type", "type": "string", "minLength": 1 }, "type": { "title": "Link type", "type": "string" }, "title": { "title": "Link title", "type": "string" } } }, "summaries": { "type": "object", "additionalProperties": { "anyOf": [ { "title": "JSON Schema", "type": "object", "minProperties": 1, "allOf": [ { "$ref": "http://json-schema.org/draft-07/schema" } ] }, { "title": "Range", "type": "object", "required": [ "minimum", "maximum" ], "properties": { "minimum": { "title": "Minimum value", "type": [ "number", "string" ] }, "maximum": { "title": "Maximum value", "type": [ "number", "string" ] } } }, { "title": "Set of values", "type": "array", "minItems": 1, "items": { "description": "For each field only the original data type of the property can occur (except for arrays), but we can't validate that in JSON Schema yet. See the sumamry description in the STAC specification for details." } } ] } } } } ================================================ FILE: stac-spec/examples/README.md ================================================ # STAC Examples This directory contains various examples for all parts of the STAC specification. It is structured to be two valid STACs, meaning both [catalog.json](catalog.json) and [collection.json](collection.json) should successfully load in various tools. They do not follow *all* the [best practices](../best-practices.md) for STAC, mostly due to the fact that they contrive examples to show the spec and we are hosting in GitHub. But we note below where they differ from an ideal catalog. The various fields are mostly fictional, to be able to demonstrate the various aspects of the spec as tersely as possible. To get a sense of real world STAC implementations we recommend exploring the [stac-examples](http://github.com/stac-utils/stac-examples) repo, which gathers in one place copies of STAC [Items](../item-spec/item-spec.md) and [Collection](../collection-spec/collection-spec.md) from a number of different production catalogs that all follow good STAC practices. And you should also explore the various catalogs listed on [STAC Index](http://stacindex.org), to see full catalogs in production. ## Organization This directory contains two STAC implementations, both valid, but simplified a bit to be illustrative of the key concepts, so they do not quite follow all the best practices. ### Simple Collection This STAC implementation consists of three files, all contained at the root of the examples directory **[collection.json](collection.json)** is a minimal 'simple collection', that links to three items. **[simple-item.json](simple-item.json)** is the most minimal possible compliant Item record. Most all data will include additional fields, as STAC is designed to be a minimal common subset. But it is useful for showing exactly what is required. **[core-item.json](core-item.json)** is a more realistic example, for a hypothetical analytic image acquisition from a satellite company called 'Remote Data'. It includes additional fields covering the [common metadata](../item-spec/common-metadata.md). It also links to a variety of assets that is typical for satellite imagery, as most providers include a number of complementary files. **[extended-item.json](extended-item.json)** is arguably an even more realistic example, as it includes a number of the [extensions](../extensions/) that are commonly used, to demonstrate how implementations tend to start with the core, and add in a number of the core extensions. **[collectionless-item.json](collectionless-item.json)** demonstrates the common metadata that is only used when an Item does not have a collection. It is recommended to organize items in collections, but we wanted to show how this works. This is not technically in the 'simple collection' of this section, but it follows the same pattern, so is included here. ### Nested Catalog This STAC implementation shows a common pattern, starting with a catalog that links to a number of distinct collections, which may link down to a number of items. **[catalog.json](catalog.json)** is a minimal catalog implementation, linking to two other collections. **[collection-only/collection.json](collection-only/collection.json)** is a collection that does not link to any items. This demonstrates how is is possible to make use of STAC Collections without needing items, to serve as nice summarizing metadata for tools that work with full layers / collections. This example collection is based on real Sentinel-2 values, so is not quite fictional, but should be taken as just an example. **[extensions-collection/collection.json](extensions-collection/collection.json)** contains a small number of items, that demonstrate more functionality available in STAC [extensions](../extensions/). These are linked to directly from the individual extensions. These items follow the recommendations for [Catalog Layout Best Practices](../best-practices.md#catalog-layout). ## In Depth As mentioned above, the files in this examples directory form valid STAC implementations. They are all based on a fictional remote sensing company called 'Remote Data', with a URL at remotedata.io. This domain has not been set up, so those links will not work, but any valid data provider should provide valid links to their homepage. The examples use the `rd:` prefix to show how providers can use custom fields when there are not set fields. In the examples these do not link to a schema which is completely valid, but it is recommended that providers do write a JSON schema that can validate their custom fields (we will work to add an example schema for the `rd:` fields in the future). ### Catalog Type One of the most important STAC Best Practices is to [use links consistently](../best-practices.md#use-of-links), following one of the described 'catalog types'. The catalogs described here are [Relative Published Catalogs](../best-practices.md#relative-published-catalog), that use absolute URL's to refer to their assets (so would be an example of a [Self-contained Metadata Only](../best-practices.md#self-contained-metadata-only) catalog that is published). ### Differences with STAC Best Practices One of the most important documents in this repository is the one about [best practices](../best-practices.md). It describes a number of practical recommendations gained by people actually implementing STAC. The core spec is designed to be as flexible as possible, so that it is not too rigid and unable to handle unanticipated needs. But we recommend following as many of the best practices as is feasible, as it will help ensure various STAC tools work much better. The examples in this folder don't align with all the best practices, mostly because they are meant to demonstrate things as tersely as possible, and also because they live directly inside a github repository. As many people will look at these examples and take them as 'how things should be' we felt its important to highlight where things here differ from the actual best practices. #### Catalog Layout Another important recommendations concerns the [layout of STAC catalogs](../best-practices.md#catalog-layout). This is important for tools to be able to expect a certain layout, and most tools will follow the described layout. The simple collection that consists of the collection.json and its 3 linked items violates this. This is done to be able to show item examples directly in the root of the 'examples' folder, so people don't have to dig deep into folders to get a quick example. But a proper catalog layout would put the items in sub-directories, along with their assets. ================================================ FILE: stac-spec/examples/catalog.json ================================================ { "id": "examples", "type": "Catalog", "title": "Example Catalog", "stac_version": "1.0.0", "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.", "links": [ { "rel": "root", "href": "./catalog.json", "type": "application/json" }, { "rel": "child", "href": "./extensions-collection/collection.json", "type": "application/json", "title": "Collection Demonstrating STAC Extensions" }, { "rel": "child", "href": "./collection-only/collection.json", "type": "application/json", "title": "Collection with no items (standalone)" }, { "rel": "child", "href": "./collection-only/collection-with-schemas.json", "type": "application/json", "title": "Collection with no items (standalone with JSON Schemas)" }, { "rel": "item", "href": "./collectionless-item.json", "type": "application/json", "title": "Collection with no items (standalone)" }, { "rel": "self", "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/catalog.json", "type": "application/json" } ] } ================================================ FILE: stac-spec/examples/collection-only/collection-with-schemas.json ================================================ { "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/sat/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "id": "sentinel-2", "type": "Collection", "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-2A", "description": "The SENTINEL-2 mission is a land monitoring constellation of two satellites each equipped with a MSI (Multispectral Imager) instrument covering 13 spectral bands providing high resolution optical imagery (i.e., 10m, 20m, 60 m) every 10 days with one satellite and 5 days with two satellites", "license": "proprietary", "extent": { "spatial": { "bbox": [ [ -180, -82.852377834669, 180, 82.819463367711 ] ] }, "temporal": { "interval": [ [ "2017-04-12T02:57:21.459000Z", "2021-04-22T11:30:12.767000Z" ] ] } }, "links": [ { "rel": "parent", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "root", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "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" } ], "providers": [ { "name": "European Union/ESA/Copernicus", "roles": [ "producer", "licensor" ], "url": "https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi" }, { "name": "AWS", "roles": [ "host" ], "url": "https://registry.opendata.aws/sentinel-2/" }, { "name": "jeobrowser", "roles": [ "processor" ], "url": "https://github.com/jjrom/resto" } ], "summaries": { "datetime": { "minimum": "2017-04-12T02:57:21Z", "maximum": "2021-04-22T11:30:12Z" }, "instruments": { "type": "string", "const": "msi", "title": "Multispectral Intrument", "count": 6613431 }, "resto:landcover": { "type": "string", "oneOf": [ { "const": "cultivated", "title": "Cultivated", "count": 490750 }, { "const": "desert", "title": "Desert", "count": 543120 }, { "const": "flooded", "title": "Flooded", "count": 5187 }, { "const": "forest", "title": "Forest", "count": 767807 }, { "const": "herbaceous", "title": "Herbaceous", "count": 674281 }, { "const": "ice", "title": "Ice", "count": 231285 }, { "const": "urban", "title": "Urban", "count": 1219 }, { "const": "water", "title": "Water", "count": 2303314 } ] }, "resto:location": { "type": "string", "oneOf": [ { "const": "tropical", "title": "Tropical", "count": 1807474 }, { "const": "southern", "title": "Southern", "count": 1671685 }, { "const": "northern", "title": "Northern", "count": 4876669 }, { "const": "equatorial", "title": "Equatorial", "count": 27302 }, { "const": "coastal", "title": "Coastal", "count": 1495516 } ] }, "platform": { "type": "string", "oneOf": [ { "const": "sentinel-2b", "title": "Sentinel 2B", "count": 3495597 }, { "const": "sentinel-2a", "title": "Sentinel 2A", "count": 3117831 } ] }, "resto:season": { "type": "integer", "oneOf": [ { "const": 0, "title": "Winter", "count": 1621108 }, { "const": 2, "title": "Summer", "count": 2279472 }, { "const": 1, "title": "Spring", "count": 1577067 }, { "const": 3, "title": "Autumn", "count": 1098015 } ] }, "eo:bands": [ { "title": "B1", "common_name": "coastal", "center_wavelength": 4.439, "gsd": 60 }, { "title": "B2", "common_name": "blue", "center_wavelength": 4.966, "gsd": 10 }, { "title": "B3", "common_name": "green", "center_wavelength": 5.6, "gsd": 10 }, { "title": "B4", "common_name": "red", "center_wavelength": 6.645, "gsd": 10 }, { "title": "B5", "center_wavelength": 7.039, "gsd": 20 }, { "title": "B6", "center_wavelength": 7.402, "gsd": 20 }, { "title": "B7", "center_wavelength": 7.825, "gsd": 20 }, { "title": "B8", "common_name": "nir", "center_wavelength": 8.351, "gsd": 10 }, { "title": "B8A", "center_wavelength": 8.648, "gsd": 20 }, { "title": "B9", "center_wavelength": 9.45, "gsd": 60 }, { "title": "B10", "center_wavelength": 1.3735, "gsd": 60 }, { "title": "B11", "common_name": "swir16", "center_wavelength": 1.6137, "gsd": 20 }, { "title": "B12", "common_name": "swir22", "center_wavelength": 2.2024, "gsd": 20 } ] } } ================================================ FILE: stac-spec/examples/collection-only/collection.json ================================================ { "type": "Collection", "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "id": "sentinel-2", "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-1C", "description": "Sentinel-2 is a wide-swath, high-resolution, multi-spectral\nimaging mission supporting Copernicus Land Monitoring studies,\nincluding the monitoring of vegetation, soil and water cover,\nas well as observation of inland waterways and coastal areas.\n\nThe Sentinel-2 data contain 13 UINT16 spectral bands representing\nTOA reflectance scaled by 10000. See the [Sentinel-2 User Handbook](https://sentinel.esa.int/documents/247904/685211/Sentinel-2_User_Handbook)\nfor details. In addition, three QA bands are present where one\n(QA60) is a bitmask band with cloud mask information. For more\ndetails, [see the full explanation of how cloud masks are computed.](https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-2-msi/level-1c/cloud-masks)\n\nEach Sentinel-2 product (zip archive) may contain multiple\ngranules. Each granule becomes a separate Earth Engine asset.\nEE asset ids for Sentinel-2 assets have the following format:\nCOPERNICUS/S2/20151128T002653_20151128T102149_T56MNN. Here the\nfirst numeric part represents the sensing date and time, the\nsecond numeric part represents the product generation date and\ntime, and the final 6-character string is a unique granule identifier\nindicating its UTM grid reference (see [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System)).\n\nFor more details on Sentinel-2 radiometric resoltuon, [see this page](https://earth.esa.int/web/sentinel/user-guides/sentinel-2-msi/resolutions/radiometric).\n", "license": "proprietary", "keywords": [ "copernicus", "esa", "eu", "msi", "radiance", "sentinel" ], "providers": [ { "name": "European Union/ESA/Copernicus", "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", null ] ] } }, "assets": { "metadata_iso_19139": { "roles": [ "metadata", "iso-19139" ], "href": "https://storage.googleapis.com/open-cogs/stac-examples/sentinel-2-iso-19139.xml", "title": "ISO 19139 metadata", "type": "application/vnd.iso.19139+xml" } }, "summaries": { "datetime": { "minimum": "2015-06-23T00:00:00Z", "maximum": "2019-07-10T13:44:56Z" }, "platform": [ "sentinel-2a", "sentinel-2b" ], "constellation": [ "sentinel-2" ], "instruments": [ "msi" ], "view:off_nadir": { "minimum": 0, "maximum": 100 }, "view:sun_elevation": { "minimum": 6.78, "maximum": 89.9 }, "gsd": [ 10, 30, 60 ], "proj:epsg": [ 32601, 32602, 32603, 32604, 32605, 32606, 32607, 32608, 32609, 32610, 32611, 32612, 32613, 32614, 32615, 32616, 32617, 32618, 32619, 32620, 32621, 32622, 32623, 32624, 32625, 32626, 32627, 32628, 32629, 32630, 32631, 32632, 32633, 32634, 32635, 32636, 32637, 32638, 32639, 32640, 32641, 32642, 32643, 32644, 32645, 32646, 32647, 32648, 32649, 32650, 32651, 32652, 32653, 32654, 32655, 32656, 32657, 32658, 32659, 32660 ], "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": "parent", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "root", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "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" } ] } ================================================ FILE: stac-spec/examples/collection.json ================================================ { "id": "simple-collection", "type": "Collection", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "stac_version": "1.0.0", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", "providers": [ { "name": "Remote Data, Inc", "description": "Producers of awesome spatiotemporal assets", "roles": [ "producer", "processor" ], "url": "http://remotedata.io" } ], "extent": { "spatial": { "bbox": [ [ 172.91173669923782, 1.3438851951615003, 172.95469614953714, 1.3690476620161975 ] ] }, "temporal": { "interval": [ [ "2020-12-11T22:38:32.125Z", "2020-12-14T18:02:31.437Z" ] ] } }, "license": "CC-BY-4.0", "summaries": { "platform": [ "cool_sat1", "cool_sat2" ], "constellation": [ "ion" ], "instruments": [ "cool_sensor_v1", "cool_sensor_v2" ], "gsd": { "minimum": 0.512, "maximum": 0.66 }, "eo:cloud_cover": { "minimum": 1.2, "maximum": 1.2 }, "proj:epsg": { "minimum": 32659, "maximum": 32659 }, "view:sun_elevation": { "minimum": 54.9, "maximum": 54.9 }, "view:off_nadir": { "minimum": 3.8, "maximum": 3.8 }, "view:sun_azimuth": { "minimum": 135.7, "maximum": 135.7 } }, "links": [ { "rel": "root", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "item", "href": "./simple-item.json", "type": "application/geo+json", "title": "Simple Item" }, { "rel": "item", "href": "./core-item.json", "type": "application/geo+json", "title": "Core Item" }, { "rel": "item", "href": "./extended-item.json", "type": "application/geo+json", "title": "Extended Item" }, { "rel": "self", "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/collection.json", "type": "application/json" } ] } ================================================ FILE: stac-spec/examples/collectionless-item.json ================================================ { "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" ], "type": "Feature", "id": "CS3-20160503_132131_08", "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": { "title": "Full Item", "description": "A sample STAC Item demonstrates an Item that does not have a collection, which is not recommended, but allowed by the spec.", "datetime": null, "start_datetime": "2016-05-03T13:22:30Z", "end_datetime": "2016-05-03T13:27:30Z", "created": "2016-05-04T00:00:01Z", "updated": "2017-01-01T00:30:55Z", "license": "various", "providers": [ { "name": "Remote Data, Inc", "description": "Producers of awesome spatiotemporal assets", "roles": [ "producer", "processor" ], "url": "http://remotedata.it" } ], "platform": "cool_sat2", "instruments": [ "cool_sensor_v1" ], "view:sun_elevation": 33.4, "gsd": 0.512, "cs:type": "scene", "cs:anomalous_pixels": 0.14, "cs:earth_sun_distance": 1.014156, "cs:sat_id": "CS3", "cs:product_level": "LV1B" }, "links": [ { "rel": "root", "href": "./catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "parent", "href": "./catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "alternate", "type": "text/html", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html", "title": "HTML representation of this STAC Item" }, { "rel": "license", "type": "text/html", "href": "http://remotedata.io/license.html", "title": "Data License for Remote Data, Inc." } ], "assets": { "analytic": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/analytic.tif", "title": "4-Band Analytic", "eo:bands": [ { "name": "band1" }, { "name": "band1" }, { "name": "band2" }, { "name": "band3" } ] }, "thumbnail": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", "title": "Thumbnail", "type": "image/png", "roles": [ "thumbnail" ] }, "udm": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/UDM.tif", "title": "Unusable Data Mask" }, "json-metadata": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/extended-metadata.json", "title": "Extended Metadata", "type": "application/json", "roles": [ "metadata" ] }, "ephemeris": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/S3-20160503_132130_04.EPH", "title": "Satellite Ephemeris Metadata" } } } ================================================ FILE: stac-spec/examples/core-item.json ================================================ { "stac_version": "1.0.0", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", "bbox": [ 172.91173669923782, 1.3438851951615003, 172.95469614953714, 1.3690476620161975 ], "geometry": { "type": "Polygon", "coordinates": [ [ [ 172.91173669923782, 1.3438851951615003 ], [ 172.95469614953714, 1.3438851951615003 ], [ 172.95469614953714, 1.3690476620161975 ], [ 172.91173669923782, 1.3690476620161975 ], [ 172.91173669923782, 1.3438851951615003 ] ] ] }, "properties": { "title": "Core Item", "description": "A sample STAC Item that includes examples of all common metadata", "datetime": null, "start_datetime": "2020-12-11T22:38:32.125Z", "end_datetime": "2020-12-11T22:38:32.327Z", "created": "2020-12-12T01:48:13.725Z", "updated": "2020-12-12T01:48:13.725Z", "platform": "cool_sat1", "instruments": [ "cool_sensor_v1" ], "constellation": "ion", "mission": "collection 5624", "gsd": 0.512 }, "collection": "simple-collection", "links": [ { "rel": "collection", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "root", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "parent", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "alternate", "type": "text/html", "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html", "title": "HTML version of this STAC Item" } ], "assets": { "analytic": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "4-Band Analytic", "roles": [ "data" ] }, "thumbnail": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg", "title": "Thumbnail", "type": "image/png", "roles": [ "thumbnail" ] }, "visual": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "3-Band Visual", "roles": [ "visual" ] }, "udm": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif", "title": "Unusable Data Mask", "type": "image/tiff; application=geotiff;" }, "json-metadata": { "href": "http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json", "title": "Extended Metadata", "type": "application/json", "roles": [ "metadata" ] }, "ephemeris": { "href": "http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH", "title": "Satellite Ephemeris Metadata" } } } ================================================ FILE: stac-spec/examples/extended-item.json ================================================ { "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json" ], "type": "Feature", "id": "20201211_223832_CS2", "bbox": [ 172.91173669923782, 1.3438851951615003, 172.95469614953714, 1.3690476620161975 ], "geometry": { "type": "Polygon", "coordinates": [ [ [ 172.91173669923782, 1.3438851951615003 ], [ 172.95469614953714, 1.3438851951615003 ], [ 172.95469614953714, 1.3690476620161975 ], [ 172.91173669923782, 1.3690476620161975 ], [ 172.91173669923782, 1.3438851951615003 ] ] ] }, "properties": { "title": "Extended Item", "description": "A sample STAC Item that includes a variety of examples from the stable extensions", "datetime": "2020-12-14T18:02:31.437000Z", "created": "2020-12-15T01:48:13.725Z", "updated": "2020-12-15T01:48:13.725Z", "platform": "cool_sat2", "instruments": [ "cool_sensor_v2" ], "gsd": 0.66, "eo:cloud_cover": 1.2, "proj:epsg": 32659, "proj:shape": [ 5558, 9559 ], "proj:transform": [ 0.5, 0, 712710, 0, -0.5, 151406, 0, 0, 1 ], "view:sun_elevation": 54.9, "view:off_nadir": 3.8, "view:sun_azimuth": 135.7, "rd:type": "scene", "rd:anomalous_pixels": 0.14, "rd:earth_sun_distance": 1.014156, "rd:sat_id": "cool_sat2", "rd:product_level": "LV3A", "sci:doi": "10.5061/dryad.s2v81.2/27.2" }, "collection": "simple-collection", "links": [ { "rel": "collection", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "root", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "parent", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "alternate", "type": "text/html", "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html", "title": "HTML version of this STAC Item" } ], "assets": { "analytic": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "4-Band Analytic", "roles": [ "data" ], "eo:bands": [ { "name": "band1", "common_name": "blue", "center_wavelength": 470, "full_width_half_max": 70 }, { "name": "band2", "common_name": "green", "center_wavelength": 560, "full_width_half_max": 80 }, { "name": "band3", "common_name": "red", "center_wavelength": 645, "full_width_half_max": 90 }, { "name": "band4", "common_name": "nir", "center_wavelength": 800, "full_width_half_max": 152 } ] }, "thumbnail": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg", "title": "Thumbnail", "type": "image/png", "roles": [ "thumbnail" ] }, "visual": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "3-Band Visual", "roles": [ "visual" ], "eo:bands": [ { "name": "band3", "common_name": "red", "center_wavelength": 645, "full_width_half_max": 90 }, { "name": "band2", "common_name": "green", "center_wavelength": 560, "full_width_half_max": 80 }, { "name": "band1", "common_name": "blue", "center_wavelength": 470, "full_width_half_max": 70 } ] }, "udm": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif", "title": "Unusable Data Mask", "type": "image/tiff; application=geotiff;" }, "json-metadata": { "href": "http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json", "title": "Extended Metadata", "type": "application/json", "roles": [ "metadata" ] }, "ephemeris": { "href": "http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH", "title": "Satellite Ephemeris Metadata" } } } ================================================ FILE: stac-spec/examples/extensions-collection/collection.json ================================================ { "id": "extensions-collection", "type": "Collection", "stac_version": "1.0.0", "description": "A heterogenous collection containing deeper examples of various extensions", "links": [ { "rel": "parent", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "root", "href": "../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "item", "href": "./proj-example/proj-example.json", "title": "Proj extension example" }, { "rel": "license", "href": "https://remotedata.io/license.html", "title": "Remote Data License Terms" } ], "stac_extensions": [], "title": "Collection of Extension Items", "keywords": [ "examples", "sar", "projection" ], "providers": [ { "name": "Remote Data, Inc.", "roles": [ "producer", "licensor" ], "url": "https://remotedata.io" } ], "extent": { "spatial": { "bbox": [ [ -180, -56, 180, 83 ] ] }, "temporal": { "interval": [ [ "2009-05-20T02:40:01.042784Z", "2018-11-03T23:59:55.112875Z" ] ] } }, "license": "PDDL-1.0" } ================================================ FILE: stac-spec/examples/extensions-collection/proj-example/proj-example.json ================================================ { "type": "Feature", "stac_version": "1.0.0", "id": "proj-example", "properties": { "datetime": "2018-10-01T01:08:32.033000Z", "proj:epsg": 32614, "proj:wkt2": "PROJCS[\"WGS 84 / UTM zone 14N\",GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.01745329251994328,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]],UNIT[\"metre\",1,AUTHORITY[\"EPSG\",\"9001\"]],PROJECTION[\"Transverse_Mercator\"],PARAMETER[\"latitude_of_origin\",0],PARAMETER[\"central_meridian\",-99],PARAMETER[\"scale_factor\",0.9996],PARAMETER[\"false_easting\",500000],PARAMETER[\"false_northing\",0],AUTHORITY[\"EPSG\",\"32614\"],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH]]", "proj:projjson": { "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json", "type": "ProjectedCRS", "name": "WGS 84 / UTM zone 14N", "base_crs": { "name": "WGS 84", "datum": { "type": "GeodeticReferenceFrame", "name": "World Geodetic System 1984", "ellipsoid": { "name": "WGS 84", "semi_major_axis": 6378137, "inverse_flattening": 298.257223563 } }, "coordinate_system": { "subtype": "ellipsoidal", "axis": [ { "name": "Geodetic latitude", "abbreviation": "Lat", "direction": "north", "unit": "degree" }, { "name": "Geodetic longitude", "abbreviation": "Lon", "direction": "east", "unit": "degree" } ] }, "id": { "authority": "EPSG", "code": 4326 } }, "conversion": { "name": "UTM zone 14N", "method": { "name": "Transverse Mercator", "id": { "authority": "EPSG", "code": 9807 } }, "parameters": [ { "name": "Latitude of natural origin", "value": 0, "unit": "degree", "id": { "authority": "EPSG", "code": 8801 } }, { "name": "Longitude of natural origin", "value": -99, "unit": "degree", "id": { "authority": "EPSG", "code": 8802 } }, { "name": "Scale factor at natural origin", "value": 0.9996, "unit": "unity", "id": { "authority": "EPSG", "code": 8805 } }, { "name": "False easting", "value": 500000, "unit": "metre", "id": { "authority": "EPSG", "code": 8806 } }, { "name": "False northing", "value": 0, "unit": "metre", "id": { "authority": "EPSG", "code": 8807 } } ] }, "coordinate_system": { "subtype": "Cartesian", "axis": [ { "name": "Easting", "abbreviation": "E", "direction": "east", "unit": "metre" }, { "name": "Northing", "abbreviation": "N", "direction": "north", "unit": "metre" } ] }, "area": "World - N hemisphere - 102°W to 96°W - by country", "bbox": { "south_latitude": 0, "west_longitude": -102, "north_latitude": 84, "east_longitude": -96 }, "id": { "authority": "EPSG", "code": 32614 } }, "proj:geometry": { "coordinates": [ [ [ 169200, 3712800 ], [ 403200, 3712800 ], [ 403200, 3951000 ], [ 169200, 3951000 ], [ 169200, 3712800 ] ] ], "type": "Polygon" }, "proj:bbox": [ 169200, 3712800, 403200, 3951000 ], "proj:centroid": { "lat": 34.595302781575604, "lon": -101.34448382627504 }, "proj:shape": [ 8391, 8311 ], "proj:transform": [ 30, 0, 224985, 0, -30, 6790215, 0, 0, 1 ] }, "geometry": { "type": "Polygon", "coordinates": [ [ [ 152.52758, 60.63437 ], [ 149.1755, 61.19016 ], [ 148.13933, 59.51584 ], [ 151.33786, 58.97792 ], [ 152.52758, 60.63437 ] ] ] }, "links": [ { "rel": "root", "href": "../../catalog.json", "type": "application/json", "title": "Example Catalog" }, { "rel": "parent", "href": "../collection.json", "type": "application/json", "title": "Collection of Extension Items" }, { "rel": "collection", "href": "../collection.json", "type": "application/json", "title": "Collection of Extension Items" } ], "assets": { "B1": { "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B1.TIF", "type": "image/tiff; application=geotiff", "title": "Band 1 (coastal)", "eo:bands": [ { "name": "B1", "common_name": "coastal", "center_wavelength": 0.44, "full_width_half_max": 0.02 } ] }, "B8": { "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B8.TIF", "type": "image/tiff; application=geotiff", "title": "Band 8 (panchromatic)", "eo:bands": [ { "name": "B8", "center_wavelength": 0.59, "full_width_half_max": 0.18 } ], "proj:shape": [ 16781, 16621 ], "proj:transform": [ 15, 0, 224992.5, 0, -15, 6790207.5, 0, 0, 1 ] } }, "bbox": [ 148.13933, 59.51584, 152.52758, 60.63437 ], "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json" ], "collection": "landsat-8-l1" } ================================================ FILE: stac-spec/examples/simple-item.json ================================================ { "stac_version": "1.0.0", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", "bbox": [ 172.91173669923782, 1.3438851951615003, 172.95469614953714, 1.3690476620161975 ], "geometry": { "type": "Polygon", "coordinates": [ [ [ 172.91173669923782, 1.3438851951615003 ], [ 172.95469614953714, 1.3438851951615003 ], [ 172.95469614953714, 1.3690476620161975 ], [ 172.91173669923782, 1.3690476620161975 ], [ 172.91173669923782, 1.3438851951615003 ] ] ] }, "properties": { "datetime": "2020-12-11T22:38:32.125000Z" }, "collection": "simple-collection", "links": [ { "rel": "collection", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "root", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" }, { "rel": "parent", "href": "./collection.json", "type": "application/json", "title": "Simple Example Collection" } ], "assets": { "visual": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "3-Band Visual", "roles": [ "visual" ] }, "thumbnail": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg", "title": "Thumbnail", "type": "image/jpeg", "roles": [ "thumbnail" ] } } } ================================================ FILE: stac-spec/extensions/README.md ================================================ # Extensions - [Overview](#overview) - [Using Extensions](#using-extensions) - [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions) - [Stable STAC Extensions](#stable-stac-extensions) - [Community Extensions](#community-extensions) - [Proposed extensions](#proposed-extensions) - [Extending STAC](#extending-stac) - [General Conventions](#general-conventions) - [Proposing new extensions](#proposing-new-extensions) - [Extension Maturity](#extension-maturity) - [Prefixes](#prefixes) - [Use of arrays and objects](#use-of-arrays-and-objects) ## Overview One of the most important aspects of the SpatioTemporal Asset Catalog specification is its extensibility. The core STAC specification defines only a minimal core, but is designed for extension. It is expected that most real-world implementations will use several 'extensions' to fully describe their data. This document describes how extensions work, and links to the 'core' extensions included in this repo, as well as to a variety of 'community' extensions. **For the complete list of available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).** Extensions to the core STAC specification provide additional JSON fields that can be used to better describe the data. Most tend to be about describing a particular domain or type of data, but some imply functionality. Extensions include a JSON Schema precisely describing the structure, a natural language description of the fields, and thorough examples. Anybody can create an extension for their data, and data providers often work together to share fields between them to create a shared community extensions. See the section below on '[Extending STAC](#extending-stac)') for information on how to get started. And everyone is encouraged to link to the extension in the table below, so others can be aware of it. Each extension has at least one *owner*. You can find extension owners in each extension's README. ## Using Extensions When deciding how to model data in STAC it is highly recommended to first look at the [list of extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This increases interoperability, as users know that the meaning of your fields is the same as in other STAC implementations. Many clients will also understand more mature extensions for better display and querying. To incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions` array of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions), [Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions) object. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators can fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as identifiers for specific version of the extension that the STAC object implements. The extension ID can be found listed as the 'identifier' in the second line of the README of any extension made with the [extension template](https://github.com/stac-extensions/template), and new ones get published automatically with any release made with the template. ### Extension IDs in `stac_extensions` The logic for when an object should list an extension ID in its `stac_extension` array is as follows: - If the object directly implements the extension (by following the specified requirements - usually by including fields, but occasionally implementing alternate behaviors), the `stac_extensions` of that object should contain the extension ID. - If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that Asset should contain the extension ID. - If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array. - If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the [item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`. ## Stable STAC Extensions These extensions are considered stable and are widely used in many production implementations. As additional extensions advance through the [Extension Maturity](#extension-maturity) classification they, will be added here. | Extension Title | Description | |-----------------------------------------------------------------------|--------------------------------| | [Electro-Optical](https://github.com/stac-extensions/eo/) | Covers electro-optical data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. | | [Projection](https://github.com/stac-extensions/projection/) | Provides a way to describe Items whose assets are in a geospatial projection. | | [Scientific Citation](https://github.com/stac-extensions/scientific/) | Metadata that indicate from which publication data originates and how the data itself should be cited or referenced. | | [View Geometry](https://github.com/stac-extensions/view/) | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data | ## Community Extensions There are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the [stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. For an overview of all extensions with their [Extension Maturity](#extension-maturity) classification see the [STAC extensions overview page](https://stac-extensions.github.io/). ### Proposed extensions Beyond the community extensions there have been a number of extensions that people have proposed to the STAC community. These can be found in the STAC [Issue Tracker](https://github.com/radiantearth/stac-spec/issues) under the [new extension](https://github.com/radiantearth/stac-spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+extension%22) label. These are ideas that others would likely use and potentially collaborate on. Anyone is free to add new ideas there, and see the section below on [proposing new extensions](#proposing-new-extensions) for the workflow to advance ideas into full-fledged community extensions. ## Extending STAC Anyone is welcome to create an extension. There are several types of extensions, some just add additional fields, some change the behavior of STAC and some introduce completely new functionality. New extensions should try to align with existing extensions as well as possible and may even re-use fields and their definitions until they may get split into a new extension that combines commonly used fields across multiple extensions. Best practices for extension proposals are still emerging in this section. ### General Conventions Creating a new extension usually involves defining a set of logically grouped fields, and specifying what the allowed values for those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one can theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects. 1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object, rather than directly in the Item object. 2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa. For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset. 3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or [Collection](../collection-spec/collection-spec.md) should be added to the root of the object. 4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema. ### Proposing new extensions Extensions can be hosted anywhere, but should use the [extension template](https://github.com/stac-extensions/stac-extensions.github.io#using-the-stac-extensions-template) as a starting point. If you'd like to add a repository to the [stac-extensions](https://github.com/stac-extensions) GitHub organization, just ask on [Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby)! This is fine for work-in-progress extensions. You can also host the extension repository in your own GitHub account, and optionally transfer it to the stac-extensions org later. For new extensions that require community discussion, we recommend the following workflow: - Use the stac-extensions template to sketch out your proposed extension - Open an issue on this repository with the prefix "New Extension: " and describe the extension. Include a link to the extension repository. - Discussion can occur on that issue, or discussion can move to issues/pull requests on the extension repository directly. - Once the extension has an initial release, the issue on stac-spec will be closed. ### Extension Maturity There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how much they can count on the extension. Extension creators are encouraged to list their extensions here, even if it is just an rough proposal, so others can potentially collaborate. | 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. The extension has a code owner, designated in its README. | | 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. | DO NOT USE, is not supported | 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. ### Prefixes A STAC Item can combine schema information from several different sources - the core STAC Item information, an earth observation community extension, and a vendor specific provider. It can be difficult to distinguish exactly where each definition came from, and to pull out the most relevant information, especially when vendors often will dump in all the metadata they have in to the STAC definition. So one idea is to have prefixes to differentiate specific vendors (like `dg:` for DigitalGlobe), and for communities of practice (like `eo:` for Electro-Optical). These wouldn't be full namespacing, though an extension for like JSON-LD could potentially evolve to make fully resolved namespacing an option. An example of this can be seen in a Landsat example: ```js "properties": { "datetime":"2018-01-01T13:21:30Z", "start_datetime":"2018-01-01T13:21:30Z", "end_datetime":"2018-01-01T13:31:30Z", "view:off_nadir": -0.001, "eo:cloud_cover": 10.31, "view:sun_azimuth": 149.01607154, "view:sun_elevation": 59.21424700, "gsd": 30, "l8:data_type": "L1T", "l8:wrs_path": 153, "l8:wrs_row": 25, "l8:earth_sun_distance": 1.0141560, "l8:ground_control_points_verify": 114, "l8:geometric_rmse_model": 7.562, "l8:image_quality_tirs": 9, "l8:ground_control_points_model": 313, "l8:geometric_rmse_model_x": 5.96, "l8:geometric_rmse_model_y": 4.654, "l8:geometric_rmse_verify": 5.364, "l8:image_quality_oli": 9 } ``` ### Use of arrays and objects For extensions, it is recommended to 1. Use arrays only as enumerations/lists (possibly sorted), without implying additional meaning (such as order) 2. To avoid using nested objects, in favor of multiple attributes with a similar naming scheme. For example, if one would like to define an extension to contain a start and a end date, there are multiple options (tl;dr: option **3** is recommended): 1. Define an object, for example: `"date_range": {"start": "2018-01-01", "end": "2018-01-31"}`. This is **discouraged** as it is more complex to search in objects. 2. Define an two-element array where the first element is the start date and the second element is the end date, for example `"date_range": ["2018-01-01", "2018-01-31"]`. This is **discouraged** as it would conflict with Collection `summaries`, which always considers arrays as true (potentially sorted) enumeration without any additional meaning. 3. Define two separate fields, e.g. `"date_range_start": "2018-01-01", "date_range_end": "2018-01-31"`. This is **recommended** as it avoids the conflicts above and is usually better displayed in software that only understands GeoJSON but has no clue about STAC. This is due to the fact that most legacy software can not display arrays or objects GeoJSON `properties` properly. This rules only applies to the fields defined directly for the Item's `properties`. For fields and structures defined on other levels (e.g. in the root of an Item or in an array), extension authors can freely define the structure. So an array of objects such as the `eo:bands` are fine to use, but keep in mind that the drawbacks mentioned above usually still apply. ================================================ FILE: stac-spec/item-spec/README.md ================================================ # STAC Item Specification The [STAC Item](item-spec.md) object is the most important object in a STAC system. An **Item** is the entity that contains metadata for a scene and links to the assets. Item objects are the leaf nodes for a graph of [Catalog](../catalog-spec/catalog-spec.md) and [Collection](../collection-spec/collection-spec.md) objects. See the [overview](../overview.md) document for more information about how these objects relate to each other. ## In this directory **Specification:** The STAC Item specification is in *[item-spec.md](item-spec.md)*. It includes an overview and an in-depth explanation of the fields. **Schemas:** The OpenAPI specification in *[item.json](json-schema/item.json)* defines an **Item** object. The [basics](json-schema/basics.json), [datetime](json-schema/datetime.json), [instrument](json-schema/instrument.json), [licensing](json-schema/licensing.json), and [provider](json-schema/provider.json) schemas validate additional fields defined in *[Common Metadata](common-metadata.md)*. **Common Metadata:** A set of commonly-used fields for STAC Items is listed in *[common-metadata.md](common-metadata.md)*. ================================================ FILE: stac-spec/item-spec/common-metadata.md ================================================ # STAC Common Metadata This document outlines commonly used fields in STAC. They are often used in [STAC Item properties](item-spec.md#properties-object), but can also be used in other places, e.g. an [Item Asset](item-spec.md#asset-object) or [Collection Asset](../collection-spec/collection-spec.md#asset-object). - [STAC Common Metadata](#stac-common-metadata) - [Basics](#basics) - [Date and Time](#date-and-time) - [Date and Time Range](#date-and-time-range) - [Licensing](#licensing) - [Relation types](#relation-types) - [Provider](#provider) - [Provider Object](#provider-object) - [Instrument](#instrument) Various *examples* are available in the folder [`examples`](../examples/). *JSON Schemas* can be found in the folder [`json-schema`](json-schema/). By default, these fields are only included and validated against in the core [Item schema](json-schema/item.json). Implementation of any of the fields is not required, unless explicitly required by a specification using the field. For example, `datetime` is required in STAC Items. ## Basics Descriptive fields to give a basic overview of a STAC Item. - [JSON Schema](json-schema/basics.json) | Field Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------ | | title | string | A human readable title describing the Item. | | description | string | Detailed multi-line description to fully explain the Item. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | ## Date and Time - [JSON Schema](json-schema/datetime.json) Fields to provide additional temporal information such as ranges with a start and an end datetime stamp. | Field Name | Type | Description | | ---------- | ------------ | ----------- | | datetime | string\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. | | created | string | Creation date and time of the corresponding data (see below), in UTC. | | updated | string | Date and time the corresponding data (see below) was updated last, in UTC. | All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). **created** and **updated** have different meaning depending on where they are used. If those fields are available in the Item `properties`, they identify the creation and update times of the metadata. Having those fields in the Item `assets` refers to the creation and update times of the actual data linked to in the Asset Object. *NOTE: There are more date and time related fields available in the [Timestamps extension](https://github.com/stac-extensions/timestamps), which is not an official extension*. ### Date and Time Range While a STAC Item can have a nominal datetime describing the capture, these properties allow an Item to have a range of capture dates and times. An example of this is the [MODIS 16 day vegetation index product](https://lpdaac.usgs.gov/products/mod13q1v006/). **Important:** Using one of the fields REQUIRES inclusion of the other field as well to enable a user to search STAC records by the provided times. So if you use `start_datetime` you need to add `end_datetime` and vice-versa. Both fields are also REQUIRED if the `datetime` field is set to `null`. The datetime property in a STAC Item and these fields are not mutually exclusive. | Field Name | Type | Description | | -------------- | ------ | ------------------------------------------------------------ | | start_datetime | string | The first or start date and time for the Item, in UTC. It is formatted as `date-time` according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | | end_datetime | string | The last or end date and time for the Item, in UTC. It is formatted as `date-time` according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | ## Licensing Information about the license(s) of the data, which is not necessarily the same license that applies to the metadata. **Licensing information should be defined at the [Collection](../collection-spec/collection-spec.md) level if possible.** - [JSON Schema](json-schema/licensing.json) | Field Name | Type | Description | | ---------- | ------ | ----------- | | license | string | Item's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. Should be defined at the Collection level if possible. | **license**: Data license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the [`license` link relation type](#relation-types). If no link to a license is included and the `license` field is set to `proprietary`, the Collection is private, and consumers have not been granted any explicit right to use the data. ### Relation types | Type | Description | | ------------ | ------------------------------------------------------------ | | license | The license URL(s) for the Item SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC Item with the license text in a separate file and link to this file. | ## Provider Information about the organizations capturing, producing, processing, hosting or publishing this data. **Provider information should be defined at the Collection level if possible.** - [JSON Schema](json-schema/provider.json) | Field Name | Type | Description | | ---------- | ------ | ----------- | | providers | [[Provider Object](#provider-object)] | 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. | ### Provider Object The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the assets and therefore influences the data offered by the STAC implementation. May also include information about the final storage provider hosting the data. | Field Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------ | | name | string | **REQUIRED.** The name of the organization or the individual. | | description | string | 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. | | roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | | url | string | Homepage on which the provider describes the dataset and publishes contact information. | #### roles 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 the last element of the provider list. ## Instrument Adds metadata specifying a platform and instrument used in a data collection mission. These fields will often be combined with domain-specific extensions that describe the actual data, such as the `eo` or `sar` extensions. - [JSON Schema](json-schema/instrument.json) | Field Name | Type | Description | | ------------- | --------- | ----------- | | platform | string | Unique name of the specific platform to which the instrument is attached. | | instruments | \[string] | Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | | constellation | string | Name of the constellation to which the platform belongs. | | mission | string | Name of the mission for which data is collected. | | gsd | number | Ground Sample Distance at the sensor, in meters (m), must be greater than 0. | ### Additional Field Information #### platform The unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include `landsat-8` (Landsat-8), `sentinel-2a` and `sentinel-2b` (Sentinel-2), `terra` and `aqua` (part of NASA EOS, carrying the MODIS instruments), `mycorp-uav-034` (hypothetical drone name), and `worldview02` (Maxar/DigitalGlobe WorldView-2). #### instruments An array of all the sensors used in the creation of the data. For example, data from the Landsat-8 platform is collected with the OLI sensor as well as the TIRS sensor, but the data is distributed together so would be specified as `['oli', 'tirs']`. Other instrument examples include `msi` (Sentinel-2), `aster` (Terra), and `modis` (Terra and Aqua), `c-sar` (Sentinel-1) and `asar` (Envisat). #### constellation The name of a logical collection of one or more platforms that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. This field allows users to search for related data sets without the need to specify which specific platform the data came from, for example, from either of the Sentinel-2 satellites. Examples include `landsat-8` (Landsat-8, a constellation consisting of a single platform), `sentinel-2` ([Sentinel-2](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation)), `rapideye` (operated by Planet Labs), and `modis` (NASA EOS satellites Aqua and Terra). In the case of `modis`, this is technically referring to a pair of sensors on two different satellites, whose data is combined into a series of related products. Additionally, the Aqua satellite is technically part of the A-Train constellation and Terra is not part of a constellation, but these are combined to form the logical collection referred to as MODIS. #### mission The name of the mission or campaign for collecting data. This could be a discrete set of data collections over a period of time (such as collecting drone imagery), or could be a set of tasks of related tasks from a satellite data collection. #### gsd The nominal Ground Sample Distance for the data, as measured in meters on the ground. There are many definitions of GSD. The value of this field should be related to the spatial resolution at the sensor, rather than the pixel size of images after orthorectification, pansharpening, or scaling. The GSD of a sensor can vary depending on geometry (off-nadir / grazing angle) and wavelength, so it is at the discretion of the implementer to decide which value most accurately represents the GSD. For example, Landsat8 optical and short-wave IR bands are all 30 meters, but the panchromatic band is 15 meters. The `gsd` should be 30 meters in this case because that is the nominal spatial resolution at the sensor. The Planet PlanetScope Ortho Tile Product has an `gsd` of 3.7 (or 4 if rounding), even though the pixel size of the images is 3.125. For example, one might choose for WorldView-2 the Multispectral 20° off-nadir value of 2.07 and for WorldView-3 the Multispectral 20° off-nadir value of 1.38. ================================================ FILE: stac-spec/item-spec/item-spec.md ================================================ # STAC Item Specification - [Overview](#overview) - [Item fields](#item-fields) - [Additional Field Information](#additional-field-information) - [stac_version](#stac_version) - [stac_extensions](#stac_extensions) - [id](#id) - [assets](#assets) - [bbox](#bbox) - [Properties Object](#properties-object) - [datetime](#datetime) - [Additional Fields](#additional-fields) - [Link Object](#link-object) - [Relation types](#relation-types) - [derived_from](#derived_from) - [Collections](#collections) - [Asset Object](#asset-object) - [Asset Media Type](#asset-media-type) - [Asset Roles](#asset-roles) - [Asset Role Types](#asset-role-types) - [Additional Fields for Assets](#additional-fields-for-assets) - [Media Type for STAC Item](#media-type-for-stac-item) - [Extensions](#extensions) ## Overview This document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) Item. An **Item** is a [GeoJSON](http://geojson.org/) [Feature](https://tools.ietf.org/html/rfc7946#section-3.2) augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC object. These include fields that identify the time range and assets of the Item. An Item is the core object in a STAC Catalog, containing the core metadata that enables any client to search or crawl online catalogs of spatial 'assets' (e.g., satellite imagery, derived data, DEMs). The same Item definition is used in both [STAC Catalogs](../catalog-spec/README.md) and the [Item-related API endpoints](https://github.com/radiantearth/stac-api-spec/blob/master/api-spec.md#ogc-api---features-endpoints). Catalogs are simply sets of Items that are linked online, generally served by simple web servers and used for crawling data. The search endpoint enables dynamic queries, for example selecting all Items in Hawaii on June 3, 2015, but the results they return are FeatureCollections of Items. Items are represented in JSON format and are very flexible. Any JSON object that contains all the required fields is a valid STAC Item. - Examples: - See the [minimal example](../examples/simple-item.json), as well as a [more fleshed example](../examples/core-item.json) that contains a number of current best practices. - Real world [implementations](https://stacindex.org/catalogs) are also available. - [JSON Schema](json-schema/item.json) ## Item fields This object describes a STAC Item. The fields `id`, `type`, `bbox`, `geometry` and `properties` are inherited from GeoJSON. | Field Name | Type | Description | | ---------- | -------------------------------------------------------------------------- | ----------- | | type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | | stac_version | string | **REQUIRED.** The STAC version the Item implements. | | stac_extensions | \[string] | A list of extensions the Item implements. | | id | string | **REQUIRED.** Provider identifier. The ID should be unique within the [Collection](../collection-spec/collection-spec.md) that contains the Item. | | geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) \| [null](https://tools.ietf.org/html/rfc7946#section-3.2) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | | bbox | \[number] | **REQUIRED if `geometry` is not `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | | links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is strongly recommended. | | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | | collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present and is *not allowed* otherwise. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | ### Additional Field Information #### stac_version In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. #### stac_extensions A list of extensions the Item implements. The list consists of URLs to JSON Schema files that can be used for validation. This list must only contain extensions that extend the Item specification itself, see the the 'Scope' for each of the extensions. #### id It is important that an Item identifier is unique within a Collection, and that the [Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to give a globally unique identifier. Items are *[strongly recommended](#collections)* to have Collections, and not having one makes it more difficult to be used in the wider STAC ecosystem. If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog or root Collection. As most geospatial assets are already uniquely defined by some identification scheme from the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. See the [id section of best practices](../best-practices.md#item-ids) for additional recommendations. #### assets This is a dictionary of [Asset Objects](#asset-object) data associated with the Item that can be downloaded or streamed, each with a unique key. In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers. Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them. To communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object). Assets should include the main asset, as well as any 'sidecar' files that are related and help a client make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.), unusable data masks, satellite ephemeris data, etc. Some assets (like Landsat data) are represented by multiple files - all should be linked to. It is generally recommended that different processing levels or formats are not exhaustively listed in an Item, but instead are represented by related Items that are linked to, but the best practices around this are still emerging. #### bbox Bounding Box of the asset represented by this Item using either 2D or 3D geometries, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). 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 depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the Item's geometry field, not its bbox. ### Properties Object Additional metadata fields can be added to the GeoJSON Object Properties. The only required field is `datetime` but it is recommended to add more fields, see [Additional Fields](#additional-fields) resources below. | Field Name | Type | Description | | ---------- | ------------ | ------------------------------------------------------------ | | datetime | string\|null | **REQUIRED.** The searchable date and time of the assets, which must be 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](common-metadata.md#date-and-time-range) to be set. | #### datetime This is likely the acquisition (in the case of single camera type captures) or the 'nominal' or representative time in the case of assets that are combined together. Though time can be a complex thing to capture, for this purpose keep in mind the STAC spec is primarily searching for data, so use whatever single date and time is most useful for a user to search for. STAC content extensions may further specify the meaning of the main `datetime` field, and many will also add more datetime fields. **All times in STAC metadata should be in [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC).** If there's clearly no meaningful single 'nominal' time, it is allowed to use `null` instead. In this case it is **required** to specify a temporal interval with the fields `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range). For example, if your data is a time-series that covers 100 years, it's not very meaningful to set the datetime to a single timestamp as it would not be found in most searches that searches for a decade of data in that period although the Item actually covers the decade. See [datetime selection](../best-practices.md#datetime-selection) in the best practices document for more information. #### Additional Fields Providers should include metadata fields that are relevant for users of STAC, but it is recommended to [select only those necessary for search](../best-practices.md#field-selection-and-metadata-linking). Where possible metadata fields should be mapped to the STAC Common Metadata and widely used extensions, to enable cross-catalog search on known fields. - [STAC Common Metadata](common-metadata.md#stac-common-metadata) - A list of fields commonly used throughout all domains. These optional fields are included for STAC Items by default. - [Extensions](../extensions/README.md) - Additional fields that are more specific, such as [EO](https://github.com/stac-extensions/eo), [View](https://github.com/stac-extensions/view). - [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom fields but it is recommended to add multiple fields for related values instead of a nested object, e.g., two fields `view:azimuth` and `view:off_nadir` instead of a field `view` with an object value containing the two fields. The convention (as used within Extensions) is for related fields to use a common prefix on the field names to group them, e.g. `view`. A nested data structure should only be used when the data itself is nested, as with `eo:bands`. ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal with the links section, to describe things like the Catalog an Item is in, related Items, parent or child Items (modeled in different ways, like an 'acquisition' or derived data). It is allowed to add additional fields such as a `title` and `type`. | Field Name | Type | Description | | ---------- | ------ | ----------- | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | | type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. #### Relation types STAC Items use a variety of `rel` types in the link object, to describe the exact nature of the link between this Item and the entity it is linking to. It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. | Type | Description | | ------------ | ------------------------------------------------------------ | | self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | URL to the root STAC entity (Catalog or Collection). | | parent | URL to the parent STAC entity (Catalog or Collection). | | collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. ##### derived_from *Note regarding the type `derived_from`: A full provenance model is far beyond the scope of STAC, and the goal is to align with any good independent spec that comes along for that. But the derived_from field is seen as a way to encourage fuller specs and at least start a linking structure that can be used as a jumping off point for more experiments in provenance tracking* #### Collections Items are *strongly recommended* to provide a link to a STAC Collection definition. It is important as Collections provide additional information about a set of items, for example the license, provider and other information giving context on the overall set of data that an individual Item is a part of. If Items are part of a STAC Collection, the [STAC Collection spec *requires* Items to link back to the Collection](../collection-spec/collection-spec.md#relation-types). Linking back must happen in two places: 1. The field `collection` in an Item must be filled (see section 'Item fields'). It is the `id` of a STAC Collection. 2. An Item must also provide a link to the STAC Collection using the [`collection` relation type](#relation-types): ```js "links": [ { "rel": "collection", "href": "link/to/collection/record.json" } ] ``` ### Asset Object An Asset is an object that contains a URI to data associated with the Item that can be downloaded or streamed. It is allowed to add additional fields. | Field Name | Type | Description | | ----------- | --------- | ----------- | | href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. | | title | string | The displayed title for clients and users. | | description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | type | string | [Media type](#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | | roles | \[string] | The [semantic roles](#asset-roles) of the asset, similar to the use of `rel` in links. | [Additional fields](#additional-fields) *may* be added to the assets, though this is recommended only in special cases. See [Additional Fields for Assets](#additional-fields-for-assets)) for more information. #### Asset Media Type Any media type can be used in an Item's asset `type` field, and [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) Media Types are preferred. STAC Items that have sidecar metadata files associated with a data asset (e.g, `.tfw`, Landsat 8 MTL files) should use media types appropriate for the the metadata file. For example, if it is a plain text file, then `text/plain` would be appropriate; if it is an XML, then `text/xml` is appropriate. For more information on media types as well as a list of [common media types](../best-practices.md#common-media-types-in-stac) used in STAC see the [best practice on working with media types](../best-practices.md#working-with-media-types). #### Asset Roles The `roles` field is used to describe the purpose of each asset. It is recommended to include one for every asset, to give users a sense of why they might want to make use of the asset. There are some emerging standards that enable clients to take particular action when they encounter particular roles, listed below. But implementors are encouraged to come up with their own terms to describe the role. ##### Asset Role Types Like the Link `rel` field, the `roles` field can be given any value, however here are a few standardized role names. | Role Name | Description | | --------- | ------------------------------------------------------------------------------------- | | thumbnail | An asset that represents a thumbnail of the Item, typically a true color image (for Items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | | overview | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | | data | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | | metadata | A metadata sidecar file describing the data in this Item, for example the Landsat-8 MTL file. | It is STRONGLY RECOMMENDED to add to each STAC Item - a thumbnail with the role `thumbnail` for preview purposes - one or more data file although it doesn't need to use the suggested role `data` Note that multiple roles per asset are encouraged: pick all the ones that apply. So many should have the 'data' role, and then another role to describe how the data is used. For more information on how to use roles see the [Asset Roles](../best-practices.md#asset-roles) section of the Best Practices document. It includes a [list of asset roles](../best-practices.md#list-of-asset-roles) that include many more ideas on roles to use. As they reach more widespread adoption we will include them here. #### Additional Fields for Assets As detailed above, Items contain properties, which are the main source of metadata for searching across Items. Many content extensions can add further property fields as well. Any property that can be specified for an Item can also be specified for a specific asset. This can be used to override a property defined in the Item, or to specify fields for which there is no single value for all assets. **It is important to note that the STAC API does not facilitate searching across Asset properties in this way, and this should be used sparingly.** It is primarily used to define properties at the Asset level that may be used during use of the data instead of for searching. For example, `gsd` defined for an Item represents the best Ground Sample Distance (resolution) for the data within the Item. However, some assets may be lower resolution and thus have a higher `gsd`. The `eo:bands` field from the EO extension defines an array of spectral bands. However, it may be useful instead to specify the bands that are used in a particular asset. For an example see the [sentinel2-sample](https://github.com/stac-utils/stac-examples/blob/main/sentinel2/sentinel2-sample.json). The Sentinel-2 overall `gsd` is 10m, because this is the best spatial resolution among all the bands and is defined in Item properties so it can be searched on. In the example Band 5 and others have a `gsd` of 20m, so that asset specifies the `gsd` as well, which overrides the Item `gsd` for this one asset. The example also includes reduced resolution versions of files included as assets, using `gsd` to represent the proper resolution. For `eo:bands`, it could be put in Item properties as an array of all the bands, but in this case it's not. Instead, the assets each define an array containing the spectral band information for that asset (in the order the bands appear in the file). For examples of fields that this construct is recommended for, see the [section of STAC Best Practices](../best-practices.md#common-use-cases-of-additional-fields-for-assets) that talks about common use cases of additional fields for assets. ## Media Type for STAC Item A STAC Item is a GeoJSON file ([RFC 7946](https://tools.ietf.org/html/rfc7946)), and thus should use the [`application/geo+json`](https://tools.ietf.org/html/rfc7946#section-12) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) (previously known as the MIME Type). ## Extensions There are emerging best practices, which in time will evolve in to specification extensions for particular domains or uses. The [extensions page](../extensions/README.md) gives an overview about relevant extensions for STAC Items. ================================================ FILE: stac-spec/item-spec/json-schema/basics.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/basics.json#", "title": "Basic Descriptive Fields", "type": "object", "properties": { "title": { "title": "Item Title", "description": "A human-readable title describing the Item.", "type": "string" }, "description": { "title": "Item Description", "description": "Detailed multi-line description to fully explain the Item.", "type": "string" } } } ================================================ FILE: stac-spec/item-spec/json-schema/datetime.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#", "title": "Date and Time Fields", "type": "object", "dependencies": { "start_datetime": { "required": [ "end_datetime" ] }, "end_datetime": { "required": [ "start_datetime" ] } }, "properties": { "datetime": { "title": "Date and Time", "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": ["string", "null"], "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "start_datetime": { "title": "Start Date and Time", "description": "The searchable start date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "end_datetime": { "title": "End Date and Time", "description": "The searchable end date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "created": { "title": "Creation Time", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "updated": { "title": "Last Update Time", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" } } } ================================================ FILE: stac-spec/item-spec/json-schema/instrument.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/instrument.json#", "title": "Instrument Fields", "type": "object", "properties": { "platform": { "title": "Platform", "type": "string" }, "instruments": { "title": "Instruments", "type": "array", "items": { "type": "string" } }, "constellation": { "title": "Constellation", "type": "string" }, "mission": { "title": "Mission", "type": "string" }, "gsd": { "title": "Ground Sample Distance", "type": "number", "exclusiveMinimum": 0 } } } ================================================ FILE: stac-spec/item-spec/json-schema/item.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#", "title": "STAC Item", "type": "object", "description": "This object represents the metadata for an item in a SpatioTemporal Asset Catalog.", "allOf": [ { "$ref": "#/definitions/core" } ], "definitions": { "common_metadata": { "allOf": [ { "$ref": "basics.json" }, { "$ref": "datetime.json" }, { "$ref": "instrument.json" }, { "$ref": "licensing.json" }, { "$ref": "provider.json" } ] }, "core": { "allOf": [ { "$ref": "https://geojson.org/schema/Feature.json" }, { "oneOf": [ { "type": "object", "required": [ "geometry", "bbox" ], "properties": { "geometry": { "$ref": "https://geojson.org/schema/Geometry.json" }, "bbox": { "type": "array", "oneOf": [ { "minItems": 4, "maxItems": 4 }, { "minItems": 6, "maxItems": 6 } ], "items": { "type": "number" } } } }, { "type": "object", "required": [ "geometry" ], "properties": { "geometry": { "type": "null" }, "bbox": { "not": {} } } } ] }, { "type": "object", "required": [ "stac_version", "id", "links", "assets", "properties" ], "properties": { "stac_version": { "title": "STAC version", "type": "string", "const": "1.0.0" }, "stac_extensions": { "title": "STAC extensions", "type": "array", "uniqueItems": true, "items": { "title": "Reference to a JSON Schema", "type": "string", "format": "iri" } }, "id": { "title": "Provider ID", "description": "Provider item ID", "type": "string", "minLength": 1 }, "links": { "title": "Item links", "description": "Links to item relations", "type": "array", "items": { "$ref": "#/definitions/link" } }, "assets": { "$ref": "#/definitions/assets" }, "properties": { "allOf": [ { "$ref": "#/definitions/common_metadata" }, { "anyOf": [ { "required": [ "datetime" ], "properties": { "datetime": { "not": { "type": "null" } } } }, { "required": [ "datetime", "start_datetime", "end_datetime" ] } ] } ] } }, "if": { "properties": { "links": { "contains": { "required": [ "rel" ], "properties": { "rel": { "const": "collection" } } } } } }, "then": { "required": [ "collection" ], "properties": { "collection": { "title": "Collection ID", "description": "The ID of the STAC Collection this Item references to.", "type": "string", "minLength": 1 } } }, "else": { "properties": { "collection": { "not": {} } } } } ] }, "link": { "type": "object", "required": [ "rel", "href" ], "properties": { "href": { "title": "Link reference", "type": "string", "format": "iri-reference", "minLength": 1 }, "rel": { "title": "Link relation type", "type": "string", "minLength": 1 }, "type": { "title": "Link type", "type": "string" }, "title": { "title": "Link title", "type": "string" } } }, "assets": { "title": "Asset links", "description": "Links to assets", "type": "object", "additionalProperties": { "$ref": "#/definitions/asset" } }, "asset": { "allOf": [ { "type": "object", "required": [ "href" ], "properties": { "href": { "title": "Asset reference", "type": "string", "format": "iri-reference", "minLength": 1 }, "title": { "title": "Asset title", "type": "string" }, "description": { "title": "Asset description", "type": "string" }, "type": { "title": "Asset type", "type": "string" }, "roles": { "title": "Asset roles", "type": "array", "items": { "type": "string" } } } }, { "$ref": "#/definitions/common_metadata" } ] } } } ================================================ FILE: stac-spec/item-spec/json-schema/licensing.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/licensing.json#", "title": "Licensing Fields", "type": "object", "properties": { "license": { "type": "string", "pattern": "^[\\w\\-\\.\\+]+$" } } } ================================================ FILE: stac-spec/item-spec/json-schema/provider.json ================================================ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/provider.json#", "title": "Provider Fields", "type": "object", "properties": { "providers": { "title": "Providers", "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "title": "Organization name", "type": "string", "minLength": 1 }, "description": { "title": "Organization description", "type": "string" }, "roles": { "title": "Organization roles", "type": "array", "items": { "type": "string", "enum": [ "producer", "licensor", "processor", "host" ] } }, "url": { "title": "Organization homepage", "type": "string", "format": "iri" } } } } } } ================================================ FILE: stac-spec/overview.md ================================================ # STAC Overview There are three component specifications that together make up the core SpatioTemporal Asset Catalog specification. Each can be used alone, but they work best in concert with one another. The [STAC API specification](https://github.com/radiantearth/stac-api-spec) builds on top of that core, but is out of scope for this overview. An [Item](item-spec/item-spec.md) represents a single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as [GeoJSON](https://geojson.org/) so it can be searched. The [Catalog](catalog-spec/catalog-spec.md) specification provides structural elements, to group Items and [Collections](collection-spec/collection-spec.md). Collections *are* catalogs, that add more required metadata and describe a group of related Items. For more on the differences see the [section below](#catalogs-vs-collections). A [UML diagram](https://en.wikipedia.org/wiki/Unified_Modeling_Language) of the [STAC model](STAC-UML.pdf) is also provided to help with navigating the specification. ## Foundations STAC is built on top of many great standards and practices. Every part of STAC is [JSON](https://www.json.org/json-en.html), and [GeoJSON](https://geojson.org/) provides the core geometry fields and [features](https://en.wikipedia.org/wiki/Simple_Features) definition. All fields are described in the specifications, and the acceptable values are defined with [JSON Schema](https://json-schema.org/). The released JSON Schemas provide the core testing definitions, and are used in an array of validation tools. We also rely on [RFC 8288 (Web Linking)](https://tools.ietf.org/rfc/rfc8288.txt) to express relationships between resources, and IANA [Media Types](https://en.wikipedia.org/wiki/Media_type) to describe file formats and format contents. The [OGC API - Features](https://ogcapi.ogc.org/features/) standard is a final core building block. The STAC Collection extends the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) JSON defined in OGC API - Features (and the full API definition is the foundation for the STAC API specification). The STAC specifications are written to be understandable without needing a full background in these. But if you want to get deep into STAC tool implementation and are not familiar with any of the standards mentioned above it is recommended to read up on them. STAC development is guided by set of core philosophical tenets, like building small reusable parts that are loosely coupled, focusing on developers, and more - see our the [principles](principles.md) document to learn more. *Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should not be used unless the STAC spec defines its use - instead the field should be left out entirely.* ## Item Overview Fundamental to any SpatioTemporal Asset Catalog, an [Item](item-spec/item-spec.md) object represents a unit of data and metadata, typically representing a single scene of data at one place and time. A STAC Item is a [GeoJSON](http://geojson.org/) [Feature](https://tools.ietf.org/html/rfc7946#section-3.2) and can be easily read by any modern GIS or geospatial library, and it describes a [SpatioTemporal Asset](#what-is-a-spatiotemporal-asset). The STAC Item JSON specification uses the GeoJSON geometry to describe the location of the asset, and then includes additional information: - the time the asset represents; - a thumbnail for quick browsing; - asset links, to enable direct download or streaming access of the asset; - relationship links, allowing users to traverse other related resources and STAC Items. A STAC Item can contain additional fields and JSON structures to communicate more information about the asset, so it can be easily searched. STAC provides a core set of [Common Metadata](item-spec/common-metadata.md) and there is a wider community working on a variety of [STAC Extensions](extensions/) that provide shared metadata for more specific domains. Both aim to describe data with well known, well defined terms to enable consistent publishing and better search. For more recommendations on selecting fields for an Item see [this section](best-practices.md#field-selection-and-metadata-linking) of the best practices document. ### What is a SpatioTemporal Asset A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time. Examples include Imagery (from satellites, planes and drones), SAR, Point Clouds (from LiDAR, Structure from Motion, etc), Data Cubes, Full Motion Video, and data derived from any of those. The key is that the GeoJSON is not the actual 'thing', but instead references files and serves as an index to the 'assets'. It is [not recommended](best-practices.md#representing-vector-layers-in-stac) to use STAC to refer to traditional vector data layers (shapefile, geopackage) as assets, as they don't quite fit conceptually. ## Catalogs vs Collections Before we go deep into the Catalogs and Collections, it is worth explaining the relationship between the two and when you might want to use one or the other. A Catalog is a very simple construct - it just provides links to Items or to other Catalogs. The closest analog is a folder in a file structure, it is the container for Items, but it can also hold other containers (folders / catalogs). The Collection entity shares most fields with the Catalog entity but has a number of additional fields: license, extent (spatial and temporal), providers, keywords and summaries. Every Item in a Collection links back to their Collection, so clients can easily find fields like the license. Thus every Item implicitly shares the fields described in their parent Collection. Collection entities can be used just like Catalog entities to provide structure, as they provide all the same options for linking and organizing. But what *should* go in a Collection, versus just in a Catalog? A Collection will generally consist of a set of assets that are defined with the same properties and share higher level metadata. In the satellite world these would typically all come from the same sensor or constellation. It corresponds directly to what others call a "dataset series" (ESA, ISO 19115), "collection" (CNES, NASA), and "dataset" (JAXA, DCAT). So if all your Items have the same properties, they probably belong in the same Collection. But the construct is deliberately flexible, as there may be good reasons to break the recommendation. Catalogs in turn are used for two main things: - Split overly large collections into groups - Group collections into a catalog of Collections (e.g. as entry point for navigation to several Collections). The first case allows users to browse down into the Items of large collections. A collection like Landsat usually would start with path and row Catalogs to group by geography, and then year, month and day groups to enable deeper grouping. [Dynamic catalogs](best-practices.md#dynamic-catalogs) can provide multiple grouping paths, serving as a sort of faceted search. The second case is used when one wants to represent diverse data in a single place. If an organization has an internal catalog with Landsat 8, Sentinel 2, NAIP data and several commercial imagery providers then they'd have a root Catalog that would link to a number of different Collections. So in conclusion it's best to use Collections for what you want user to find as starting point, and then Catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually search Collection-level data, hopefully in concert with other specifications. ## Catalog Overview *NOTE: The below examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to serve as a Catalog* There are two required element types of a Catalog: Catalog and Item. A STAC Catalog points to [STAC Items](item-spec/README.md), or to other STAC catalogs. It provides a simple linking structure that can be used recursively so that many Items can be included in a single Catalog, organized however the implementor desires. STAC makes no formal distinction between a "root" Catalog and the "child" Catalogs. A root Catalog is simply the top-most Catalog or Collection -- it has no parent. A nested catalog structure is useful (and recommended) for breaking up massive numbers of catalog Items into logical groupings. For example, it might make sense to organize a catalog by date (year, month, day), or geography (continent, country, state/prov). See the [Catalog Layout](best-practices.md#catalog-layout) best practices section for more. A simple STAC structure might look like this: - catalog (root) - catalog - catalog - item - asset - item - asset - item - asset - asset This example might be considered a somewhat "typical" structure. However, Catalogs and Items can describe a number of different relationships. The following shows various relationships between catalogs and items: - `Catalog` -> `Item` (this is a common structure for a catalog to list links to Items) - `Catalog` -> `Catalog` (this is a common tree structure to group sets of Items. Each catalog in this relationship may also include Item links as well as catalog links) The relationships are all described by a common `links` object structure, making use of the `rel` field to further describe the relationship. There are a few types of catalogs that implementors occasionally refer to. These get defined by the `links` structure. - A **sub-catalog** is a Catalog that is linked to from another Catalog that is used to better organize data. For example a Landsat collection might have sub-catalogs for each Path and Row, so as to create a nice tree structure for users to follow. - A **root catalog** is a Catalog that only links to sub-catalogs. These are typically entry points for browsing data. Often they will contain the [STAC Collection](collection-spec/) definition, but in implementations that publish diverse information it may contain sub-catalogs that provide a variety of Collections. - A **parent catalog** is the Catalog that sits directly above a sub-catalog. Following parent catalog links continuously will naturally end up at a root catalog definition. It should be noted that a Catalog does not have to link back to all the other Catalogs that point to it. Thus a published root catalog might be a sub-catalog of someone else's structure. The goal is for data providers to publish all the information and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are linked to across the web. ### Static and Dynamic Catalogs The Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as simply putting linked json files on a file server or an object storage service (like [AWS S3](https://aws.amazon.com/s3/)), or it can be generated on the fly by a live server. The first type of implementation is often called a 'static catalog', and any catalog that is not just files is called a 'dynamic catalog'. You can read more about the two types along with recommendations in [this section](best-practices.md#static-and-dynamic-catalogs) of the best practices document, along with how to keep a [dynamic catalog in sync](best-practices.md#static-to-dynamic-best-practices) with a static one. ### Catalog Best Practices In addition to information about different catalog types, the [best practices document](best-practices.md) has a number of suggestions on how to organize and implement good catalogs. The [catalog specification](catalog-spec/catalog-spec.md) is designed for maximum flexbility, so none of these are required, but they provide guidance for implementors who want to follow what most of the STAC community is doing. - [Catalog Layout](best-practices.md#catalog-layout) is likely the most important section, as following its recommendations will enable catalogs to work better with client tooling that optimizes for known layouts. - [Use of Links](best-practices.md#use-of-links) articulates practices for making catalogs that are portable (with relative links through out) and ones that are published in stable locations (with absolute self links). - [Versioning for Catalogs](best-practices.md#versioning-for-catalogs) explains how to use STAC's structure to keep a history of changes made to Items and catalogs. - [STAC on the Web](best-practices.md#stac-on-the-web) explains how catalogs should have html versions for each Item and Catalog, as well as ways to achieve that. ## Collection Overview A STAC Collection includes the core fields of the Catalog entity and also provides additional metadata to describe the set of Items it contains. The required fields are fairly minimal - it includes the 4 required Catalog fields (id, description, stac_version and links), and adds license and extents. But there are a number of other common fields defined in the spec, and more common fields are also defined in [STAC extensions](extensions/). These serve as basic metadata, and ideally Collections also link to fuller metadata (ISO 19115, etc) when it is available. As Collections contain all of Catalogs' core fields, they can be used just as flexibly. They can have both parent Catalogs and Collections as well as child Items, Catalogs and Collections. Items are strongly recommended to have a link to the Collection they are a part of. Items can only belong to one Collection, so if an Item is in a Collection that is the child of another Collection, then it must pick which one to refer to. Generally the 'closer' Collection, the more specific one, should be the one linked to. The Collection specification is used standalone quite easily - it is used to describe an aggregation of data, and doesn't require links down to sub-catalogs and Items. This is most often used when the software does operations at the layer / coverage level, letting users manipulate a whole collection of assets at once. They often have an optimized internal format that doesn't make sense to expose as Items. [OpenEO](https://openeo.org/) and [Google Earth Engine](https://earthengine.google.com/) are two examples that only use STAC collections, and both would be hardpressed to expose individual Items due to their architectures. For others implementing STAC Collections can also be a nice way to start and achieve some level of interoperability. ================================================ FILE: stac-spec/package.json ================================================ { "name": "stac-spec", "version": "1.0.0", "description": "STAC spec helpers to check the spec.", "repository": "https://github.com/radiantearth/stac-spec", "license": "Apache-2.0", "scripts": { "check": "npm run check-markdown && npm run check-examples", "check-markdown": "remark . -f -r .circleci/rc.yaml", "check-examples": "stac-node-validator . --lint --verbose --schemas .", "format-examples": "stac-node-validator . --format --schemas .", "publish-schemas": "node .circleci/publish-schemas.js" }, "dependencies": { "gh-pages": "^3.0.0", "klaw-sync": "^6.0.0", "remark-cli": "^8.0.0", "remark-lint": "^7.0.0", "remark-lint-no-html": "^2.0.0", "remark-preset-lint-consistent": "^3.0.0", "remark-preset-lint-markdown-style-guide": "^3.0.0", "remark-preset-lint-recommended": "^4.0.0", "remark-validate-links": "^10.0.0", "stac-node-validator": "^1.1.0" } } ================================================ FILE: stac-spec/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. - **JSON + REST + HTTP at the core.** JSON has won over XML, and REST 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 REST 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. [JSON API](http://jsonapi.org/) should be used as basis of decisions where possible. - **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. - **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. Fully accepted specifications should have at least 3 implementations that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) 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: stac-spec/process.md ================================================ ## STAC Development & Release Process ### Development Process The SpatioTemporal Asset Catalog specification is under active development. The goal is to get to a small, flexible stable release that can be extended in a variety of ways. The core development team aims to release early and often, which generally has meant a new release between two and four months since the previous one. The `master` branch aims to always be stable, meaning that all the pieces of the specification are consistent and well explained, and all the examples are consistent with the specification. The `dev` 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. The team uses the [stac-spec issue tracker](https://github.com/radiantearth/stac-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. Any changes to the spec must be made as pull requests to the `dev` branch. Anyone is welcome and encouraged to bring ideas and improvements, to the issue tracker or (ideally) as pull requests. To merge a new pull request the work must be reviewed by at least two members of the STAC spec 'core team' (who have write access to the main repository). It also must pass the Continuous Integration (CI) testing, which checks all markdown and example files for proper formatting, and also validates all examples against JSON schema. For more information about making pull requests see [CONTRIBUTING.md](CONTRIBUTING.md), and there is also information on how to [run the CI checks locally](CONTRIBUTING.md#check-files). #### Core STAC Team The current list of people who are part of the 'core STAC team', and can approve pull requests. - [Alex Kaminsky](https://github.com/alkamin) - [Alexandra Kirk](https://github.com/anayeaye) - [Chris Holmes](http://github.com/cholmes) - [Emmanuel Mathot](https://github.com/emmanuelmathot) - [Michael Smith](https://github.com/hgs-msmith) - [James Banting](https://github.com/jbants) - [James Santucci](https://github.com/jisantuc) - [Josh Fix](https://github.com/joshfix) - [Rob Emanuele](https://github.com/lossyrob) - [Matthias Mohr](https://github.com/m-mohr) - [Matt Hanson](https://github.com/matthewhanson) - [Phil Varner](https://github.com/philvarner) Anyone can be nominated to the core STAC team, and that generally happens after contributing a few pull requests and/or helping review other PR's. Nominations are reviewed by the [PSC](#project-steering-committee), and must recieve 3 positive votes and no negatives. ### 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. - **Agreement from the Project Steering Committee**: The PSC should meet (on phone 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 version numbers**: There are several places in the spec that use the version number or a branch name in text or a link. These include the markdown files and the JSON schemas. Right now the best thing to do is just a search & replace for the last version number and `https://schemas.stacspec.org/dev/` with `https://schemas.stacspec.org//` (in JSON Schemas, don't replace it here). `` must correspond with the tag on GitHub, usually including a leading `v`. Hopefully in the future there will be scripts to do this. - **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. - **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github repository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state of the spec. - **Release on Github**: The final step to create the release is to add a new 'release' on . 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 a client like STAC Browser 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 rc.2. 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 master, with no changes to the spec - just updating the version numbers. ### Governance The vast majority of decisions on STAC are made by the [Core STAC Team](#core-stac-team) reaching consensus in discussions in pull requests and issues. Any change to the specification must have two positive reviews and no negative reviews. #### Project Steering Committee For the rare case where a decision cannot be reached by consensus, there is a Project Steerting Committee that has ultimate decision making authority. This consists of individuals who are intended to represent the various communities which have a stake in the specification and surrounding ecosystem. An odd number is chosen to facilitate the voting process and help prevent ties. This committee also handles the allocation of any funds that are raised for the project. Turnover is allowed and expected to accommodate people only able to become active on the project in intervals. A PSC member may step down at any time. #### Current Project Steering Committee - [Matthias Mohr](https://github.com/m-mohr) - University of Muenster, [OpenEO](https://openeo.org/) and [Radiant Earth](https://www.radiant.earth/) - [Matt Hanson](https://github.com/matthewhanson) - [Element 84](https://www.element84.com/) - [James Banting](https://github.com/jbants) - [SparkGeo](https://sparkgeo.com/) - [Rob Emanuele](https://github.com/lossyrob) - [Microsoft](https://microsoft.com/) - [Chris Holmes](https://github.com/cholmes) - [Planet](https://planet.com) and [Radiant Earth](https://www.radiant.earth/) #### PSC Membership A new PSC member can be nominated at any time. Voting for a new PSC is done by current active PSC members. PSC nominations are generally given in recognition to very significant contributions to the specification or the broader ecosystem. PSC members are not expected to be technical, and we hope to recognized contributions in documentation, outreach and evangelism. Nominated PSC members must recieve a majority of +1 vote’s from the PSC, and no -1’s. The initial PSC was selected by Chris Holmes, who was deemed the 'Benevolent Dictator for Life' for the bootstrapping phase.