[
  {
    "path": ".circleci/.spectral-fragments.yml",
    "content": "extends: \"spectral:oas\"\nrules:\n  openapi-tags: off\n  info-contact: off\n  oas3-api-servers: off\n  oas3-unused-component: off\n  operation-operationId: off\n  oas3-parameter-description: true"
  },
  {
    "path": ".circleci/.spectral.yml",
    "content": "extends: \"spectral:oas\"\nrules:\n  oas3-api-servers: off\n  oas3-schema: warn\n  tag-description: true\n  oas3-parameter-description: true"
  },
  {
    "path": ".circleci/build-openapi.sh",
    "content": "#!/bin/bash\n\nPATH=./node_modules/.bin:$PATH\n\n# find all OpenAPI docs that are not fragments\nFINS=(core/openapi.yaml item-search/openapi.yaml ogcapi-features/openapi-collections.yaml ogcapi-features/openapi-features.yaml)\nFOUTS=(core item-search collections ogcapi-features)\n\nfor i in \"${!FINS[@]}\"; do\n    fout=./build/${FOUTS[$i]}/openapi.yaml\n    mkdir -p \"${fout%/*}\"\n    openapi bundle --ext yaml --output \"${fout}\" \"${FINS[$i]}\"\n    cp build/redoc_index.html \"${fout%/*}\"/index.html\ndone\n"
  },
  {
    "path": ".circleci/config.yml",
    "content": "version: 2.1\n\nreferences:\n  restore_repo: &restore_repo\n    restore_cache:\n      keys:\n        - v0-repo-{{ .Branch }}-{{ .Revision }}\n        - v0-repo-{{ .Branch }}\n        - v0-repo\n\n  restore_dependencies: &restore_dependencies\n    restore_cache:\n      keys: \n        - v0-dependencies-{{ checksum \"package.json\"}}\n        - v0-dependencies\n\n  restore_build: &restore_build\n    restore_cache:\n      keys: \n        - v0-build-{{ .Branch }}-{{ .Revision }}\n\n\njobs:\n  validate:\n    working_directory: ~/stac\n    docker:\n      - image: cimg/node:16.14\n    steps:\n      - checkout\n      - save_cache:\n          key: v0-repo-{{ .Branch }}-{{ .Revision }}\n          paths:\n            - ~/stac\n      - run:\n          name: install\n          command: npm install\n      - save_cache:\n          key: v0-dependencies-{{ checksum \"package.json\"}}\n          paths:\n            - ~/stac/node_modules\n      - run:\n          name: validate\n          command: npm run check\n  build:\n    working_directory: ~/stac\n    docker:\n      - image: cimg/node:16.14\n    steps:\n      - *restore_repo\n      - *restore_dependencies\n      - run:\n          name: build openapi\n          command: npm run build-openapi\n      - save_cache:\n          key: v0-build-{{ .Branch }}-{{ .Revision }}\n          paths:\n            - ~/stac/build\n  publish:\n    working_directory: ~/stac\n    docker:\n      - image: cimg/node:16.14\n    steps:\n      - *restore_repo\n      - *restore_dependencies\n      - *restore_build\n      - add_ssh_keys\n      - run:\n          name: publish\n          command: |\n            ssh-keyscan github.com >> ~/.ssh/known_hosts\n            npm run publish-openapi -- $CIRCLE_TAG\n  check-core-changes:\n    working_directory: ~/stac\n    docker:\n      - image: cimg/node:16.14\n    steps:\n      - *restore_repo\n      - *restore_dependencies\n      - run:\n          name: check-core-changes\n          command: npm run check-stac-spec-changes --compare-to=<< pipeline.git.base_revision >>\n\nworkflows:\n  version: 2\n  ci:\n    jobs:\n      - validate:\n          filters:\n            tags:\n              only: /^v.*/\n      - build:\n          requires:\n            - validate\n          filters:\n            tags:\n              only: /^v.*/\n      - check-core-changes:\n          requires:\n            - validate\n          filters:\n            tags:\n              only: /^v.*/\n      - publish:\n          requires:\n            - build\n          filters:\n            tags:\n              only: /^v.*/\n            branches:\n              # Only main branch, not PRs\n              only: main"
  },
  {
    "path": ".circleci/publish.js",
    "content": "const ghpages = require('gh-pages');\n\nlet args = process.argv.slice(2);\nlet tag = 'main';\nif (args.length && args[0].trim().length > 0) {\n\ttag = args[0];\n}\n\nghpages.publish('build/', {\n\tsrc: '**',\n\tdest: tag,\n\tmessage: 'Publish JSON Schemas [ci skip]',\n\tuser: {\n\t  name: 'STAC CI',\n\t  email: 'ci@stacspec.org'\n\t}\n}, error => {\n\tconsole.error(error ? error : 'Deployed to gh-pages');\n\tprocess.exit(error ? 1 : 0);\n});"
  },
  {
    "path": ".github/pull_request_template.md",
    "content": "**Related Issue(s):** \n\n- #\n\n**Proposed Changes:**\n\n1. \n2. \n\n**PR Checklist:**\n\n- [ ] This PR has **no** breaking changes.\n- [ ] 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))\n- [ ] 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.\n"
  },
  {
    "path": ".gitignore",
    "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Runtime data\npids\n*.pid\n*.seed\n*.pid.lock\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nlib-cov\n\n# Coverage directory used by tools like istanbul\ncoverage\n\n# nyc test coverage\n.nyc_output\n\n# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)\n.grunt\n\n# Bower dependency directory (https://bower.io/)\nbower_components\n\n# node-waf configuration\n.lock-wscript\n\n# Compiled binary addons (https://nodejs.org/api/addons.html)\nbuild/Release\n\n# Dependency directories\nnode_modules/\njspm_packages/\n\n# Typescript v1 declaration files\ntypings/\n\n# Optional npm cache directory\n.npm\n\n# Optional eslint cache\n.eslintcache\n\n# Optional REPL history\n.node_repl_history\n\n# Output of 'npm pack'\n*.tgz\n\n# Yarn Integrity file\n.yarn-integrity\n\n# dotenv environment variables file\n.env\n\n# next.js build output\n.next\n\n# IntelliJ IDEA files\n.idea/\n*.iml\n"
  },
  {
    "path": ".nvmrc",
    "content": "16\n"
  },
  {
    "path": ".remarkignore",
    "content": "/CHANGELOG.md\n/CODE_OF_CONDUCT.md"
  },
  {
    "path": "CHANGELOG.md",
    "content": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [v1.0.0] - 2023-04-24\n\nNone\n\n## [v1.0.0-rc.4] - 2023-04-13\n\n## Changed\n\n- Field `type` is no longer required for all Link objects, but is instead strongly\n  recommended. This was added as a requirement in 1.0.0-rc.3 based on a mis-reading\n  of the OGC Features spec, and is now removed as a requirement.\n\n## [v1.0.0-rc.3] - 2023-03-27\n\n## Changed\n\n- Browseable has been moved to an extension, now located at <https://github.com/stac-api-extensions/browseable>\n- Link relation `parent` is no longer a required link for Collections or Items\n- Field `type` is now required for all Link objects\n\n## Added\n\n- Added authentication status code recommendations.\n- Added extension field to all OpenAPI specifications `x-conformance-classes` indicating the\n  conformance classes they define.\n- STAC API - Item Search now requires a `root` link relation in the response from `/search`\n- Added a `collection` link from and Item to its Collection to conform with the STAC spec.\n\n### Fixed\n\n- 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.\n\n## [v1.0.0-rc.2] - 2022-11-01\n\n### Added\n\n- Added optional `numberMatched` and `numberReturned` fields to ItemCollection to align with OGC Commons\n  and OAFeat.\n\n### Changed\n\n- The Collections specification has been incorporated into the *Features* specification, but remains as\n  a separate conformance class.\n- The Browseable specification has been incorporated into the *Core* specification, but remains as\n  a separate conformance class.\n- Extensions moved to standalone specification repositories:\n  - [Items and Collections API Version](https://github.com/stac-api-extensions/version)\n  - [Fields](https://github.com/stac-api-extensions/fields)\n  - [Filter](https://github.com/stac-api-extensions/filter)\n  - [Context](https://github.com/stac-api-extensions/context)\n  - [Sort](https://github.com/stac-api-extensions/sort)\n  - [Transaction](https://github.com/stac-api-extensions/transaction)\n  - [Query](https://github.com/stac-api-extensions/query)\n  - [Children](https://github.com/stac-api-extensions/children)\n\n### Fixed\n\n- 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\nservice description must return a 400 Bad Request status code.\n\n## [v1.0.0-rc.1] - 2022-03-17\n\n### Added\n\n- The CQL2 Accent and Case-insensitive Comparison\n    (`http://www.opengis.net/spec/cql2/1.0/conf/accent-case-insensitive-comparison`) conformance class\n    adds the ACCENTI and CASEI functions for case-insensitive comparison. These replace the UPPER and\n    LOWER psuedo-functions that were previously part of the Advanced Comparison Operators class.\n\n### Changed\n\n- Query Extension is no longer deprecated.\n- Children conformance class now requires the /children endpoint includes all child catalogs or collections\n  referenced via `child` link relations from the Landing Page\n- Clarified behavior of Transaction Extension endpoints:\n  - PUT and PATCH of a body that changes the `collection` or `id` is disallowed.\n  - POST, PUT, and PATCH do not need to include the `collection` attribute, as it should be derived from the URL.\n  - 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\n    the server can derive a valid Item, e.g., by populating the id and collection fields or adding links\n  - Likewise, POST can be used with a body of a FeatureCollection that contains features that meet the same constraints.\n- Specifications now use the term \"must\" instead of \"shall\". The semantics of these words are identical.\n- Conformance class for Item Search Filter is now\n  `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`, whereas before it was incorrectly stated as\n  `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n## [v1.0.0-beta.5] - 2022-01-14\n\n### Added\n\n- Added `STAC API - Browseable` conformance class\n- Added `STAC API - Children` conformance class\n- Added description of how to support both search and browse in an API.\n- The paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used\n  for the STAC API - Features endpoint `/collections/{collection_id}/items`, as described in OAFeat.\n- The paging mechanism via a Link with rel `next` or `prev` as defined for items can also be used\n  for the STAC API - Features and STAC API - Collections endpoint `/collections`.\n\n### Changed\n\n- Limit parameter semantics now match OAFeat. Previously, the behavior was not precisely defined.\n- Filter Extension updates to align with changes to OAFeat CQL2 spec\n  - Updated all \"CQL\" usages to \"CQL2\"\n  - Most conformance class URIs are now prefixed with `http://www.opengis.net/spec/cql2/` instead\n    of `http://www.opengis.net/spec/ogcapi-features-3/`\n  - Conformance classes `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/basic-cql`,\n    `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-text`, and\n    `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-json` have had `cql` replaced\n    with `cql2` (in addition to the prefix change) to\n    become `http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2`,\n    `http://www.opengis.net/spec/cql2/1.0/conf/cql2-text`, and\n    `http://www.opengis.net/spec/cql2/1.0/conf/cql2-json`\n  - Significant changes to CQL2 JSON format, now using `op` and `args` structure\n  - Spatial operator `INTERSECTS` is now `S_INTERSECTS`\n  - Temporal operator `ANYINTERACTS` is now `T_INTERSECTS`\n  - Updated Example 3 (now Example 5) to make it clear that property to property comparisons require the\n    Property-Property Comparisons conformance class\n  - The CQL2 Case-insensitive Comparison\n    (`http://www.opengis.net/spec/cql2/1.0/conf/case-insensitive-comparison`) conformance class\n    that adds UPPER/LOWER terms or function CASEI for case-insensitive comparison has not been added\n    to this spec yet, since the definition in CQL2 is in flux.\n- `service-desc` endpoint may return any service description format, typically a\n  machine-consumable one (previous restricted required to be OpenAPI 3.0 JSON)\n- `service-doc` endpoint may return any service description format, typically a\n  human-consumable one (previous restricted required to be HTML)\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n- Collection conformance class URI should be `https://api.stacspec.org/v1.0.0-beta.XXX/collections` instead\n  of `http://stacspec.org/spec/api/1.0.0-beta.XXX/extensions/collections`\n- definition of Item object was missing `properties` as an attribute\n- Filter Extension - examples of using intervals and timestamps in CQL2 were incorrect and have been fixed\n- Filter Extension - examples are updated so that text and json examples are equivalent\n\n## [v1.0.0-beta.4] - 2021-10-05\n\n### Added\n\n- Support binding Sort, Fields, and Context Extensions to STAC Features items resource\n  endpoint (`/collections/{collectionId}/items`)\n- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints\n- In Item Search, added endpoint table\n\n### Changed\n\n- Filter Extension - query language is now referred to as \"CQL2\" rather than CQL\n- Filter Extension now uses OAFeat Part 3 conformance class URIs\n- 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\n  whose names have changed also have changed conformance URI strings.\n  - \"Basic CQL\" now includes the \"not equal\" operator (`<>`)\n  - \"Basic CQL\" has always supported datetime comparisons, but this is now explicitly mentioned\n  - \"Enhanced Comparison Operators\" has been renamed \"Advanced Comparison Operators\". This is the same as the OAFeat CQL definition, except\n    that it does not require the `upper` and `lower` functions.\n  - \"Enhanced Spatial Operators\" has been renamed to just \"Spatial Operators\" (not to be confused with Basic Spatial Operators)\n  - \"Basic Temporal Operators\" and \"Enhanced Temporal Operators\" have merged into \"Temporal Operators\"\n  - \"Functions\" has been renamed \"Custom Functions\"\n  - \"Arithmetic\" has been renamed \"Arithmetic Expressions\"\n  - \"Arrays\" has been renamed \"Array Operators\"\n  - \"Queryable Second Operand\" has been renamed \"Property-Property Comparisons\"\n- The required Link Relations and endpoints for each conformance class now use the wording of 'shall'\n  instead of 'should'. While this technically changes the semantics, it was generally understood\n  previously the semantics were those of 'shall' (must).\n- Explicitly state that the `/children` endpoint can return Catalog and Collection objects that have fewer\n  fields than are available through other endpoints.\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n## [v1.0.0-beta.3] - 2021-08-06\n\n### Added\n\n- Added STAC API - Collections definition (subset of STAC API - Features)\n- More thorough definitions for valid `datetime` and `bbox` query parameter values.\n\n### Changed\n\n- Query extension not deprecated; recommendation to use Filter (<https://github.com/radiantearth/stac-api-spec/pull/157>)\n- Filter Extension conformance classes refactored to better align with STAC API use cases.\n- Renamed conformance class \"Queryable First Operand\"\n  (<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand>) to\n  \"Queryable Second Operand\"\n  (<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-second-operand>)\n\n### Deprecated\n\n### Removed\n\n- Remove stac_version and stac_extensions fields in ItemCollection\n\n### Fixed\n\n## [v1.0.0-beta.2] - 2021-06-01\n\n### Added\n\n- Added Filter extension to integrate OAFeat Part 3 CQL\n- Catalog and Collection definitions now have required field \"type\"\n- Added recommendation to enable CORS for public APIs\n\n### Changed\n\n- Updated all STAC versions to 1.0.0\n- Passing the `ids` parameter to an item search does not deactivate other query parameters [#125](https://github.com/radiantearth/stac-api-spec/pull/125)\n- 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)\n\n### Deprecated\n\n- Query extension is now deprecated. Replaced by the Filter extension using OGC CQL.\n\n### Removed\n\n### Fixed\n\n- Updated text description of root ('/') endpoint (also called landing page) that the return type is a Catalog\n\n## [v1.0.0-beta.1] - 2020-12-10\n\n### Added\n\n- The landing page returns the conformance classes in a property `conformsTo`, which mirrors `GET /conformances` from OGC APIs.\n- Conformance classes for all the major functionality and extensions, to be referenced in a new `conformsTo` JSON object in the landing page.\n- Fragments: reusable OpenAPI documents for sort, filter, fields and context, along with explanation of how they work.\n- ItemCollection moved from [STAC Core](https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/itemcollection-spec.md) to this repo.\n\n### Changed\n\n- Major re-organization of the content and directory structure to make better conformance classes.\n  - STAC API Core is the landing page (a STAC catalog and conformance information).\n  - Item Search is the `search` cross-collection item search resource.\n  - STAC API - Features is the OGC API - Features standards to be used in a STAC API.\n  - Extensions are specified in the relevant functionality directory, though they can share openapi yaml's in the 'fragments' directory.\n- Updated to STAC specification version 1.0.0-beta.2\n- Named explicit supported STAC core versions to be from 0.9.0 up to (and not including) 2.0.0\n- Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute\n- Added root endpoint Link `search` must have `type` of `application/geo+json`\n- Corrected the description of endpoint `/collections` to say it returns an object per OAFeat, instead of an array of Collection\n- Updated transaction extension so it aligns with OGC API - Features Part 4: Simple Transactions\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n- BBOX openapi yaml to only allow 4 or 6 element arrays\n- Fixed invalid OpenAPI files\n\n## Older versions\n\nSee the [stac-spec CHANGELOG](https://github.com/radiantearth/stac-spec/blob/v0.9.0/CHANGELOG.md)\nfor STAC API releases prior to or equal to version 0.9.0.\n\n[Unreleased]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0...main>\n[v1.0.0]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0>\n[v1.0.0-rc.4]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.4>\n[v1.0.0-rc.3]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3>\n[v1.0.0-rc.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2>\n[v1.0.0-rc.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1>\n[v1.0.0-beta.5]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5>\n[v1.0.0-beta.4]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.4>\n[v1.0.0-beta.3]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.3>\n[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.2>\n[v1.0.0-beta.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1>\n"
  },
  {
    "path": "CITATION.cff",
    "content": "cff-version: 1.2.0\nmessage: \"If you are referring to the STAC API specification in your publications, please cite it as below.\"\ntype: software\ntitle: \"SpatioTemporal Asset Catalog (STAC) API specification\"\nauthors:\n  - name: \"STAC API Contributors\"\npreferred-citation:\n  type: standard\n  title: \"SpatioTemporal Asset Catalog (STAC) API specification\"\n  abstract: \"An API to make geospatial assets openly searchable and crawlable.\"\n  version: v1.0.0\n  year: 2023\n  date-released: 2023-04-24\n  license: Apache-2.0\n  url: https://stacspec.org\n  repository: https://github.com/radiantearth/stac-api-spec\n  authors:\n    - name: \"STAC API Contributors\"\n      email: stac-psc@radiant.earth\n"
  },
  {
    "path": "CODE_OF_CONDUCT.md",
    "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, caste, color, religion, or sexual\nidentity and orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n* Demonstrating empathy and kindness toward other people\n* Being respectful of differing opinions, viewpoints, and experiences\n* Giving and gracefully accepting constructive feedback\n* Accepting responsibility and apologizing to those affected by our mistakes,\n  and learning from the experience\n* Focusing on what is best not just for us as individuals, but for the overall\n  community\n\nExamples of unacceptable behavior include:\n\n* The use of sexualized language or imagery, and sexual attention or advances of\n  any kind\n* Trolling, insulting or derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or email address,\n  without their explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n  professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement at\n[stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com). \nAll complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series of\nactions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or permanent\nban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within the\ncommunity.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.1, available at\n[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].\n\nCommunity Impact Guidelines were inspired by\n[Mozilla's code of conduct enforcement ladder][Mozilla CoC].\n\nFor answers to common questions about this code of conduct, see the FAQ at\n[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at\n[https://www.contributor-covenant.org/translations][translations].\n\n[homepage]: https://www.contributor-covenant.org\n[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html\n[Mozilla CoC]: https://github.com/mozilla/diversity\n[FAQ]: https://www.contributor-covenant.org/faq\n[translations]: https://www.contributor-covenant.org/translations\n\n"
  },
  {
    "path": "CONTRIBUTING.md",
    "content": "## Contributing\n\nPull Requests are the primary method of contributing to the spec itself, and everyone is welcome to submit \nchanges. Suggestions for changes to the core will be taken with higher priority if a clear implementation \nof STAC API has been built that can highlight the problem.\n\nWe consider everyone using the specification to catalog their data to be a 'contributor', as STAC is\nreally about the end result of more interoperable data, not just creating a spec for the sake of it.\nSo if you want to help then the best thing you can do is make new catalogs or build software that uses\nthe spec. And please do give us feedback. The best place to do so is on our \n[gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). If you are interested in helping\nbut aren't sure where to, then see the [stac-ecosystem](https://github.com/stac-utils/stac-ecosystem) repo\nfor ideas on projects to advance STAC. \n\n## Development Process\n\nThe SpatioTemporal Asset Catalog API specification is under active development. \n\nThe `main` branch is a place of active development, \nwhere a new change in one part of the spec might not yet be fully updated everywhere else. Releases are tagged. The team uses the\n[stac-api-spec issue tracker](https://github.com/radiantearth/stac-api-spec/issues) to identify and track all that will be done for \na release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and\nexamples.\n\n### Submitting Pull Requests\n\nAny proposed changes to the specification should be done as pull requests. Please make these\nrequests against the [main](https://github.com/radiantearth/stac-api-spec/tree/main) branch.\n\nCreating a Pull Request will show our PR template, which includes checkbox reminders for a number\nof things, including adding an entry the [CHANGELOG](CHANGELOG.md) and making the PR against the `main`\nbranch. \n\nAll pull requests should submit clean markdown, which is checked by the continuous integration\nsystem. Please use `npm run check` locally, as described in the [next section](#check-files), \nto ensure that the checks on the pull request succeed. If it does not then you can look at the\nmistakes online, which are the same as running `npm run check` locally would surface.\n\nAll pull requests that modify or create JSON schema files or examples should use\n[JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo. \n\nAll pull requests additionally require a review of two STAC core team members. Releases are cut\nfrom main and require 3 approvals.\n\n### Check files\n\nThe 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. \nTo install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).\nAny recent version of node/npm should work.\n\nIf using nvm, run `nvm install`.\n\nInstall the dependencies with npm:\n\n```bash\nnpm install\n```\n\nThen to do the check for markdown and examples you run:\n\n```bash\nnpm run check\n```\n\nThis will spit out the same texts that you see online, and you can then go and fix your markdown or examples.\n\nTo just check the markdown, run:\n\n```bash\nnpm run check-markdown\n```\n\nTo just validate the OpenAPI definitions, run:\n\n```bash\nnpm run check-openapi\n```\n\n### Working with the OpenAPI files\n\nThe definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is\ncontained within several YAML files in the various directories. These live in the same place as the markdown defining\nvarious parts of the specification. Currently we expect developers to be up to speed with\nOpenAPI and using their own tools to modify things. In the future we will provide tools to make it easier to work with.\nThere are html version of the OpenAPI files online at `https://api.stacspec.org/{version_number}` with `{version_number}` being the git tag or `dev`.\n\nOften, updating\nthe JSON Schema and OpenAPI files is one of the harder aspects of creating a change, so please, don't\nhesitate to ask for help in doing this!\n\n## Release Process\n\nTo release a new version of the STAC spec the following list of tasks must be done. \n\n- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github \nissue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not \nneed to be completed, but the core release team should all review the issues to make sure that the critical ones for the \nrelease have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no\nopen issues against the milestone.\n- **Check dependencies**: STAC relies on OGC API - Features and STAC Core specifications at its core, and will likely rely\non additional Features API extensions as well as OGC API - Commons. We aim to always reference the latest version of these,\nso before releasing we should check to make sure we are on the latest stable versions, and upgrade if it makes sense. We include\nthe latest stable STAC core spec version as a 'submodule', so before release we should update that to be the latest.\n- **Agreement from core team**: The core STAC API team should meet (on video or on gitter) and decided that the release is ready.\nThis should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep\nwith a coherent whole.\n- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense\nand there are no typos, errors, etc.\n- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements\nin the release. And anything in 'unreleased' section should move to the version of the spec to be released.\n- **Check Online API Docs**: Check to make sure the online API docs reflect the release at <https://api.stacspec.org/> \n(this step may go away once we are confident this works well, as this publishing is in flux)\n- **Release on Github**: The final step to create the release is to add a new 'release' on \n<https://github.com/radiantearth/stac-api-spec/releases>. This should use a tag like the others, with a 'v' prefix and then the \nrelease number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to \nthe full milestone of everything closed in the issue tracker.\n- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel\nto post / promote it.\n\n### Release Candidates\n\nBefore any release that has *major* changes (made as a judgement call by the core contributors)  there should be a 'release \ncandidate' to ensure the wider community of implementors can try it out\nand catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec\nversion is good, so this step is essential if there are major changes. The release should proceed as normal, but called\nvX.Y.Z-RC.1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations\nshould be updated to the new specification before there is a real release. And ideally an API client is also \nupdated. This provides the core sanity check. If there are changes or fixes to the spec or \nschemas needed from their feedback then make fixes and do RC2. If it is just fixes to the examples or tooling then no \nadditional RC is needed. After there is no more changes to spec or schemas then the release process should be done on `main`,\nwith no changes to the spec - just updating the version numbers.\n\n## Governance \n\nThe STAC API spec follows the same governance as the [core STAC spec](https://github.com/radiantearth/stac-spec/blob/master/process.md#governance).\n"
  },
  {
    "path": "LICENSE",
    "content": "                                 Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"{}\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright {yyyy} {name of copyright owner}\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n"
  },
  {
    "path": "PRINCIPLES.md",
    "content": "This project will be governed by a set of informal core principles. These principles are not set in stone,\nand indeed they should evolve in the same manner that all specifications worked on should - proposed and\nreviewed in pull requests, approved by consensus. The goal of the principles is to help avoid\n[bikeshedding](http://bikeshed.org/) - lay down some meta-rules so we can focus on creating useful\ncore geospatial standards.\n\n- **Creation and evolution of specs in Github**, using Open Source principles\n(please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you).\nThe collaboration facilities of Github should be used to their full extent. All proposed improvements and\nchanges should come in the form of pull requests, using code review functionality to discuss changes.\n\n- **Alignment with OGC standards** - The Open Geospatial Consortium publishes a large set of geospatial standards.\n  To the greatest extent possible, the STAC API should align with existing and in-progress OGC API standards. The\n  STAC API has a symbiotic relationship with these standards, as it seeks both to reuse their building blocks and\n  push them forward in a practical direction. Among the most important of these are:\n  - [OGC API - Common](https://ogcapi.ogc.org/common/)\n  - [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)\n  - [OGC API - Records](https://ogcapi.ogc.org/records/)\n  - [Common Query Language (CQL2)](https://docs.ogc.org/DRAFTS/21-065.html), formerly part of OGC \n    API - Features - Part 3: Filtering and the Common Query Language (CQL)\n\n- **Web API using JSON + HTTP at the core.** JSON has won over XML, and resource-centric over SOAP. We embrace them and\nare not considering legacy options. Forward looking protocols can be considered as extensions,\nbut the default specifications should be in JSON, following best web API practices. HTTP caching and\nerror codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,\nso it should also be core. As STAC APIs follow a resource-centric, hypermedia-driven model, a core principal \nis the use of HTTP Request Methods (\"verbs\") and the `Content-Type` header to drive behavior on resources (\"nouns\"). \n\n- **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible,\ndefining one core concept and refraining from describing lots of options. Additional options can be made\nas separate specifications that build on the core. But the core specs should be small and easily understandble,\nwith clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces.\nImplementors should not be forced to implement lots of options just for basic compliance - they should be\nable to pick and choose which pieces are relevant to the problems they are trying to solve.\n\n- **Specify in OpenAPI 3.0 (formerly known as Swagger) specification.** All web interfaces should be\nspecified in [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).\nThis enables generation of live documentation, client libraries and test engines, and makes the spec less ambiguous.\nAccompanying human readable specifications should be available in github and auto-built in to html.\n\n- **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice\nshould be considered with a developer audience. And specifications should be accessible to developers who do not\nhave geospatial background. A developer should not need to understand 'projections' to implement a simple feature\naccess service. But we should think through the spec extensions they could use in the future when their client asks\nfor data in a different projection.\n\n- **Working code required.** Proposed changes should be accompanied by working code\n(ideally with a link to an online service running the code). A reference implementation should be available\nonline to power the interactive documentation. Both core conformance classes and extensions follow the\n[Maturity Classification](README.md#maturity-classification) model.\n\n- **Design for scale.** The design should work great with more data than can be imagined right now.\nIdeally implementations are built with large test data sets to validate that they will work.\nEverything should be compatible with content distribution network (CDN) caching.\n\n## Resources\n\n- Open Source Principles - [Producing Open Source Software](http://producingoss.org) by Karl Fogel.\n- Best Practices JSON API Design - [JSON API](http://jsonapi.org/) best practices for making API's with JSON\n- Pragmatic REST - [Web API Design: Crafting interfaces that developers love](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf)\n- Open API Initiative - [OpenAPIs.org](https://openapis.org/)\n"
  },
  {
    "path": "README.md",
    "content": "<!--lint disable no-html-->\r\n<img src=\"https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png\" alt=\"stac-logo\" width=\"700\"/>\r\n\r\n# STAC API Foundation Specifications\r\n\r\n- [STAC API Foundation Specifications](#stac-api-foundation-specifications)\r\n  - [Releases (stable)](#releases-stable)\r\n  - [Development (unstable)](#development-unstable)\r\n  - [About](#about)\r\n  - [Stability Note](#stability-note)\r\n  - [Maturity Classification](#maturity-classification)\r\n  - [Communication](#communication)\r\n  - [In this repository](#in-this-repository)\r\n  - [Contributing](#contributing)\r\n\r\n## Releases (stable)\r\n\r\n- [v1.0.0](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0) (latest)\r\n- [v1.0.0-rc.4](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.4)\r\n- [v1.0.0-rc.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3)\r\n- [v1.0.0-rc.2](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2)\r\n- [v1.0.0-rc.1](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1)\r\n- [v1.0.0-beta.5](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5)\r\n- [v1.0.0-beta.4](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.4)\r\n- [v1.0.0-beta.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.3)\r\n- [v1.0.0-beta.2](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.2)\r\n- [v1.0.0-beta.1](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1)\r\n- [v0.9.0](https://github.com/radiantearth/stac-api-spec/tree/v0.9.0)\r\n\r\n## Development (unstable)\r\n\r\nThe [main](https://github.com/radiantearth/stac-api-spec/tree/main) branch in GitHub is\r\nused for active development and may be unstable. Implementers should reference one of\r\nthe release branches above for a stable version of the specification.\r\n**NOTE**: This means that if you are on github.com/radiantearth/stac-api-spec then you are looking at an unreleased,\r\nunstable version of the specification. Use the first listed link on releases to read the current released, stable version\r\nof the spec.\r\n\r\n## About\r\n\r\nThe SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried.\r\nA 'spatiotemporal asset' is any file that represents information about the Earth captured in a certain space and \r\ntime. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).\r\n\r\nA STAC API is a dynamic version of a SpatioTemporal Asset Catalog. This repository defines the three\r\nSTAC API foundation specifications -- [STAC API - Core](core/),\r\n[STAC API - Features](ogcapi-features/), and [STAC API - Item Search](item-search/) -- which can be composed \r\nwith [Extensions](extensions.md) to define a specific STAC API implementation.\r\n\r\nA STAC API can be used to retrieve STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), \r\n[Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), \r\nor STAC API [ItemCollection](fragments/itemcollection/README.md) objects from various endpoints.\r\nCatalog and Collection objects are JSON, while Item and ItemCollection objects are GeoJSON-compliant entities with foreign members.\r\nTypically, a Feature is used when returning a single Item object, and FeatureCollection when multiple Item objects (rather than a \r\nJSON array of Item entities).\r\n\r\nThe API can be implemented in compliance with the *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)* standard \r\n(OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API \r\nto search STAC catalogs, where the features returned are STAC [Item](stac-spec/item-spec/item-spec.md) objects, \r\nthat have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.\r\n\r\nThe specification for STAC API is provided as files that follow the [OpenAPI](http://openapis.org/) 3.0 specification, \r\nrendered online into HTML at <https://api.stacspec.org/v1.0.0>, in addition to human-readable documentation.  \r\n\r\n## Stability Note\r\n\r\nThis specification has evolved over the past couple years, and is used in production in a variety of deployments. It is \r\ncurrently in a 'beta' state, with no major changes anticipated.\r\nAs of v1.0.0, we remain fully aligned with\r\n[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) \r\nVersion 1.0, and we are working to stay aligned\r\nas the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API \r\nspecification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking change \r\nwill require the spec to go to 2.0.0.\r\n\r\n## Maturity Classification\r\n\r\nConformance classes and extensions are meant to evolve to maturity, and thus may be in different states\r\nin terms of stability and number of implementations. All extensions must include a \r\nmaturity classification, so that STAC API spec users can easily get a sense of how much they can count\r\non the extension. \r\n\r\n| Maturity Classification | Min Impl # | Description                                                                                                                                                | Stability                                                                                                 |\r\n| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |\r\n| 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.                         |\r\n| 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 |\r\n| 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.                     |\r\n| 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.                           |\r\n| 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.                                      |\r\n\r\nMaturity mostly comes through diverse implementations, so the minimum number of implementations\r\ncolumn is the main gating function for an extension to mature. But extension authors can also\r\nchoose to hold back the maturity advancement if they don't feel they are yet ready to commit to\r\nthe less breaking changes of the next level.\r\n\r\nA 'mature' classification level will likely be added once there are extensions that have been \r\nstable for over a year and are used in twenty or more implementations.\r\n\r\n## Communication\r\n\r\nFor any questions feel free to jump on our [gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby) or email \r\nour [google group](https://groups.google.com/forum/#!forum/stac-spec). The majority of communication about the evolution of \r\nthe specification takes place in the [issue tracker](https://github.com/radiantearth/stac-api-spec/issues) and in \r\n[pull requests](https://github.com/radiantearth/stac-api-spec/pulls).\r\n\r\n## In this repository\r\n\r\nThe **[Overview](overview.md)** document describes all the various parts of the STAC API and how they fit together.\r\n\r\n**STAC API - Core:**\r\nThe *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and \r\nretrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.\r\n\r\n**STAC API - Features:**\r\nThe *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API - \r\nFeatures](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of\r\neach STAC collection. It also includes extensions that can be used to further enhance OAFeat.\r\n\r\n**STAC API - Item Search Specification:**\r\nThe *[item-search](item-search)* folder contains the Item Search specification, which enables \r\ncross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions. \r\n\r\n**Extensions:**\r\nThe *[extensions](extensions.md) document* describes how STAC adds new functionality\r\nthrough extensions. The official list of STAC API Extensions\r\nis maintained at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).\r\n\r\n**Fragments:**\r\nThe *[fragments/](fragments/)* folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI \r\nschemas and parameters for behavior like sorting and filtering. Most all of them are compatible with \r\nOGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations.\r\nOpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.\r\n\r\n**STAC Specification:** This repository includes a '[sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules)', which\r\nis a copy of the [STAC specification](stac-spec/) tagged at the latest stable version.\r\nSub-modules aren't checked out by default, so to get the directory populated\r\neither use `git submodule update --init --recursive` if you've already cloned it,\r\nor clone from the start with `git clone --recursive git@github.com:radiantearth/stac-api-spec.git`. \r\n\r\n**Implementation Recommendations:** Recommendations for implementing a STAC API may be found [here](implementation.md). \r\nThese are mostly concerns that apply to an entire API implementation and are not part of the specification itself.\r\n\r\n## Contributing\r\n\r\nAnyone building software that catalogs imagery or other geospatial assets is welcome to collaborate.\r\nBeforehand, please review our [guidelines for contributions and development process](CONTRIBUTING.md).\r\n"
  },
  {
    "path": "build/index.html",
    "content": "<!DOCTYPE html>\n<html>\n\n<head>\n    <title>STAC API</title>\n    <!-- needed for adaptive design -->\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <link href=\"https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700\" rel=\"stylesheet\">\n</head>\n\n<body>\n    <h1>STAC API</h1>\n    <h2>Conformance Classes</h2>\n    <ul>\n        <li><a href=\"core/\">STAC API - Core</a></li>\n        <li><a href=\"item-search/\">STAC API - Item Search</a></li>\n        <li><a href=\"ogcapi-features/\">STAC API - Features</a></li>\n        <li><a href=\"collections/\">STAC API - Collections</a></li>\n    </ul>\n</body>\n\n</html>\n"
  },
  {
    "path": "build/redoc_index.html",
    "content": "<!DOCTYPE html>\n<html>\n\n<head>\n  <title>STAC API</title>\n  <!-- needed for adaptive design -->\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <link href=\"https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700\" rel=\"stylesheet\">\n\n  <!--\n    ReDoc doesn't change outer page styles\n    -->\n  <style>\n    body {\n      margin: 0;\n      padding: 0;\n    }\n  </style>\n</head>\n\n<body>\n  <redoc \n    spec-url='openapi.yaml'\n    expandResponses='200,201,202,203,204'\n    pathInMiddlePanel='true'\n    hideDownloadButton='true'\n  ></redoc>\n  <script src=\"https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js\"> </script>\n</body>\n\n</html>\n"
  },
  {
    "path": "build/swagger-config.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: STAC API - Complete\n  version: 1.0.0-rc.2\napis:\n  - url: 'build/core/openapi.yaml'\n    paths:\n      exclude:\n        - \"^\\/$\"\n  - url: 'build/item-search/openapi.yaml'\n  - url: 'build/ogcapi-features/openapi.yaml'\n  - url: 'build/ogcapi-features/extensions/version/openapi.yaml'\n  - url: 'build/ogcapi-features/extensions/transaction/openapi.yaml'\n"
  },
  {
    "path": "core/README.md",
    "content": "# STAC API - Core Specification\n\n- [STAC API - Core Specification](#stac-api---core-specification)\n  - [Summary](#summary)\n  - [Overview](#overview)\n  - [Core](#core)\n  - [Link Relations](#link-relations)\n  - [Endpoints](#endpoints)\n  - [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core)\n  - [Extensions](#extensions)\n\n## Summary\n\n- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/core)),\n- **Conformance URIs:**\n  - <https://api.stacspec.org/v1.0.0/core>\n- **[Maturity Classification](../README.md#maturity-classification):** Candidate\n- **Dependencies**: None\n  and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.\n\n## Overview\n\nAll STAC API implementations must implement the *STAC API - Core* conformance class\n<https://api.stacspec.org/v1.0.0/core>. This requires a server to return from a root endpoint a valid\n[STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) \"landing page\" that also includes a `conformsTo`\nattribute with a string array value. Any API implementing this is considered a minimal, valid STAC API.\n\n## Core\n\nThe root of a STAC API is the Landing Page, which is a STAC Catalog object with additional fields.\nThis resource is the starting point to determine what behaviors\nthe API supports via the `conformsTo` array and the URIs of resources via link relations.\nSupport for this type of behavior in a web API is known as\n[Hypermedia as the Engine of Application State (HATEOAS)](https://en.wikipedia.org/wiki/HATEOAS).\nA hypermedia-driven web API provides a robust, consistent, and flexible mechanism for interacting with remote resources.\nSTAC API relies heavily on hypermedia for API resource discovery and navigation.\n\nIn a STAC API, the root endpoint (Landing Page) has the following characteristics:\n\n- The returned JSON is a [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md), and provides any number of 'child' links\n  to navigate to additional [Catalog](../stac-spec/catalog-spec/catalog-spec.md),\n  [Collection](../stac-spec/collection-spec/README.md), and [Item](../stac-spec/item-spec/README.md) objects.\n- The `links` attribute is part of a STAC Catalog, and provides a list of relations to API endpoints. Some of these endpoints can\n  exist on any path (e.g., sub-catalogs) and some have a specified path (e.g., `/search`),\n  so the client must inspect the `rel` (relationship) to understand what capabilities are offered at each location.\n- The `conformsTo` section provides the capabilities of this service. This is the field\n  that indicates to clients that this is a STAC API and how to access conformance classes, including this\n  one. The relevant conformance URIs are listed in each part of the API specification. If a conformance URI is listed then\n  the service must implement all of the required capabilities.\n\nNote the `conformsTo` array follows the same structure of the OGC API - Features [declaration of conformance\nclasses](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes), except it is part of the\nlanding page instead of in the JSON response from the `/conformance` endpoint. This is different from how the OGC API advertises\nconformance, as STAC feels it is important for clients\nto understand conformance from a single request to the landing page. Implementers who implement the *OGC API - Features* and/or\n[STAC API - Features](../ogcapi-features/README.md) conformance classes must also implement the `/conformance` endpoint.\n\nThe scope of the conformance classes declared in the `conformsTo` field and the `/conformance` endpoint are limited\nto the STAC API Catalog that declares them. A STAC API Catalog may link to sub-catalogs within it via `child` links\nthat declare different conformance classes. This is useful when an entire catalog cannot be searched against to\nsupport the *STAC API - Item Search* conformance class, perhaps because it uses multiple databases to store items,\nbut sub-catalogs whose items are all in one database can support search.\n\n## Link Relations\n\nThe STAC definition of Link does not require the `type` field,\nbut it is **STRONGLY RECOMMENDED** that this field exists.\nIf the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.\n\nThe following Link relations are defined for the Landing Page (root).\n\n| **rel**        | **href**    | **Media Type**       | **From**        | **Description**                                                                                                                    |\n| -------------- | ----------- | -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `root`         | `/`         | application/json     | STAC API - Core | **REQUIRED** The root URI                                                                                                          |\n| `self`         | `/`         | application/json     | OAFeat          | **REQUIRED** Self reference, same as root URI                                                                                      |\n| `service-desc` | `/api`      | various              | OAFeat          | **REQUIRED** The service description in a machine-readable format                                                                  |\n| `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. |\n| `child`        | various     | application/json     | STAC API - Core | The child STAC Catalogs & Collections.                                                                                             |\n| `item`         | various     | application/geo+json | STAC API - Core | The child STAC Items.                                                                                                              |\n\nThe path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be\nOpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML),\n`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1`\n(3.1 JSON).\n\nA `service-doc` endpoint is recommended, but not required. This commonly returns an HTML\npage, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API\n, but any format is allowed. The Link `type` field should correspond to whatever format or formats are\nsupported by this endpoint, e.g., `text/html`.\n\nAdditionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These\nrelations form a directed graph that enables traversal from a root catalog or collection to items.\n\nWhile it is valid to have `item` links from the landing page, most STAC API implementations\nserve large numbers of features, so they will typically use several layers of intermediate `child` links to sub-catalogs and collections before\ngetting to Item objects.  These relations form a directed graph\nof Catalogs and Collections, where interior nodes contain `child` relations, and the penultimate nodes will be\nCatalogs with `item` relations to individual Items as leaf nodes.\n\n`child` link relations may point to another STAC Catalog that *also* acts as a STAC API root, which can support\nsearch over only a sub-catalog. This is useful for very large or federated catalogs that cannot support searching\nover the entire catalog, but can support searching over individual sub-catalogs within it.\n\nNote that there is a different link relation `items` (plural)\nused by the [STAC API - Features](../ogcapi-features/README.md) conformance class that links from a collection resource\n(at the `/collections/{collectionId}` endpoint) to the items in\nthat collection (at the `/collections/{collectionId}/items` endpoint). Both of these endpoints are\n[derived from OGC API - Features](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_).\n\n## Endpoints\n\nThis conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.\n\nThese endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml).\n\n| **Endpoint** | **Media Type**   | **Returns**                                    | **Description**                                                                                                                                                    |\n| ------------ | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `/`          | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities                                                                                                                            |\n| `/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. |\n\nThe service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1\nwith media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON),\nor `application/vnd.oai.openapi+json;version=3.1` (3.1 JSON). Whichever format or formats are used, the link\nwith relation `service-desc` must have a `type` field that matches an `Accept` header value to which the service\nresponds, and the `Content-Type` header in the response should contain the same media type. If the OpenAPI 3.0\nformat is used, the conformance class `http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30` should be\nadvertised. All service descriptions provided as part of the STAC API spec use OpenAPI 3.0 YAML format, and can\neasily be used to return either YAML or JSON from this endpoint. OAFeat does not currently define a conformance\nclass for OpenAPI 3.1, but may in the future.\n\n## Example Landing Page for STAC API - Core\n\nThis JSON is what would be expected from an API that only implements *STAC API - Core*. It is a valid STAC Catalog\nwith additional Links and a `conformsTo` attribute. In practice,\nmost APIs will also implement other conformance classes, and those will be reflected in the `links` and\n`conformsTo` attribute.  A more typical Landing Page example is in\nthe [overview](../overview.md#example-landing-page) document.\n\nThis particular catalog provides both the ability to browse down to child Catalog objects through its\n`child` links, and also provides the search endpoint to be able to search across items in its collections. Note\nthat some of those links are not required and other servers may provide\ndifferent conformance classes and a different set of links.\n\n```json\n{\n    \"stac_version\": \"1.0.0\",\n    \"id\": \"example-stac\",\n    \"title\": \"A simple STAC API Example\",\n    \"description\": \"This Catalog aims to demonstrate a simple landing page\",\n    \"type\": \"Catalog\",\n    \"conformsTo\" : [\n        \"https://api.stacspec.org/v1.0.0/core\"\n    ],\n    \"links\": [\n        {\n            \"rel\": \"self\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"root\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"service-desc\",\n            \"type\": \"application/vnd.oai.openapi+json;version=3.0\",\n            \"href\": \"https://stac-api.example.com/api\"\n        },\n        {\n            \"rel\": \"service-doc\",\n            \"type\": \"text/html\",\n            \"href\": \"https://stac-api.example.com/api.html\"\n        },\n        {\n            \"rel\": \"child\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/catalogs/sentinel-2\"\n        },\n        {\n            \"rel\": \"child\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/catalogs/landsat-8\"\n        }\n    ]\n}\n```\n\n## Extensions\n\nSTAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).\n"
  },
  {
    "path": "core/commons.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: The SpatioTemporal Asset Catalog API - Commons\n  description: This is the OpenAPI version of the core STAC spec JSON Schemas.\n  version: v1.0.0\npaths: {}\ncomponents:\n  responses:\n    Error:\n      description: An error occurred.\n      content:\n        application/json:\n          schema:\n            $ref: \"#/components/schemas/exception\"\n  schemas:\n    exception:\n      type: object\n      description: |-\n        Information about the exception: an error code plus an optional description.\n      required:\n        - code\n      properties:\n        code:\n          type: string\n        description:\n          type: string\n    conformanceClasses:\n      type: object\n      required:\n        - conformsTo\n      properties:\n        conformsTo:\n          description: >-\n            A list of all conformance classes implemented by the server.\n            In addition to the STAC-specific conformance classes, all OGC-related\n            conformance classes listed at `GET /conformance` must be listed here.\n            This entry should mirror what `GET /conformance` returns, if implemented.\n          type: array\n          items:\n            type: string\n    catalog:\n      type: object\n      required:\n        - stac_version\n        - type\n        - id\n        - description\n        - links\n      properties:\n        stac_version:\n          $ref: \"#/components/schemas/stac_version\"\n        stac_extensions:\n          $ref: \"#/components/schemas/stac_extensions\"\n        type:\n          type: string\n          enum:\n            - Catalog\n        id:\n          type: string\n        title:\n          type: string\n        description:\n          type: string\n        links:\n          $ref: \"#/components/schemas/links\"\n    collection:\n      type: object\n      required:\n        - stac_version\n        - type\n        - id\n        - description\n        - license\n        - extent\n        - links\n      properties:\n        stac_version:\n          $ref: \"#/components/schemas/stac_version\"\n        stac_extensions:\n          $ref: \"#/components/schemas/stac_extensions\"\n        type:\n          type: string\n          enum:\n            - Collection\n        id:\n          description: identifier of the collection used, for example, in URIs\n          type: string\n        title:\n          description: human readable title of the collection\n          type: string\n        description:\n          type: string\n          description: >-\n            Detailed multi-line description to fully explain the catalog or\n            collection.\n\n            [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for\n            rich text representation.\n        keywords:\n          type: array\n          description: List of keywords describing the collection.\n          items:\n            type: string\n        license:\n          $ref: \"#/components/schemas/license\"\n        extent:\n          $ref: \"#/components/schemas/extent\"\n        providers:\n          $ref: \"#/components/schemas/providers\"\n        links:\n          $ref: \"#/components/schemas/links\"\n        summaries:\n          description: |-\n            Summaries are either a unique set of all available values *or*\n            statistics. Statistics by default only specify the range (minimum\n            and maximum values), but can optionally be accompanied by additional\n            statistical values. The range can specify the potential range of\n            values, but it is recommended to be as precise as possible. The set\n            of values must contain at least one element and it is strongly\n            recommended to list all values. It is recommended to list as many\n            properties as reasonable so that consumers get a full overview of\n            the Collection. Properties that are covered by the Collection\n            specification (e.g. `providers` and `license`) may not be repeated\n            in the summaries.\n          type: object\n          additionalProperties:\n            oneOf:\n              - type: array\n                title: Set of values\n                items:\n                  description: A value of any type.\n              - type: object\n                title: Statistics\n                description: |-\n                  By default, only ranges with a minimum and a maximum value can\n                  be specified. Ranges can be specified for ordinal values only,\n                  which means they need to have a rank order. Therefore, ranges\n                  can only be specified for numbers and some special types of\n                  strings. Examples: grades (A to F), dates or times.\n                  Implementors are free to add other derived statistical values\n                  to the object, for example `mean` or `stddev`.\n                required:\n                  - min\n                  - max\n                properties:\n                  min:\n                    anyOf:\n                      - type: string\n                      - type: number\n                  max:\n                    anyOf:\n                      - type: string\n                      - type: number\n      example:\n        stac_version: \"1.0.0\"\n        stac_extensions: []\n        type: Collection\n        id: Sentinel-2\n        title: \"Sentinel-2 MSI: MultiSpectral Instrument, Level-1C\"\n        description: |\n          Sentinel-2 is a wide-swath, high-resolution, multi-spectral\n          imaging mission...\n        license: proprietary\n        keywords:\n          - copernicus\n          - esa\n          - eu\n          - msi\n          - radiance\n          - sentinel\n        providers:\n          - name: ESA\n            roles:\n              - producer\n              - licensor\n            url: \"https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi\"\n        extent:\n          spatial:\n            bbox:\n              - - -180\n                - -56\n                - 180\n                - 83\n          temporal:\n            interval:\n              - - \"2015-06-23T00:00:00Z\"\n                - \"2019-07-10T13:44:56Z\"\n        summaries:\n          datetime:\n            min: \"2015-06-23T00:00:00Z\"\n            max: \"2019-07-10T13:44:56Z\"\n          \"sci:citation\":\n            - \"Copernicus Sentinel data [Year]\"\n          \"eo:gsd\":\n            - 10\n            - 30\n            - 60\n          \"platform\":\n            - sentinel-2a\n            - sentinel-2b\n          \"constellation\":\n            - sentinel-2\n          \"instruments\":\n            - msi\n          \"view:off_nadir\":\n            min: 0\n            max: 100\n          \"view:sun_elevation\":\n            min: 6.78\n            max: 89.9\n          \"eo:bands\":\n            - - name: B1\n                common_name: coastal\n                center_wavelength: 4.439\n              - name: B2\n                common_name: blue\n                center_wavelength: 4.966\n              - name: B3\n                common_name: green\n                center_wavelength: 5.6\n              - name: B4\n                common_name: red\n                center_wavelength: 6.645\n              - name: B5\n                center_wavelength: 7.039\n              - name: B6\n                center_wavelength: 7.402\n              - name: B7\n                center_wavelength: 7.825\n              - name: B8\n                common_name: nir\n                center_wavelength: 8.351\n              - name: B8A\n                center_wavelength: 8.648\n              - name: B9\n                center_wavelength: 9.45\n              - name: B10\n                center_wavelength: 1.3735\n              - name: B11\n                common_name: swir16\n                center_wavelength: 1.6137\n              - name: B12\n                common_name: swir22\n                center_wavelength: 2.2024\n        links:\n          - rel: self\n            href: \"http://cool-sat.com/collections/Sentinel-2\"\n            type: application/json\n          - rel: root\n            href: \"http://cool-sat.com/collections\"\n            type: application/json\n          - rel: license\n            href: \"https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf\"\n            title: Legal notice on the use of Copernicus Sentinel Data and Service Information\n            type: application/pdf\n    extent:\n      type: object\n      description: |-\n        The extent of the features in the collection. In the Core only spatial and temporal\n        extents are specified. Extensions may add additional members to represent other\n        extents, for example, thermal or pressure ranges.\n\n        The first item in the array describes the overall extent of\n        the data. All subsequent items describe more precise extents, \n        e.g., to identify clusters of data.\n        Clients only interested in the overall extent will only need to\n        access the first item in each array.\n      required:\n        - spatial\n        - temporal\n      properties:\n        spatial:\n          description: |-\n            The spatial extent of the features in the collection.\n          type: object\n          required:\n            - bbox\n          properties:\n            bbox:\n              description: |-\n                One or more bounding boxes that describe the spatial extent of the dataset.\n\n                The first bounding box describes the overall spatial\n                extent of the data. All subsequent bounding boxes describe \n                more precise bounding boxes, e.g., to identify clusters of data.\n                Clients only interested in the overall spatial extent will\n                only need to access the first item in each array.\n              type: array\n              minItems: 1\n              items:\n                description: |-\n                  Each bounding box is provided as four or six numbers, depending on\n                  whether the coordinate reference system includes a vertical axis\n                  (height or depth):\n\n                  * Lower left corner, coordinate axis 1\n                  * Lower left corner, coordinate axis 2\n                  * Minimum value, coordinate axis 3 (optional)\n                  * Upper right corner, coordinate axis 1\n                  * Upper right corner, coordinate axis 2\n                  * Maximum value, coordinate axis 3 (optional)\n\n                  The coordinate reference system of the values is WGS 84 longitude/latitude\n                  (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate\n                  reference system is specified in `crs`.\n\n                  For WGS 84 longitude/latitude the values are in most cases the sequence of\n                  minimum longitude, minimum latitude, maximum longitude and maximum latitude.\n                  However, in cases where the box spans the antimeridian the first value\n                  (west-most box edge) is larger than the third value (east-most box edge).\n\n                  If the vertical axis is included, the third and the sixth number are\n                  the bottom and the top of the 3-dimensional bounding box.\n\n                  If a feature has multiple spatial geometry properties, it is the decision of the\n                  server whether only a single spatial geometry property is used to determine\n                  the extent or all relevant geometries.\n                type: array\n                minItems: 4\n                maxItems: 6\n                items:\n                  type: number\n                example:\n                  - -180\n                  - -90\n                  - 180\n                  - 90\n            crs:\n              description: |-\n                Coordinate reference system of the coordinates in the spatial extent\n                (property `bbox`). The default reference system is WGS 84 longitude/latitude.\n                In the Core this is the only supported coordinate reference system.\n                Extensions may support additional coordinate reference systems and add\n                additional enum values.\n              type: string\n              enum:\n                - \"http://www.opengis.net/def/crs/OGC/1.3/CRS84\"\n              default: \"http://www.opengis.net/def/crs/OGC/1.3/CRS84\"\n        temporal:\n          description: |-\n            The temporal extent of the features in the collection.\n          type: object\n          required:\n            - interval\n          properties:\n            interval:\n              description: |-\n                One or more time intervals that describe the temporal extent of the dataset.\n\n                The first time interval describes the overall\n                temporal extent of the data. All subsequent time intervals describe \n                more precise time intervals, e.g., to identify clusters of data.\n                Clients only interested in the overall extent will only need\n                to access the first item in each array.\n              type: array\n              minItems: 1\n              items:\n                description: |-\n                  Begin and end times of the time interval. The timestamps\n                  are in the coordinate reference system specified in `trs`. By default\n                  this is the Gregorian calendar.\n\n                  The value `null` is supported and indicates an open time interval.\n                type: array\n                minItems: 2\n                maxItems: 2\n                items:\n                  type: string\n                  format: date-time\n                  nullable: true\n                example:\n                  - \"2011-11-11T12:22:11Z\"\n                  - null\n            trs:\n              description: |-\n                Coordinate reference system of the coordinates in the temporal extent\n                (property `interval`). The default reference system is the Gregorian calendar.\n                In the Core this is the only supported temporal reference system.\n                Extensions may support additional temporal reference systems and add\n                additional enum values.\n              type: string\n              enum:\n                - \"http://www.opengis.net/def/uom/ISO-8601/0/Gregorian\"\n              default: \"http://www.opengis.net/def/uom/ISO-8601/0/Gregorian\"\n    links:\n      type: array\n      items:\n        $ref: \"#/components/schemas/link\"\n    link:\n      title: Link\n      type: object\n      required:\n        - href\n        - rel\n      properties:\n        href:\n          type: string\n          format: uri\n          description: The location of the resource\n        rel:\n          type: string\n          description: Relation type of the link\n        type:\n          type: string\n          description: The media type of the resource\n        title:\n          type: string\n          description: Title of the resource\n        method:\n          type: string\n          enum:\n            - GET\n            - POST\n          default: GET\n          description: Specifies the HTTP method that the resource expects\n        headers:\n          type: object\n          description: Object key values pairs they map to headers\n          example:\n            Accept: application/json\n        body:\n          type: object\n          description: For POST requests, the resource can specify the HTTP body as a JSON object.\n        merge:\n          type: boolean\n          default: false\n          description: |-\n            This is only valid when the server is responding to POST request.\n\n            If merge is true, the client is expected to merge the body value\n            into the current request body before following the link.\n            This avoids passing large post bodies back and forth when following\n            links, particularly for navigating pages through the `POST /search`\n            endpoint.\n\n            NOTE: To support form encoding it is expected that a client be able\n            to merge in the key value pairs specified as JSON\n            `{\"next\": \"token\"}` will become `&next=token`.\n    license:\n      type: string\n      description: |-\n        License(s) of the data as a SPDX\n        [License identifier](https://spdx.org/licenses/). Alternatively, use\n        `proprietary` if the license is not on the SPDX license list or\n        `various` if multiple licenses apply. In these two cases links to the\n        license texts SHOULD be added, see the `license` link relation type.\n\n        Non-SPDX licenses SHOULD add a link to the license text with the\n        `license` relation in the links section. The license text MUST NOT be\n        provided as a value of this field. If there is no public license URL\n        available, it is RECOMMENDED to host the license text and\n        link to it.\n      example: Apache-2.0\n    providers:\n      type: array\n      description: >-\n        A list of providers, which may include all organizations capturing or\n        processing the data or the hosting provider. Providers should be listed\n        in chronological order with the most recent provider being the last\n        element of the list.\n      items:\n        type: object\n        title: Provider\n        required:\n          - name\n        properties:\n          name:\n            description: The name of the organization or the individual.\n            type: string\n          description:\n            description: >-\n              Multi-line description to add further provider information such as\n              processing details for processors and producers, hosting details\n              for hosts or basic contact information.\n\n\n              [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for\n              rich text representation.\n            type: string\n          roles:\n            description: |-\n              Roles of the provider.\n\n              The provider's role(s) can be one or more of the following\n              elements:\n\n              * licensor: The organization that is licensing the dataset under\n                the license specified in the collection's license field.\n              * producer: The producer of the data is the provider that\n                initially captured and processed the source data, e.g. ESA for\n                Sentinel-2 data.\n              * processor: A processor is any provider who processed data to a\n                derived product.\n              * host: The host is the actual provider offering the data on their\n                storage. There should be no more than one host, specified as last\n                element of the list.\n            type: array\n            items:\n              type: string\n              enum:\n                - producer\n                - licensor\n                - processor\n                - host\n          url:\n            description: >-\n              Homepage on which the provider describes the dataset and publishes\n              contact information.\n            type: string\n            format: url\n    bbox:\n      description: |-\n        Only features that have a geometry that intersects the bounding box are\n        selected. The bounding box is provided as four or six numbers,\n        depending on whether the coordinate reference system includes a\n        vertical axis (elevation or depth):\n\n        * Lower left corner, coordinate axis 1\n        * Lower left corner, coordinate axis 2  \n        * Lower left corner, coordinate axis 3 (optional) \n        * Upper right corner, coordinate axis 1 \n        * Upper right corner, coordinate axis 2 \n        * Upper right corner, coordinate axis 3 (optional)\n\n        The coordinate reference system of the values is WGS84\n        longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).\n\n        For WGS84 longitude/latitude the values are in most cases the sequence\n        of minimum longitude, minimum latitude, maximum longitude and maximum\n        latitude. However, in cases where the box spans the antimeridian the\n        first value (west-most box edge) is larger than the third value\n        (east-most box edge).\n\n        If a feature has multiple spatial geometry properties, it is the\n        decision of the server whether only a single spatial geometry property\n        is used to determine the extent or all relevant geometries.\n\n        Example: The bounding box of the New Zealand Exclusive Economic Zone in\n        WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be\n        represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as\n        `bbox=160.6,-55.95,-170,-25.89`.\n      type: array\n      minItems: 4\n      maxItems: 6\n      items:\n        type: number\n      example:\n        - -110\n        - 39.5\n        - -105\n        - 40.5\n    datetime:\n      type: string\n      format: date-time\n      nullable: true\n      description: |-\n        The searchable date and time of the assets, in UTC.\n        It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n        `null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.\n      example: \"2018-02-12T00:00:00Z\"\n    stac_version:\n      title: STAC version\n      type: string\n      example: 1.0.0\n    stac_extensions:\n      title: STAC extensions\n      type: array\n      uniqueItems: true\n      items:\n        anyOf:\n          - title: Reference to a JSON Schema\n            type: string\n            format: uri\n          - title: Reference to a core extension\n            type: string\n    item:\n      description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity\n      type: object\n      required:\n        - stac_version\n        - id\n        - type\n        - geometry\n        - bbox\n        - links\n        - properties\n        - assets\n      properties:\n        stac_version:\n          $ref: \"#/components/schemas/stac_version\"\n        stac_extensions:\n          $ref: \"#/components/schemas/stac_extensions\"\n        id:\n          $ref: \"#/components/schemas/itemId\"\n        bbox:\n          $ref: \"#/components/schemas/bbox\"\n        geometry:\n          $ref: \"#/components/schemas/geometryGeoJSON\"\n        type:\n          $ref: \"#/components/schemas/itemType\"\n        links:\n          $ref: \"#/components/schemas/links\"\n        properties:\n          $ref: \"#/components/schemas/properties\"\n        assets:\n          $ref: \"#/components/schemas/assets\"\n      example:\n        stac_version: \"1.0.0\"\n        stac_extensions:\n          - \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\"\n          - \"https://stac-extensions.github.io/view/v1.0.0/schema.json\"\n          - \"https://example.com/cs-extension/1.0/schema.json\"\n        type: Feature\n        id: CS3-20160503_132131_05\n        bbox:\n          - -122.59750209\n          - 37.48803556\n          - -122.2880486\n          - 37.613537207\n        geometry:\n          type: Polygon\n          coordinates:\n            - - - -122.308150179\n                - 37.488035566\n              - - -122.597502109\n                - 37.538869539\n              - - -122.576687533\n                - 37.613537207\n              - - -122.2880486\n                - 37.562818007\n              - - -122.308150179\n                - 37.488035566\n        properties:\n          datetime: \"2016-05-03T13:22:30.040Z\"\n          title: A CS3 item\n          license: PDDL-1.0\n          providers:\n            - name: CoolSat\n              roles:\n                - producer\n                - licensor\n              url: \"https://cool-sat.com/\"\n          \"view:sun_azimuth\": 168.7\n          \"eo:cloud_cover\": 0.12\n          \"view:off_nadir\": 1.4\n          \"platform\": coolsat2\n          \"instruments\":\n            - cool_sensor_v1\n          \"eo:bands\": []\n          \"view:sun_elevation\": 33.4\n          \"eo:gsd\": 0.512\n        collection: CS3\n        links:\n          - rel: self\n            href: \"http://cool-sat.com/collections/CS3/items/20160503_132130_04\"\n            type: application/geo+json\n          - rel: root\n            href: \"http://cool-sat.com/collections\"\n            type: application/json\n          - rel: parent\n            href: \"http://cool-sat.com/collections/CS3\"\n            type: application/json\n          - rel: collection\n            href: \"http://cool-sat.com/collections/CS3\"\n            type: application/json\n        assets:\n          analytic:\n            href: \"http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif\"\n            title: 4-Band Analytic\n            type: image/tiff; application=geotiff; profile=cloud-optimized\n          thumbnail:\n            href: \"http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png\"\n            title: Thumbnail\n            type: image/png\n    itemId:\n      type: string\n      description: Provider identifier, a unique ID.\n    itemType:\n      type: string\n      description: The GeoJSON type\n      enum:\n        - Feature\n    properties:\n      type: object\n      required:\n        - datetime\n      description: provides the core metadata fields plus extensions\n      properties:\n        datetime:\n          $ref: \"#/components/schemas/datetime\"\n      additionalProperties:\n        description: Any additional properties added in via Item specification or extensions.\n    assets:\n      type: object\n      additionalProperties:\n        type: object\n        required:\n          - href\n        properties:\n          href:\n            type: string\n            format: url\n            description: Link to the asset object\n            example: >-\n              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png\n          title:\n            type: string\n            description: Displayed title\n            example: Thumbnail\n          description:\n            type: string\n            description: >-\n              Multi-line description to explain the asset.\n\n\n              [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for\n              rich text representation.\n            example: Small 256x256px PNG thumbnail for a preview.\n          type:\n            type: string\n            description: Media type of the asset\n            example: image/png\n          roles:\n            type: array\n            items:\n              type: string\n            description: Purposes of the asset\n            example:\n              - thumbnail\n    geometryGeoJSON:\n      oneOf:\n        - $ref: \"#/components/schemas/pointGeoJSON\"\n        - $ref: \"#/components/schemas/multipointGeoJSON\"\n        - $ref: \"#/components/schemas/linestringGeoJSON\"\n        - $ref: \"#/components/schemas/multilinestringGeoJSON\"\n        - $ref: \"#/components/schemas/polygonGeoJSON\"\n        - $ref: \"#/components/schemas/multipolygonGeoJSON\"\n        - $ref: \"#/components/schemas/geometrycollectionGeoJSON\"\n    geometrycollectionGeoJSON:\n      type: object\n      required:\n        - type\n        - geometries\n      properties:\n        type:\n          type: string\n          enum:\n            - GeometryCollection\n        geometries:\n          type: array\n          items:\n            $ref: \"#/components/schemas/geometryGeoJSON\"\n    linestringGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - LineString\n        coordinates:\n          type: array\n          minItems: 2\n          items:\n            type: array\n            minItems: 2\n            items:\n              type: number\n    multilinestringGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - MultiLineString\n        coordinates:\n          type: array\n          items:\n            type: array\n            minItems: 2\n            items:\n              type: array\n              minItems: 2\n              items:\n                type: number\n    multipointGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - MultiPoint\n        coordinates:\n          type: array\n          items:\n            type: array\n            minItems: 2\n            items:\n              type: number\n    multipolygonGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - MultiPolygon\n        coordinates:\n          type: array\n          items:\n            type: array\n            items:\n              type: array\n              minItems: 4\n              items:\n                type: array\n                minItems: 2\n                items:\n                  type: number\n    pointGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - Point\n        coordinates:\n          type: array\n          minItems: 2\n          items:\n            type: number\n    polygonGeoJSON:\n      type: object\n      required:\n        - type\n        - coordinates\n      properties:\n        type:\n          type: string\n          enum:\n            - Polygon\n        coordinates:\n          type: array\n          items:\n            type: array\n            minItems: 4\n            items:\n              type: array\n              minItems: 2\n              items:\n                type: number\n    featureCollectionGeoJSON:\n      type: object\n      required:\n        - type\n        - features\n      properties:\n        type:\n          type: string\n          enum:\n            - FeatureCollection\n        features:\n          type: array\n          items:\n            $ref: \"#/components/schemas/featureGeoJSON\"\n    featureGeoJSON:\n      type: object\n      required:\n        - type\n        - geometry\n        - properties\n      properties:\n        type:\n          type: string\n          enum:\n            - Feature\n        geometry:\n          $ref: \"#/components/schemas/geometryGeoJSON\"\n        properties:\n          type: object\n          nullable: true\n"
  },
  {
    "path": "core/openapi.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: STAC API - Core\n  version: v1.0.0\n  description: >-\n    This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core\n    specification. Any service that implements this endpoint to allow discovery of\n    spatiotemporal assets can be considered a STAC API.\n  contact:\n    name: STAC Specification\n    url: \"http://stacspec.org\"\n  license:\n    name: Apache License 2.0\n    url: \"http://www.apache.org/licenses/LICENSE-2.0\"\n  x-conformance-classes: [\"https://api.stacspec.org/v1.0.0/core\"]\ntags:\n  - name: Core\n    description: essential characteristics of a STAC API\npaths:\n  \"/\":\n    get:\n      tags:\n        - Core\n      summary: landing page\n      description: |-\n        Returns the root STAC Catalog or STAC Collection that is the entry point\n        for users to browse with STAC Browser or for search engines to crawl.\n        This can either return a single STAC Collection or more commonly a STAC\n        catalog.\n\n        The landing page provides links to the\n        API definition (link relations `service-desc` and `service-doc`)\n        and the STAC records such as collections/catalogs (link relation `child`)\n        or items (link relation `item`).\n\n        Extensions may add additional links with new relation types.\n      operationId: getLandingPage\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/LandingPage\"\n        \"4XX\":\n          $ref: \"commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"commons.yaml#/components/responses/Error\"\ncomponents:\n  schemas:\n    landingPage:\n      allOf:\n        - $ref: \"commons.yaml#/components/schemas/catalog\"\n        - $ref: \"commons.yaml#/components/schemas/conformanceClasses\"\n  responses:\n    LandingPage:\n      description: |-\n        The landing page provides links to the API definition\n        (link relations `service-desc` and `service-doc`).\n      content:\n        application/json:\n          schema:\n            $ref: \"#/components/schemas/landingPage\"\n          example:\n            type: Catalog\n            stac_version: \"1.0.0\"\n            id: sentinel\n            title: Copernicus Sentinel Imagery\n            description: Catalog of Copernicus Sentinel 1 and 2 imagery.\n            conformsTo:\n              - \"https://api.stacspec.org/v1.0.0/core\"\n            links:\n              - href: \"http://data.example.org/\"\n                rel: self\n                type: application/json\n                title: this document\n              - href: \"http://data.example.org/api\"\n                rel: service-desc\n                type: application/vnd.oai.openapi+json;version=3.0\n                title: the API definition\n              - href: \"http://data.example.org/api.html\"\n                rel: service-doc\n                type: text/html\n                title: the API documentation\n              - href: \"http://data.example.org/catalogs/sentinel-1\"\n                rel: child\n                type: application/json\n                title: Sentinel 1 Catalog\n              - href: \"http://data.example.org/catalogs/sentinel-2\"\n                rel: child\n                type: application/json\n                title: Sentinel 2 Catalog\n"
  },
  {
    "path": "extensions.md",
    "content": "# STAC API Extensions\n\nSTAC API aims to define a core of functionality, with richer capabilities enabled by extensions. The list of\nSTAC API Extensions is maintained at **<https://stac-api-extensions.github.io>**.\n\nThis document explains the process of creating and maturing an extension.\n\nAnyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged\nto add the extension to the [official list](https://stac-api-extensions.github.io) by creating an issue or PR\non <https://github.com/stac-api-extensions/stac-api-extensions.github.io>.\n\nAll extensions must include a [maturity classification](README.md#maturity-classification), so that STAC API\nspecification users can easily get a sense of how much they can count on the extension.\n\n## Extensions and Conformance\n\nEach extension has its own conformance class, which is specified with one or more **conformance URIs**\nthat are defined for the extension. These must be listed in the `conformsTo` JSON of the Landing Page,\nas specified by [STAC API - Core](core/), to let clients know that they can use the functionality.\n\nA number of extensions define functionality that could be used easily in a number of endpoints, such\nas additional parameters for search through either **STAC API - Item Search** or **STAC API - Features**.\n\n## Creating new extensions\n\nCreating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives\nan overview of the functionality. In the README, a conformance URI should be provided, so clients can use it to tell if\na service has the indicated functionality. It is also recommended to note the 'extension maturity', as defined above,\nso others can know how widely it is used.\n\nThe new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes.\nThe first step in sharing the extension is to add it to the official list, as described above. If it is of something\nthat the wider community may be interested in, then it may be added to the\n[stac-api-extensions](https://github.com/stac-api-extensions) GitHub organization.\n"
  },
  {
    "path": "fragments/itemcollection/README.md",
    "content": "# STAC API - ItemCollection Fragment\n\nThis document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) ItemCollection. \nAn **ItemCollection** is a [GeoJSON](http://geojson.org/) [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) \nthat is augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC entity.\n\nSimilarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection must be a valid GeoJSON \nFeatureCollection to allow interoperability with existing tools that support GeoJSON. \n\nItem objects are represented in JSON format and are very flexible. Any JSON object that contains all the\nrequired fields is a valid STAC ItemCollection.\n\n- Examples:\n  - See the [minimal example](examples/itemcollection-sample-minimal.json), as well as a [more complete \n    example](examples/itemcollection-sample-full.json). There are more real world inspired samples in the [examples/](examples/) folder.\n- [OpenAPI YAML](openapi.yaml)\n\n## ItemCollection fields\n\nThis object describes a STAC ItemCollection. The fields `type` and `features` are inherited from GeoJSON FeatureCollection.\n\n| Field Name     | Type                                                                 | Description                                                                     |\n| -------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| type           | string                                                               | **REQUIRED.** Always \"FeatureCollection\" to provide compatibility with GeoJSON. |\n| features       | \\[[STAC Item](../../stac-spec/item-spec/item-spec.md)]               | **REQUIRED.** A possibly-empty array of Item objects.                           |\n| links          | \\[[Link Object](../../stac-spec/item-spec/item-spec.md#link-object)] | An array of Links related to this ItemCollection.                               |\n| numberMatched  | integer                                                              | The number of Items that meet the selection parameters, possibly estimated.     |\n| numberReturned | integer                                                              | The number of Items in the `features` array.                                    |\n\n## Extensions\n\nSTAC API Extensions can be found [here](https://stac-api-extensions.github.io).\n"
  },
  {
    "path": "fragments/itemcollection/examples/itemcollection-sample-full.json",
    "content": "{\n    \"type\": \"FeatureCollection\",\n    \"numberMatched\": 10,\n    \"numberReturned\": 1,\n    \"features\": [\n        {\n            \"stac_version\": \"1.0.0\",\n            \"stac_extensions\": [],\n            \"type\": \"Feature\",\n            \"id\": \"cs3-20160503_132131_05\",\n            \"bbox\": [\n                -122.59750209,\n                37.48803556,\n                -122.2880486,\n                37.613537207\n            ],\n            \"geometry\": {\n                \"type\": \"Polygon\",\n                \"coordinates\": [\n                    [\n                        [\n                            -122.308150179,\n                            37.488035566\n                        ],\n                        [\n                            -122.597502109,\n                            37.538869539\n                        ],\n                        [\n                            -122.576687533,\n                            37.613537207\n                        ],\n                        [\n                            -122.288048600,\n                            37.562818007\n                        ],\n                        [\n                            -122.308150179,\n                            37.488035566\n                        ]\n                    ]\n                ]\n            },\n            \"properties\": {\n                \"datetime\": \"2016-05-03T13:22:30.040Z\",\n                \"title\": \"A CS3 item\",\n                \"license\": \"PDDL-1.0\",\n                \"providers\": [\n                    {\n                        \"name\": \"CoolSat\",\n                        \"roles\": [\n                            \"producer\",\n                            \"licensor\"\n                        ],\n                        \"url\": \"https://stac-api.example.com\"\n                    }\n                ]\n            },\n            \"collection\": \"cs3\",\n            \"links\": [\n                {\n                    \"rel\": \"self\",\n                    \"type\": \"application/json\",\n                    \"href\": \"https://stac-api.example.com/collections/cs3/items/CS3-20160503_132131_05\"\n                },\n                {\n                    \"rel\": \"root\",\n                    \"type\": \"application/json\",\n                    \"href\": \"https://stac-api.example.com/\"\n                },\n                {\n                    \"rel\": \"collection\",\n                    \"type\": \"application/json\",\n                    \"href\": \"https://stac-api.example.com/collections/cs3\"\n                }\n            ],\n            \"assets\": {\n                \"analytic\": {\n                    \"href\": \"https://stac-api.example.com/catalog/cs3-20160503_132130_04/analytic.tif\",\n                    \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n                    \"title\": \"4-Band Analytic\"\n                },\n                \"thumbnail\": {\n                    \"href\": \"https://stac-api.example.com/catalog/cs3-20160503_132130_04/thumbnail.png\",\n                    \"type\": \"image/png\",\n                    \"title\": \"Thumbnail\",\n                    \"roles\": [\n                        \"thumbnail\"\n                    ]\n                }\n            }\n        }\n    ],\n    \"links\": [\n        {\n            \"rel\": \"root\",\n            \"href\": \"http://stac.example.com/\",\n            \"type\": \"application/json\"\n        }\n    ]\n}"
  },
  {
    "path": "fragments/itemcollection/examples/itemcollection-sample-minimal.json",
    "content": "{\n  \"type\": \"FeatureCollection\",\n  \"features\": []\n}\n"
  },
  {
    "path": "fragments/itemcollection/openapi.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: The SpatioTemporal Asset Catalog API - Item Collection\n  description: The specification for a set of items, e.g. returned by a search.\n  version: v1.0.0\npaths: {}\ncomponents:\n  schemas:\n    itemCollection:\n      description: >-\n        A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity\n      type: object\n      required:\n        - features\n        - type\n      properties:\n        type:\n          type: string\n          enum:\n            - FeatureCollection\n        features:\n          type: array\n          items:\n            $ref: \"../../core/commons.yaml#/components/schemas/item\"\n        links:\n          type: array\n          description: >-\n            An array of links. Can be used for pagination, e.g. by providing a link\n            with the `next` relation type.\n          items:\n            $ref: \"../../core/commons.yaml#/components/schemas/link\"\n          example:\n            - rel: next\n              type: application/geo+json\n              href: >-\n                http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk\n        numberMatched:\n          type: integer\n          minimum: 0\n        numberReturned:\n          type: integer\n          minimum: 0\n"
  },
  {
    "path": "implementation.md",
    "content": "# Implementation Recommendations\n\nThis document describes implementation recommendations for a STAC API.\n\n## Identifiers\n\nIt is recommended that all items presented through a STAC API be part of a collection. STAC\nallows items to not be contained in a collection, though this is rarely done in practice.\nFor each STAC Item, the Collection ID and Item ID must for a globally-unique tuple, e.g., item IDs are unique within a collection.\n\n## CORS\n\nWeb browsers enforce a mechanism called [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to prevent \nmalicious access to APIs. It is recommended that public STAC APIs advertise a permissive [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) \nconfiguration so browser-based UIs running on a different domain may more easily access them.\n\nAPIs should acknowledge pre-flight request headers. In general, these header values should be set on responses:\n\n```\naccess-control-allow-origin: *\naccess-control-allow-methods: OPTIONS, POST, GET\naccess-control-allow-headers: Content-Type\n```\n\nIt is relatively safe to use these headers for all endpoints. However, one may want to restrict the methods to \nonly those that apply to each endpoint. For example, the `/collection/{collectionId}/items` endpoint should \nonly allow OPTIONS and GET, since POST is only used by the Transactions Extension, which presumably would \nrequire authentication as it is mutating data. \n\nImplementations that support the Transactions Extension or require credentials for some operations will need to \nimplement different behavior, for example, allowing credentials when requests are coming from a trusted domain, \nallowing DELETE, PUT, or PATCH methods, or \npermitting the `If-Match` request header.\n\n## datetime Parameter Handling\n\nThe datetime parameter used by the Item Search and Features conformance classes allows the same values as the \n[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for \neither a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`) \nor a closed or single open ended interval that also uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`).\n\nRFC 3339 is a profile of ISO 8601, adding these constraints to the allowed values:\n- a complete representation of date and time (fractional seconds optional).\n- requires 4-digit years\n- only allows a period character to be used as the decimal point for fractional seconds\n- requires the zone offset to be `Z` or like `+00:00`, while ISO8601 allows timezones like `+0000`\n\nA simple regex for an RFC 3339 datetime is:\n\n```regex\n^(\\d\\d\\d\\d)\\-(\\d\\d)\\-(\\d\\d)(T|t)(\\d\\d):(\\d\\d):(\\d\\d)([.]\\d+)?(Z|([-+])(\\d\\d):(\\d\\d))$\n```\n\nThis is not a precise regex, as it matches some strings that violate semantics. There are additional restrictions, for example, \nthe month (01-12), the day (01-31), the hour (0-24), minute (0-60), seconds (0-9), and timezone offsets.  However, the best \nstrategy is to use this regex to ensure the datetime conforms to the RFC 3339 profile and then us an ISO8601 parser to produce\na valid datetime object from the datetime string.\n\nThereby, the recommended process for parsing the datetime value (which may consist of a single\nRFC 3339 datetime or an interval) is:\n\n1. uppercase the string (this avoids needing to match on both (t|T) and (z|Z))\n2. split the string on `/` to determine if it is a single datetime or an interval\n3. For the single value or each value of the split, check if it is either an open interval\n   (the empty string or `..`), or a datetime value. Only one of the interval ends may be open.\n4. Either use an RFC 3339 datetime parser like in [ciso8601](https://github.com/closeio/ciso8601), or\n   match the datetime value against the RFC 3339 regex, upper case the string, and use an \n   ISO8601 parser such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python) or\n   [Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into\n   language standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in\n   Python datetime library does not handle `Z` as a timezone.\n\nBelow are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, the use of `.` \nas the fractional seconds separator, Z (recommended) or z as a timezone, \npositive and negative arbitrary offset timezones, and T (recommended) or t as a separator between date and time. While \nthe RFC 3339 spec does not define the required number of fractional seconds, STAC API only requires up to \n9 digits be supported.\n\n- 1990-12-31T23:59:59Z (no fractional seconds, Z timezone)\n- 1990-12-31T23:59:23.123Z (fractional seconds, Z timezone)\n- 1996-12-19T16:39:57-08:00 (no fractional seconds, negative offset timezone)\n- 1937-01-01T12:00:27.87+01:00 (fractional seconds, positive offset timezone)\n- 1985-04-12t23:20:50.5202020z (lowercase t for separator, lowercase z for timezone)\n\nThese are several examples of datetime intervals:\n\n- `/1990-12-31T23:59:59Z`\n- `/1990-12-31T23:59:59Z`\n- `../1990-12-31T23:59:59Z`\n- `1990-12-31T23:59:59Z/`\n- `1990-12-31T23:59:59Z/..`\n- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z`\n\n## Authentication Status Codes\n\nWhen authentication is applied to a STAC API, it is recommended the following status codes be returned:\n\n- 401 when no or invalid authentication information is provided\n- 403 when valid authentication information is provided, but the principal does not have access (permissions)\n  on the requested resource\n"
  },
  {
    "path": "item-search/README.md",
    "content": "# STAC API - Item Search\n\n- [STAC API - Item Search](#stac-api---item-search)\n  - [Summary](#summary)\n  - [Overview](#overview)\n  - [Link Relations](#link-relations)\n  - [Endpoints](#endpoints)\n  - [Query Parameters and Fields](#query-parameters-and-fields)\n    - [Query Examples](#query-examples)\n    - [Query Parameter Table](#query-parameter-table)\n  - [Response](#response)\n    - [Pagination](#pagination)\n  - [HTTP Request Methods and Content Types](#http-request-methods-and-content-types)\n    - [GET](#get)\n    - [POST](#post)\n      - [PUT / PATCH / DELETE](#put--patch--delete)\n  - [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search)\n  - [Extensions](#extensions)\n\n## Summary\n\n- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/item-search))\n- **Conformance URIs:**\n  - <https://api.stacspec.org/v1.0.0/item-search>\n- **[Maturity Classification](../README.md#maturity-classification):** Candidate\n- **Dependencies**: [STAC API - Core](../core)\n- **Examples**: [examples.md](examples.md)\n\n## Overview\n\nThe *STAC API - Item Search* specification defines the *STAC API - Item Search*\nconformance class (<https://api.stacspec.org/v1.0.0/item-search>), which\nprovides the ability to search for STAC [Item](../stac-spec/item-spec/README.md)\nobjects across collections.\nIt retrieves a group of Item objects that match the provided parameters, wrapped in an\n[ItemCollection](../fragments/itemcollection/README.md) (which is a\nvalid [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that contains STAC Item objects). Several core\nquery parameters are defined by [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), with\na few additions specified in this document.\n\nThe Item Search endpoint intentionally defines only a limited group of operations. It is expected that\nmost behavior will be defined in [Extensions](#extensions). These extensions can be composed by an implementer to\ncover only the set of functionality the implementer requires. For example, the query capability defined by\nItem Search is limited, and only adds cross-collection and spatial intersects query operators to the capabilities\nalready defined by OAFeat. For example, the Query Extension and Filter Extension\nprovide a more expressive set of operators.\n\nImplementing `GET /search` is **required**, `POST /search` is optional, but recommended.\n\n## Link Relations\n\nThe STAC definition of Link does not require the `type` field,\nbut it is **STRONGLY RECOMMENDED** that this field exists.\nIf the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.\n\nThis conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.\n\nThe following Link relations are defined for the Landing Page (root).\n\n| **rel**  | **href**  | **Media Type**       | **From**               | **Description**                          |\n| -------- | --------- | -------------------- | ---------------------- | ---------------------------------------- |\n| `search` | `/search` | application/geo+json | STAC API - Item Search | **REQUIRED** URI for the Search endpoint |\n\nThis `search` link relation must have a `type` of `application/geo+json`. If no `method` attribute is\nspecified, 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`.\n\nOther links with relation `search` may be included that advertise other content types the server may respond\nwith, but these other types are not part of the STAC API requirements.\n\nThe following Link relations are defined for the `/search` endpoint response.\n\n| **rel** | **href** | **From**               | **Description**           |\n| ------- | -------- | ---------------------- | ------------------------- |\n| `root`  | `/`      | STAC API - Item Search | **REQUIRED** The root URI |\n\n## Endpoints\n\nThis conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.\n\n| **Endpoint** | **Returns**     | **Media Type**       | **From**               | **Description** |\n| ------------ | --------------- | -------------------- | ---------------------- | --------------- |\n| `/search`    | Item Collection | application/geo+json | STAC API - Item Search | Search endpoint |\n\n## Query Parameters and Fields\n\nThe following list of parameters is used to narrow search queries. They can all be represented as query\nstring parameters in a GET request, or as JSON entity fields in a POST request. For filters that represent\na set of values, query parameters must use comma-separated string values with no enclosing brackets\n(\\[ or \\]) and no whitespace between values, and JSON entity attributes must use JSON Arrays.\n\n### Query Examples\n\n```\nGET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit=200&datetime=2017-05-05T00:00:00Z\n```\n\n```json\n{\n    \"collections\": [\"landsat8\",\"sentinel\"],\n    \"bbox\": [-10.415,36.066,3.779,44.213],\n    \"limit\": 200,\n    \"datetime\": \"2017-05-05T00:00:00Z\"\n}\n```\n\nFor more examples see [examples.md](examples.md).\n\n### Query Parameter Table\n\nThe core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience.\n\n| **Parameter** | **Type**         | **Source API** | **Description**                                                                                                                                                                 |\n| ------------- | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| limit         | integer          | OAFeat         | The maximum number of results to return (page size).                                                                                                                            |\n| bbox          | \\[number]        | OAFeat         | Requested bounding box.                                                                                                                                                         |\n| 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. |\n| intersects    | GeoJSON Geometry | STAC           | Searches items by performing intersection between their geometry and provided GeoJSON geometry.  All GeoJSON geometry types must be supported.                                  |\n| ids           | \\[string]        | STAC           | Array of Item ids to return.                                                                                                                                                    |\n| collections   | \\[string]        | STAC           | Array of one or more Collection IDs that each matching Item must be in.                                                                                                         |\n\nSee [examples](examples.md) for some example requests.\n\n**limit** The limit parameter follows the same semantics of the OAFeat Item resource limit parameter. The value is\na suggestion to the server as to the maximum number of Item objects the\nclient would prefer in the response. The server may return fewer Item objects, but\nmust not return more. The OpenAPI specification defines the default and maximum values\nfor this parameter. The base specifications define these with a default of 10 and a maximum of 10000, but implementers\nmay choose other values to advertise through their `service-desc` endpoint.  If the limit parameter value is greater\nthan the advertised maximum limit, the server must act as if the request were for the maximum\nand not return an error.\n\n**datetime** The datetime parameter use the same allowed values as the\n[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter.\nThis allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an\nopen or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be\nfound in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling).\n\nOnly one of either **intersects** or **bbox** may be specified.  If both are specified, a 400 Bad Request status code\nmust be returned.\n\n**bbox** Represented using either 2D or 3D geometries. The length of the array must be 2\\*n where\n*n* is the number of dimensions. The array contains all axes of the southwesterly most extent\nfollowed by all axes of the northeasterly most extent specified in Longitude/Latitude or\nLongitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84).\nWhen using 3D geometries, the elevation of the southwesterly most extent is the minimum elevation\nin meters and the elevation of the northeasterly most extent is the maximum. When filtering with\na 3D bbox over Items with 2D geometries, it is assumed that the 2D geometries are at\nelevation 0. Degenerate bboxes that form a point or line must be supported.\n\n**intersects** It is at the discretion of the implementation to reject semantically-invalid\nGeoJSON objects, e.g., a self-intersecting Polygon or a LineString with zero-length segments.\nThese should result in a 400 Bad Request status code and a specific error message, rather than\na 500 Server Error and generic or database-level error message.\n\n## Response\n\nThe response to a request (GET or POST) to the search endpoint must always be an\n[ItemCollection](../fragments/itemcollection/README.md) object - a valid [GeoJSON\nFeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that consists entirely of STAC\n[Item](../stac-spec/item-spec/item-spec.md) objects.\n\n### Pagination\n\nOGC API supports paging through hypermedia links and STAC follows the same pattern for the cross collection search. For\nGET requests, a link with `rel` type `next` is supplied.  This link may contain any URL parameter that is necessary\nfor the implementation to understand how to provide the next page of results, eg: `page`, `next`, `token`, etc.  The\nparameter name is defined by the implementor and is not necessarily part of the API specification.  For example:\n\n```json\n{\n    \"type\": \"FeatureCollection\",\n    \"features\": [],\n    \"links\": [\n        {\n            \"rel\": \"next\",\n            \"href\": \"https://stac-api.example.com/search?page=3\",\n            \"type\": \"application/geo+json\"\n\n        },\n        {\n            \"rel\": \"prev\",\n            \"href\": \"https://stac-api.example.com/search?page=1\",\n            \"type\": \"application/geo+json\"\n        },\n        {\n            \"rel\": \"root\",\n            \"href\": \"https://stac-api.example.com/\",\n            \"type\": \"application/json\"\n        }\n    ]\n}\n```\n\nThe href may contain any arbitrary URL parameter:\n\n- `https://stac-api.example.com/search?page=2`\n- `https://stac-api.example.com/search?next=8a35eba9c`\n- `https://stac-api.example.com/search?token=f32890a0bdb09ac3`\n\nImplementations may also add link relations `prev`, `first`, and `last`, though these are not required and may\nbe infeasible to implement in some data stores.\n\nOAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed\nfor anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has\ndecided to extend the Link object to support additional fields that provide hints to the client as to how it must\nexecute a subsequent request for the next page of results.\n\nThe following fields have been added to the Link object specification for the API spec:\n\n| **Parameter** | **Type** | **Description**                                                                                                                                              |\n| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| method        | string   | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET`                                                                                   |\n| headers       | object   | A dictionary of header values that must be included in the next request                                                                                      |\n| body          | object   | A JSON object containing fields/values that must be included in the body of the next request                                                                 |\n| 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` |\n\nThe implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination\nmechanism.  The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page\nof results is purely up to the implementor and not defined in the API spec, if the implementor decides to use headers,\nthere are no specific or required header names defined in the specification.  Implementors may use any names or fields\nof their choosing. Pagination can be provided solely through header values, solely through body values, or through some\ncombination.\n\nTo avoid returning the entire original request body in a POST response which may be arbitrarily large, the  `merge`\nproperty can be specified. This indicates that the client must send the same post body that it sent in the original\nrequest, but with the specified headers/body values merged in. This allows servers to indicate what needs to change\nto get to the next page without mirroring the entire query structure back to the client.\n\nSee the [paging examples](examples.md#paging-examples) for additional insight.\n\n## HTTP Request Methods and Content Types\n\nSTAC APIs follow the modern web API practices of using HTTP Request Methods (\"verbs\") and\nthe `Content-Type` header to drive behavior on resources (\"nouns\").\nThis section describes how these are used with the `/search` endpoint.\n\n### GET\n\n**Required**: STAC's cross-collection `/search` requires GET queries for all implementations, following OAFeat's precedent of\nmaking GET required (it only specifies GET so far).\n\n### POST\n\n**Recommended** STAC `/search` is strongly recommended to implement POST `Content-Type: application/json`, where the content body is a JSON\nobject representing a query and filter, as defined in this document.\n\nIt is recommended that clients use POST for querying (if the STAC API supports it), especially when using the\n`intersects` query parameter, for two reasons:\n\n1. In practice, the allowed size for an HTTP GET request is significantly less than that allowed for a POST request,\nso if a large geometry is used in the query it may cause a GET request to fail.\n2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON\nparameters (such as intersect, as well as additional filters from the query extension).\n\n**STAC API extensions** allow for more sophisticated searching, such as the ability to sort, select which fields you want returned, and\nsearching on specific Item properties.\n\n#### PUT / PATCH / DELETE\n\nThe other HTTP verbs are not supported in STAC Item Search. The [Transaction Extension](https://github.com/stac-api-extensions/transaction)\ndoes implement them, for STAC and OAFeat implementations that want to enable writing and deleting items.\n\n## Example Landing Page for STAC API - Item Search\n\nThis JSON is what would be expected from an api that only implements *STAC API - Item Search*. In practice,\nmost APIs will also implement other conformance classes, and those will be reflected in the `links` and\n`conformsTo` fields.  A more typical Landing Page example is in\nthe [overview](../overview.md#example-landing-page) document.\n\n```json\n{\n    \"stac_version\": \"1.0.0\",\n    \"id\": \"example-stac\",\n    \"title\": \"A simple STAC API Example\",\n    \"description\": \"This Catalog aims to demonstrate the a simple landing page\",\n    \"type\": \"Catalog\",\n    \"conformsTo\" : [\n        \"https://api.stacspec.org/v1.0.0/core\",\n        \"https://api.stacspec.org/v1.0.0/item-search\"\n    ],\n    \"links\": [\n        {\n            \"rel\": \"self\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"root\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"service-desc\",\n            \"type\": \"application/vnd.oai.openapi+json;version=3.0\",\n            \"href\": \"https://stac-api.example.com/api\"\n        },\n        {\n            \"rel\": \"service-doc\",\n            \"type\": \"text/html\",\n            \"href\": \"https://stac-api.example.com/api.html\"\n        },\n        {\n            \"rel\": \"search\",\n            \"type\": \"application/geo+json\",\n            \"href\": \"https://stac-api.example.com/search\",\n            \"method\": \"GET\"\n        },\n        {\n            \"rel\": \"search\",\n            \"type\": \"application/geo+json\",\n            \"href\": \"https://stac-api.example.com/search\",\n            \"method\": \"POST\"\n        }\n    ]\n}\n```\n\n## Extensions\n\nSTAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).\n"
  },
  {
    "path": "item-search/examples.md",
    "content": "## Item Search Examples\n\n### Single Collection example\n\nThis example shows how you can request Item objects from a single collection from the `search` endpoint, without having to using\nOGC API - Features. It requests 100 results in `mycollection` that is in New Zealand at anytime on January 1st, 2019:\n\n```json\n{\n    \"collections\": [\"mycollection\"],\n    \"bbox\": [160.6,-55.95,-170,-25.89],\n    \"limit\": 100,\n    \"datetime\": \"2019-01-01T00:00:00Z/2019-01-01T23:59:59Z\"\n}\n```\n\n```\nGET /search?collections=mycollection&bbox=160.6,-55.95,-170,-25.89&limit=100&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z\n```\n\n### Paging Examples\n\n#### Simple GET based search\n\nRequest:\n```\nHTTP GET /search?bbox=-110,39.5,-105,40.5\n```\n\nResponse with `200 OK`:\n\n```json\n{\n    \"type\": \"FeatureCollection\",\n    \"features\": [],\n    \"links\": [\n        {\n            \"rel\": \"next\",\n            \"href\": \"https://stac-api.example.com/search?page=2\",\n            \"type\": \"application/geo+json\"\n        },\n        {\n            \"rel\": \"root\",\n            \"href\": \"https://stac-api.example.com/\",\n            \"type\": \"application/json\"\n        }\n    ]\n}\n```\n\nFollowing the link `https://stac-api.example.com/search?page=2` will send the user to the next page of results.\n\n#### POST search with body and merge fields\n\nRequest to `HTTP POST /search`:\n\n```json\n{\n    \"bbox\": [-110, 39.5, -105, 40.5]\n}\n```\n\nResponse with `200 OK`:\n\n```json\n{\n    \"type\": \"FeatureCollection\",\n    \"features\": [],\n    \"links\": [\n        {\n            \"rel\": \"next\",\n            \"href\": \"https://stac-api.example.com/search\",\n            \"type\": \"application/geo+json\",\n            \"method\": \"POST\",\n            \"body\": {\n                \"page\": 2,\n                \"limit\": 10\n            },\n            \"merge\": true\n        },\n        {\n            \"rel\": \"root\",\n            \"href\": \"https://stac-api.example.com/\",\n            \"type\": \"application/json\"\n        }\n    ]\n}\n```\n\nThis tells the client to POST to the search endpoint using the original request with the `page` and `limit` fields \nmerged in to obtain the next set of results:\n\nRequest to `POST /search`:\n```json\n{\n    \"bbox\": [-110, 39.5, -105, 40.5],\n    \"page\": 2,\n    \"limit\": 10\n}\n```\n\nThis can be even more effective when using continuation tokens on the server, as the entire request body need not be \nrepeated in the subsequent request:\n\nResponse with `200 OK`:\n\n```json\n{\n    \"rel\": \"next\",\n    \"href\": \"https://stac-api.example.com/search\",\n    \"type\": \"application/geo+json\",\n    \"method\": \"POST\",\n    \"body\": {\n        \"next\": \"a9f3kfbc98e29a0da23\"\n    }\n}\n```\n\nThe above link tells the client not to merge (default of false) so it is only required to pass the next token in the body.\n\nRequest to `POST /search`:\n\n```json\n{\n    \"next\": \"a9f3kfbc98e29a0da23\"\n}\n```\n\n#### POST search using headers\n\nRequest to `HTTP POST /search`:\n\n```json\n{\n    \"bbox\": [-110, 39.5, -105, 40.5],\n    \"page\": 2,\n    \"limit\": 10\n}\n```\n\nResponse with `200 OK`:\n\n```json\n{\n    \"type\": \"FeatureCollection\",\n    \"features\": [],\n    \"links\": [\n        {\n            \"rel\": \"next\",\n            \"href\": \"https://stac-api.example.com/search\",\n            \"type\": \"application/geo+json\",\n            \"method\": \"POST\",\n            \"headers\": {\n                \"Search-After\": \"LC81530752019135LGN00\"\n            }\n        },\n        {\n            \"rel\": \"root\",\n            \"href\": \"https://stac-api.example.com/\",\n            \"type\": \"application/json\"\n        }\n    ]\n}\n```\n\nThis tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results:\n\nRequest:\n\n```\nPOST /search\nSearch-After: LC81530752019135LGN00\n```\n"
  },
  {
    "path": "item-search/openapi.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: STAC API - Item Search\n  version: v1.0.0\n  description: >-\n    This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Item Search\n    specification.\n  contact:\n    name: STAC Specification\n    url: \"http://stacspec.org\"\n  license:\n    name: Apache License 2.0\n    url: \"http://www.apache.org/licenses/LICENSE-2.0\"\ntags:\n  - name: Item Search\n    description: essential characteristics of a STAC API\nx-conformance-classes: [\"https://api.stacspec.org/v1.0.0/item-search\"]\npaths:\n  /search:\n    get:\n      summary: Search STAC items with simple filtering.\n      operationId: getItemSearch\n      description: |-\n        Retrieve Items matching filters. Intended as a shorthand API for simple\n        queries.\n\n        This method is required to implement.\n\n        If this endpoint is implemented on a server, it is required to add a\n        link referring to this endpoint with `rel` set to `search` to the\n        `links` array in `GET /`. As `GET` is the default method, the `method`\n        may not be set explicitly in the link.\n      tags:\n        - Item Search\n      parameters:\n        - $ref: \"#/components/parameters/bbox\"\n        - $ref: \"#/components/parameters/intersects\"\n        - $ref: \"#/components/parameters/datetime\"\n        - $ref: \"#/components/parameters/limit\"\n        - $ref: \"#/components/parameters/ids\"\n        - $ref: \"#/components/parameters/collectionsArray\"\n      responses:\n        \"200\":\n          description: A feature collection.\n          content:\n            application/geo+json:\n              schema:\n                $ref: \"../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection\"\n            text/html:\n              schema:\n                type: string\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n    post:\n      summary: Search STAC items with full-featured filtering.\n      operationId: postItemSearch\n      description: |-\n        Retrieve items matching filters. Intended as the standard, full-featured\n        query API.\n\n        This method is optional to implement, but recommended.\n\n        If this endpoint is implemented on a server, it is required to add a\n        link referring to this endpoint with `rel` set to `search` and `method`\n        set to `POST` to the `links` array in `GET /`.\n      tags:\n        - Item Search\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/searchBody\"\n      responses:\n        \"200\":\n          description: A feature collection.\n          content:\n            application/geo+json:\n              schema:\n                $ref: \"../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection\"\n            text/html:\n              schema:\n                type: string\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\ncomponents:\n  parameters:\n    ids:\n      name: ids\n      in: query\n      description: |-\n        Array of Item ids to return.\n      required: false\n      schema:\n        $ref: \"#/components/schemas/ids\"\n      explode: false\n    collectionsArray:\n      name: collections\n      in: query\n      description: |\n        Array of Collection IDs to include in the search for items.\n        Only Item objects in one of the provided collections will be searched\n      required: false\n      schema:\n        $ref: \"#/components/schemas/collectionsArray\"\n      explode: false\n    datetime:\n      name: datetime\n      in: query\n      description: |-\n        Either a date-time or an interval, open or closed. Date and time expressions\n        adhere to RFC 3339. Open intervals are expressed using double-dots.\n\n        Examples:\n\n        * A date-time: \"2018-02-12T23:20:50Z\"\n        * A closed interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n        * Open intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n\n        Only features that have a temporal property that intersects the value of\n        `datetime` are selected.\n\n        If a feature has multiple temporal properties, it is the decision of the\n        server whether only a single temporal property is used to determine\n        the extent or all relevant temporal properties.\n      required: false\n      schema:\n        type: string\n      style: form\n      explode: false\n    bbox:\n      name: bbox\n      in: query\n      description: |-\n        Only features that have a geometry that intersects the bounding box are selected.\n        The bounding box is provided as four or six numbers, depending on\n        whether the coordinate reference system includes a vertical axis (height\n        or depth):\n\n        * Lower left corner, coordinate axis 1\n        * Lower left corner, coordinate axis 2\n        * Minimum value, coordinate axis 3 (optional)\n        * Upper right corner, coordinate axis 1\n        * Upper right corner, coordinate axis 2\n        * Maximum value, coordinate axis 3 (optional)\n\n        The coordinate reference system of the values is WGS 84\n        longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).\n\n        For WGS 84 longitude/latitude the values are in most cases the sequence\n        of minimum longitude, minimum latitude, maximum longitude and maximum\n        latitude. However, in cases where the box spans the antimeridian the\n        first value (west-most box edge) is larger than the third value\n        (east-most box edge).\n\n        If the vertical axis is included, the third and the sixth number are\n        the bottom and the top of the 3-dimensional bounding box.\n\n        If a feature has multiple spatial geometry properties, it is the\n        decision of the server whether only a single spatial geometry property\n        is used to determine the extent or all relevant geometries.\n\n        Example: The bounding box of the New Zealand Exclusive Economic Zone in\n        WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be\n        represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as\n        `bbox=160.6,-55.95,-170,-25.89`.\n      required: false\n      schema:\n        type: array\n        oneOf:\n          - minItems: 4\n            maxItems: 4\n          - minItems: 6\n            maxItems: 6\n        items:\n          type: number\n      style: form\n      explode: false\n    limit:\n      name: limit\n      in: query\n      description: |-\n        The optional limit parameter recommends the number of items that should be present in the response document.\n\n        Only items are counted that are on the first level of the collection in the response document.\n        Nested objects contained within the explicitly requested items must not be counted.\n\n        Minimum = 1. Maximum = 10000. Default = 10.\n      required: false\n      schema:\n        type: integer\n        minimum: 1\n        maximum: 10000\n        default: 10\n      style: form\n      explode: false\n    intersects:\n      name: intersects\n      in: query\n      description: |-\n        The optional intersects parameter filters the result Items in the same was as bbox, only with\n        a GeoJSON Geometry rather than a bbox.\n      required: false\n      schema:\n        $ref: \"../core/commons.yaml#/components/schemas/geometryGeoJSON\"\n      style: form\n      explode: false\n  schemas:\n    searchBody:\n      description: The search criteria\n      type: object\n      allOf:\n        - $ref: \"#/components/schemas/bboxFilter\"\n        - $ref: \"#/components/schemas/datetimeFilter\"\n        - $ref: \"#/components/schemas/intersectsFilter\"\n        - $ref: \"#/components/schemas/collectionsFilter\"\n        - $ref: \"#/components/schemas/idsFilter\"\n        - $ref: \"#/components/schemas/limitFilter\"\n    limit:\n      type: integer\n      minimum: 1\n      example: 10\n      default: 10\n      maximum: 10000\n      description: |-\n        The optional limit parameter limits the number of items that are presented in the response document.\n\n        If the limit parameter value is greater than advertised limit maximum, the server must return the\n        maximum possible number of items, rather than responding with an error.\n\n        Only items are counted that are on the first level of the collection in the response document.\n        Nested objects contained within the explicitly requested items must not be counted.\n\n        Minimum = 1. Maximum = 10000. Default = 10.\n    bboxFilter:\n      type: object\n      description: Only return items that intersect the provided bounding box.\n      properties:\n        bbox:\n          $ref: \"../core/commons.yaml#/components/schemas/bbox\"\n    collectionsArray:\n      type: array\n      description: |-\n        Array of Collection IDs to include in the search for items.\n        Only Item objects in one of the provided collections will be searched.\n      items:\n        type: string\n    ids:\n      type: array\n      description: |-\n        Array of Item ids to return.\n      items:\n        type: string\n    datetimeFilter:\n      description: An object representing a date+time based filter.\n      type: object\n      properties:\n        datetime:\n          $ref: \"#/components/schemas/datetime_interval\"\n    intersectsFilter:\n      type: object\n      description: Only returns items that intersect with the provided polygon.\n      properties:\n        intersects:\n          $ref: \"../core/commons.yaml#/components/schemas/geometryGeoJSON\"\n    limitFilter:\n      type: object\n      description: Only returns maximum number of results (page size)\n      properties:\n        limit:\n          $ref: \"#/components/schemas/limit\"\n    idsFilter:\n      type: object\n      description: Only returns items that match the array of given ids\n      properties:\n        ids:\n          $ref: \"#/components/schemas/ids\"\n    collectionsFilter:\n      type: object\n      description: Only returns the collections specified\n      properties:\n        collections:\n          $ref: \"#/components/schemas/collectionsArray\"\n    datetime_interval:\n      type: string\n      description: |-\n        Either a date-time or an interval, open or closed. Date and time expressions\n        adhere to RFC 3339. Open intervals are expressed using double-dots.\n\n        Examples:\n\n        * A date-time: \"2018-02-12T23:20:50Z\"\n        * A closed interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n        * Open intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n\n        Only features that have a temporal property that intersects the value of\n        `datetime` are selected.\n\n        If a feature has multiple temporal properties, it is the decision of the\n        server whether only a single temporal property is used to determine\n        the extent or all relevant temporal properties.\n      example: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n"
  },
  {
    "path": "ogcapi-features/README.md",
    "content": "# STAC API - Collections and Features Specification\n\n- [STAC API - Collections and Features Specification](#stac-api---collections-and-features-specification)\n  - [Summary](#summary)\n  - [Overview](#overview)\n  - [Conformance Classes](#conformance-classes)\n    - [STAC API - Features](#stac-api---features)\n    - [STAC API - Collections](#stac-api---collections)\n    - [OGC API - Features - Part 1: Core](#ogc-api---features---part-1-core)\n    - [OGC API - Features - Part 1: GeoJSON](#ogc-api---features---part-1-geojson)\n    - [OGC API - Features - Part 1: OpenAPI 3.0](#ogc-api---features---part-1-openapi-30)\n  - [Link Relations](#link-relations)\n    - [Landing Page (/)](#landing-page-)\n    - [Collections (/collections)](#collections-collections)\n    - [Collection (/collections/{collectionId})](#collection-collectionscollectionid)\n    - [Collection Items (/collections/{collectionId}/items)](#collection-items-collectionscollectioniditems)\n    - [Items (/collections/{collectionId}/items/{itemId})](#items-collectionscollectioniditemsitemid)\n  - [Endpoints](#endpoints)\n  - [Item Pagination](#item-pagination)\n  - [Collection Pagination](#collection-pagination)\n  - [Examples](#examples)\n  - [Example Landing Page](#example-landing-page)\n  - [Example Collection Endpoint](#example-collection-endpoint)\n  - [Extensions](#extensions)\n\n## Summary\n\n- **OpenAPI specifications:**\n  - [STAC API - Features](openapi-features.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/ogcapi-features))\n  - [STAC API - Collections](openapi-collections.yaml) ([rendered version](https://api.stacspec.org/v1.0.0/collections))\n- **Conformance Class URIs:**\n  - <https://api.stacspec.org/v1.0.0/ogcapi-features> - Features\n  - <https://api.stacspec.org/v1.0.0/collections> - Collections\n- **[Maturity Classification](../README.md#maturity-classification):** Candidate\n- **Dependencies**:\n  - [STAC API - Core](../core)\n  - [OGC API - Features](https://www.ogc.org/standards/ogcapi-features)\n  uses all the OGC API - Features openapi fragments to describe returning STAC Item objects.\n\n## Overview\n\nThe *STAC API - Collections and Features* specification extends the\n[OGC API - Features - Part 1: Core](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html)\n(OAFeat) specification. OAFeat\nallows returning any content type from its endpoints, whereas *STAC API - Features* requires support\nfor returning STAC [Item](../stac-spec/item-spec/README.md) and STAC [Collection](../stac-spec/item-spec/README.md)\nentities. As these entities are also GeoJSON types, the GeoJSON conformance class of OGC API - Features is supported\n(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson>).\n\n## Conformance Classes\n\nWhile OAFeat defines a single conformance class for its endpoints, STAC API divides these behaviors into two\nconformance classes -- Collections and Features. The STAC API - Features\n(<https://api.stacspec.org/v1.0.0/ogcapi-features>) conformance class includes and extends the behavior\nof OAFeat, while the STAC API - Collections (<https://api.stacspec.org/v1.0.0/collections>) conformance\nclass is the subset of Features that pertains only to Collections.\n\n### STAC API - Features\n\nThe *STAC API - Features* (<https://api.stacspec.org/v1.0.0/ogcapi-features>) conformance class\nencompasses all of the behavior described in this specification, as\nderived from OAFeat.\n\n### STAC API - Collections\n\nThe *STAC API - Collections* (<https://api.stacspec.org/v1.0.0/collections>) conformance class\nrequires only the subset of the behavior of Features that relates to Collections.\n\nThis subset is:\n\n- the `data` link relation on the landing page\n- the `/collections` and `/collections/{collection_id}` endpoints\n\nThis subset of behavior is useful in conjunction\nwith the *STAC API - Item Search* conformance class to allow the description of STAC Collections\nwithout needing to implement the entire *STAC API - Features* conformance class.\n\n### OGC API - Features - Part 1: Core\n\nA STAC API implementation that conforms to *STAC API - Features* (<https://api.stacspec.org/v1.0.0/ogcapi-features>)\nalso conforms to\n[OGC API - Features - Part 1 Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core)\nconformance class (<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core>). \nThis conformance class should be advertised to OAFeat clients so they will also work with the STAC API.\n\n### OGC API - Features - Part 1: GeoJSON\n\nA STAC API implementation that conforms to *STAC API - Features*\nalso conforms to [OGC API - Features - Part 1 Requirements Class GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson) (<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson>)\nThis conformance class should be advertised to OAFeat clients so they will know of the support for GeoJSON.\n\n### OGC API - Features - Part 1: OpenAPI 3.0\n\nIf OpenAPI 3.0 is used for the endpoint referenced by the `service-desc` link relation in the landing page defined\nby *STAC API - Core*, the\n[OGC API - Features - Part 1 Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)\n(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30>) can be advertised. \n\n## Link Relations\n\nThese conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.\n\nThe STAC definition of Link does not require the `type` field,\nbut it is **STRONGLY RECOMMENDED** that this field exists.\nIf the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.\n\n### Landing Page (/)\n\nThe following Link relations are defined for the Landing Page (root).\n\n| **rel**       | **href**       | **Media Type**   | **From** | **Description**                  |\n| ------------- | -------------- | ---------------- | -------- | -------------------------------- |\n| `conformance` | `/conformance` | application/json | OAFeat   | **REQUIRED** Conformance URI     |\n| `data`        | `/collections` | application/json | OAFeat   | **REQUIRED** List of Collections |\n\n### Collections (/collections)\n\nThe following Link relations are defined for the `/collections` endpoint response.\n\n| **rel** | **href**       | **Media Type**   | **From**                                    | **Description**             |\n| ------- | -------------- | ---------------- | ------------------------------------------- | --------------------------- |\n| `root`  | `/`            | application/json | STAC API - Features, STAC API - Collections | **REQUIRED** The root URI   |\n| `self`  | `/collections` | application/json | OAFeat                                      | **REQUIRED** Self reference |\n\n### Collection (/collections/{collectionId})\n\nThe following Link relations are defined for the Collection object returned from the `/collections/{collectionId}` endpoint.\n\n| **rel**     | **href**                      | **Media Type**   | **From**                                    | **Description**                                                                                                                                                                                                                                                                                         |\n| ----------- | ----------------------------- | ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `root`      | `/`                           | application/json | STAC API - Features, STAC API - Collections | **REQUIRED** The root URI                                                                                                                                                                                                                                                                               |\n| `self`      | `/collections/{collectionId}` | application/json | OAFeat                                      | **REQUIRED** Self reference                                                                                                                                                                                                                                                                             |\n| `parent`    | `/`                           | application/json | STAC Collection                             | Parent reference, usually the root Catalog                                                                                                                                                                                                                                                              |\n| `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. |\n\nUsually, the `self` link in a Collection must link to the same URL that was used to request\nit. However, implementations may choose to have the canonical location of the Collection be\nelsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.\n\nNote that the `parent` link for a Collection should be point to the parent Catalog (such as the root Catalog, `/`) or Collection\nof that Collection, rather than the API sub-path of `/collections`.\n\n### Collection Items (/collections/{collectionId}/items)\n\nThe following Link relations are defined for the ItemCollection object returned from the `/collections/{collectionId}/items` endpoint.\n\n| **rel**      | **href**                            | **Media Type**       | **From**            | **Description**                   |\n| ------------ | ----------------------------------- | -------------------- | ------------------- | --------------------------------- |\n| `root`       | `/`                                 | application/json     | STAC API - Features | **REQUIRED** The root URI         |\n| `self`       | `/collections/{collectionId}/items` | application/geo+json | OAFeat              | **REQUIRED** Self reference       |\n| `collection` | `/collections/{collectionId}`       | application/json     | OAFeat              | **REQUIRED** Collection reference |\n\n### Items (/collections/{collectionId}/items/{itemId})\n\nThe following Link relations are defined for the Item object returned from the `/collections/{collectionId}/items/{itemId}` endpoint.\n\n| **rel**      | **href**                                     | **Media Type**       | **From**            | **Description**                                     |\n| ------------ | -------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------- |\n| `root`       | `/`                                          | application/json     | STAC API - Features | **REQUIRED** The root URI                           |\n| `self`       | `/collections/{collectionId}/items/{itemId}` | application/geo+json | OAFeat              | **REQUIRED** Self reference                         |\n| `collection` | `/collections/{collectionId}`                | application/json     | STAC Item           | **REQUIRED** The containing Collection              |\n| `parent`     | `/collections/{collectionId}`                | application/json     | STAC Item           | Parent reference, usually the containing Collection |\n\nThe `parent` link for an Item may point to a Collection or a Catalog.  The\n`collection` link for an Item will always point to the containing Collection.\nLinks to a Collection must point to the `/collections/{collectionId}` endpoint,\nrather than the API sub-path of `/collections/{collectionId}/items/`.\n\n## Endpoints\n\nThis conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.\n\nThe *OGC API - Features* endpoints are shown below, with details provided in the OpenAPI specifications for [Features](openapi-features.yaml) or [Collections](openapi-collections.yaml).\n\n| **Endpoint**                                    | **Returns**          | **Media Type**                                          | **Description**                                                                     |\n| ----------------------------------------------- | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| `/collections`                                  | application/json     | JSON                                                    | Object containing an array of Collection objects in the Catalog, and Link relations |\n| `/collections/{collectionId}`                   | application/json     | [Collection](../stac-spec/collection-spec/README.md)    | Returns single Collection JSON                                                      |\n| `/collections/{collectionId}/items`             | application/geo+json | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection           |\n| `/collections/{collectionId}/items/{featureId}` | application/geo+json | [Item](../stac-spec/item-spec/README.md)                | Returns single Item (GeoJSON Feature)                                               |\n\nThe OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface\nto query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry\nplus any number of properties. The core [STAC Item spec](../stac-spec/item-spec/README.md)\nenhances the core `Feature` with additional requirements and options to enable cataloging of spatiotemporal 'assets' like\nsatellite imagery.\n\nOAFeat also defines the concept of a Collection, which contains Features. In OAFeat, a Collection is a set of data that can\nbe queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic\ninformation about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all\nthe data contained. A [STAC Collection](../stac-spec/collection-spec/README.md) contains this same\ninformation, along with other STAC-specific fields to provide additional metadata for searching spatiotemporal assets, and\nthus are compliant with both OAFeat Collection and STAC Collection, and are returned from the `/collections/{collectionId}`\nendpoint.\n\nIn OAFeat, Features are the individual records within a Collection and are usually provided in GeoJSON format.\n[STAC Item](../stac-spec/item-spec/README.md) objects are compliant with the OAFeat Features\n[GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the\n`/collections/{collectionId}/items/{itemId}` endpoint. The return of other encodings\n([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))\nis outside the scope of STAC API, as the [STAC Item](../stac-spec/item-spec/item-spec.md) is\nspecified in GeoJSON.\n\nA typical OAFeat will have multiple collections. Simple search for items within a collection can be done\nwith the resource endpoint `GET /collections/{collectionId}/items`. This endpoint must be exposed via a\nlink in the individual collection's endpoint with `rel=items`, as shown in the\n[Example Landing Page diagram](../overview.md#example-landing-page). Note that this relation is `items`, which is\ndistinct from the `item` relation defined in STAC for linking to a single Item. The part of the API implementing OAFeat will usually not use\n`item` relations directly, but instead rely on\nthe collection resource linking to a paginated endpoint returning items through a link relation\n`items`, e.g., `/collections/{collectionId}` has a link with relation `items` linking\nto `/collections/{collectionId}/items`. However, static catalogs and other parts of the API may contain `item` relations.\n\nIt is recommended to have each OAFeat Collection correspond to a STAC Collection,\nand the `/collections/{collectionId}/items` endpoint can be used as a single collection search. Implementations may **optionally**\nprovide support for the full superset of STAC API query parameters to the `/collections/{collectionId}/items` endpoint,\nwhere the collection ID in the path is equivalent to providing that single value in the `Collections* query parameter in\nSTAC API.\n\nImplementing OAFeat enables a wider range of clients to access the API's STAC Item objects, as it is a more widely implemented\nprotocol than STAC.\n\n## Item Pagination\n\nOAFeat supports paging through hypermedia links for the Items resource\n(`/collections/{collectionId}/items`). Since only GET requests are allowed for this endpoint,\nit is possible\nto provide a Link with `rel` type `next` and the href of the full URL of the next page of results.\nThis link href must contain any URL parameters that are necessary\nfor the implementation to understand how to provide the next page of results, e.g., the query parameters `page`, `next`,\nor `token` and any additional filter parameters if given and required. For example, the links array will have an object like:\n\n```json\n    \"links\": [\n        {\n            \"rel\": \"next\",\n            \"type\": \"application/geo+json\",\n            \"href\": \"https://stac-api.example.com/collections/my_collection/items?page=2\"\n        }\n    ]\n```\n\nThe href may contain any arbitrary URL parameter, which is implementation-specific:\n\n- `https://stac-api.example.com/collections/my_collection/items?page=2`\n- `https://stac-api.example.com/collections/my_collection/items?next=8a35eba9c`\n- `https://stac-api.example.com/collections/my_collection/items?token=f32890a0bdb09ac3`\n\nIn addition to supporting query parameters in the URL value of the `href` field,\nSTAC has extended the Link object\nwith additional fields to support more complex HTTP requests. These include `method` to specify\nan HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either\nthe entire body for the request or only the body fields that must be changed from the previous\nrequest, as determined by the `merge` field. These fields are described in detail in the\n[Item Search](../item-search/README.md#pagination) spec.\n\nImplementations may also add link relations `prev`, `first`, and `last`. Most API implementations\nshould be able to support `first`, though `last` may be infeasible to implement in some data\nstores.\n\nSee the [paging examples](../item-search/examples.md#paging-examples) for additional insight.\n\n## Collection Pagination\n\nOAFeat does not define a specific mechanism for how clients may access all collections from servers\nwith many\ncollections. STAC API - Features adds support for this with pagination (similar to the Item pagination\nmechanism) through hypermedia links for the Collections resource\n(`/collections`). This mechanism aligns with pagination of collections in the\n[OGC API - Common - Part 2: Geospatial Data](https://portal.ogc.org/files/99149) specification. \nWith this, a link with\nrelation `next` is included in the `links` array,\nand this is used to navigate to the next page of Collection objects. The specific query\nparameter used for paging is implementation specific and not defined by STAC API. For example,\nan implementation may take a parameter (e.g., `page`) indicating the numeric page of results, a\nbase64-encoded value indicating the last result returned for the current page (e.g., `search_after` as\nin Elasticsearch), or a cursor token representing backend state.\n\nIn our simple example of numerical pages, the response for `page=3` would have a\n`links` array containing these two Links indicating the URLs for the next (page=4) and\nprevious (page=2) pages:\n\n```json\n{\n    \"links\": [\n    {\n        \"rel\": \"prev\",\n        \"type\": \"application/json\",\n        \"href\": \"https://stac-api.example.com/collections?page=2\"\n    },\n    {\n        \"rel\": \"next\",\n        \"type\": \"application/json\",\n        \"href\": \"https://stac-api.example.com/collections?page=4\"\n    }\n    ]\n}\n```\n\nIn addition to supporting query parameters in the URL value of the `href` field,\nSTAC has extended the Link object\nwith additional fields to support more complex HTTP requests. These include `method` to specify\nan HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either\nthe entire body for the request or only the body fields that must be changed from the previous\nrequest, as determined by the `merge` field. These fields are described in detail in the\n[Item Search](../item-search/README.md#pagination) spec.\n\nImplementations may also add link relations `prev`, `first`, and `last`. Most API implementations\nshould be able to support `first`, though `last` may be infeasible to implement in some data\nstores.\n\n## Examples\n\nNote that the OAFeat endpoints *only* allow HTTP GET. HTTP POST requests are not supported. If POST is required,\nit is recommended to use STAC Item Search, as it can be constrained to a single collection to act the same as\nan OAFeat `items` endpoint.\n\nRequest all the data in `mycollection` that is in New Zealand:\n\n```\nGET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89\n```\n\nRequest 100 results in `mycollection` from New Zealand:\n\n```\nGET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100\n```\n\nRequest all the data in `mycollection` that is in New Zealand at anytime on January 1st, 2019:\n\n```\nGET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z\n```\n\nRequest 10 results from the data in `mycollection` from between January 1st (inclusive) and April 1st, 2019 (exclusive):\n\n```\nGET /collections/mycollection/items?datetime=2019-01-01T00:00:00Z/2019-03-31T23:59:59Z&limit=10\n```\n\n## Example Landing Page\n\nThis JSON is what would be expected from an api that implements only *STAC API - Core* and \n*STAC API - Features*. In practice,\nmost APIs will also implement other conformance classes, and those will be reflected in the `links` and\n`conformsTo` fields.  A more typical Landing Page example is in\nthe [overview](../overview.md#example-landing-page) document.\n\n```json\n{\n    \"stac_version\": \"1.0.0\",\n    \"id\": \"example-stac\",\n    \"title\": \"A simple STAC API Example\",\n    \"description\": \"This Catalog aims to demonstrate the a simple landing page\",\n    \"type\": \"Catalog\",\n    \"conformsTo\" : [\n        \"https://api.stacspec.org/v1.0.0/core\",\n        \"https://api.stacspec.org/v1.0.0/ogcapi-features\",\n        \"https://api.stacspec.org/v1.0.0/collections\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson\"\n    ],\n    \"links\": [\n        {\n            \"rel\": \"self\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"root\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"conformance\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/conformance\"\n        },\n        {\n            \"rel\": \"service-desc\",\n            \"type\": \"application/vnd.oai.openapi+json;version=3.0\",\n            \"href\": \"https://stac-api.example.com/api\"\n        },\n        {\n            \"rel\": \"service-doc\",\n            \"type\": \"text/html\",\n            \"href\": \"https://stac-api.example.com/api.html\"\n        },\n        {\n            \"rel\": \"data\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/collections\"\n        }\n    ]\n}\n```\n\n## Example Collection Endpoint\n\nThe landing page `data` relation points to an endpoint to retrieve all collections. Each collection then has\na link relation to its `items` resource through the link with a rel value `items`.  Note here that, unlike\nas is typical with a static STAC Collection, there are no links here with rel value `item`.\n\n`https://stac-api.example.com/collections/aster-l1t`\n\n```json\n{\n  \"id\": \"aster-l1t\",\n  \"type\": \"Collection\",\n  \"title\": \"ASTER L1T\",\n  \"links\": [\n    {\n      \"rel\": \"items\",\n      \"type\": \"application/geo+json\",\n      \"href\": \"https://stac-api.example.com/collections/aster-l1t/items\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"type\": \"application/json\",\n      \"href\": \"https://stac-api.example.com\"\n    },\n    {\n      \"rel\": \"root\",\n      \"type\": \"application/json\",\n      \"href\": \"https://stac-api.example.com\"\n    },\n    {\n      \"rel\": \"self\",\n      \"type\": \"application/json\",\n      \"href\": \"https://stac-api.example.com/collections/aster-l1t\"\n    }\n  ]\n}\n```\n\n## Extensions\n\nSTAC API Extensions can be found at [stac-api-extensions.github.io](https://stac-api-extensions.github.io).\n"
  },
  {
    "path": "ogcapi-features/openapi-collections.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: STAC API - Collections\n  version: v1.0.0\n  description: >-\n    This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Collections\n    specification.  This is a subset of the STAC API - Features specification.\n  contact:\n    name: STAC Specification\n    url: \"http://stacspec.org\"\n  license:\n    name: Apache License 2.0\n    url: \"http://www.apache.org/licenses/LICENSE-2.0\"\n  x-conformance-classes: [\"https://api.stacspec.org/v1.0.0/collections\"]\ntags:\n  - name: Core\n    description: essential characteristics of a STAC API\n  - name: Collections\n    description: All endpoints related to STAC API - Collections\npaths:\n  \"/\":\n    get:\n      tags:\n        - Core\n      summary: landing page\n      description: |-\n        The landing page provides links to the sub-resources.\n      operationId: getLandingPage\n      responses:\n        \"200\":\n          description: |-\n            The landing page provides links to the API definition\n            (link relations `service-desc` and `service-doc`),\n            the Conformance declaration (path `/conformance`,\n            link relation `conformance`), and the Feature\n            Collections (path `/collections`, link relation\n            `data`).\n          content:\n            application/json:\n              schema:\n                $ref: \"../core/openapi.yaml#/components/schemas/landingPage\"\n              example:\n                stac_version: \"1.0.0\"\n                type: Catalog\n                id: sentinel\n                title: Copernicus Sentinel Imagery\n                description: Catalog of Copernicus Sentinel 1 and 2 imagery.\n                conformsTo:\n                  - \"https://api.stacspec.org/v1.0.0/core\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson\"\n                links:\n                  - href: \"http://data.example.org/\"\n                    rel: self\n                    type: application/json\n                    title: this document\n                  - href: \"http://data.example.org/api\"\n                    rel: service-desc\n                    type: application/vnd.oai.openapi+json;version=3.0\n                    title: the API definition\n                  - href: \"http://data.example.org/api.html\"\n                    rel: service-doc\n                    type: text/html\n                    title: the API documentation\n                  - href: \"http://data.example.org/conformance\"\n                    rel: conformance\n                    type: application/json\n                    title: OGC API conformance classes implemented by this server\n                  - href: \"http://data.example.org/collections\"\n                    rel: data\n                    type: application/json\n                    title: Information about the feature collections\n  \"/collections\":\n    get:\n      tags:\n        - Collections\n      summary: the feature collections in the dataset\n      description: |-\n        A body of Feature Collections that belong or are used together with additional links.\n        Request may not return the full set of metadata per Feature Collection.\n      operationId: getCollections\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Collections\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n  \"/collections/{collectionId}\":\n    get:\n      tags:\n        - Collections\n      summary: |-\n        describe the feature collection with id `collectionId`\n      description: |-\n        A single Feature Collection for the given if `collectionId`.\n        Request this endpoint to get a full list of metadata for the Feature Collection.\n      operationId: describeCollection\n      parameters:\n        - $ref: \"#/components/parameters/collectionId\"\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Collection\"\n        \"404\":\n          $ref: \"#/components/responses/NotFound\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\ncomponents:\n  parameters:\n    collectionId:\n      name: collectionId\n      in: path\n      description: local identifier of a collection\n      required: true\n      schema:\n        type: string\n  schemas:\n    collections:\n      type: object\n      required:\n        - links\n        - collections\n      properties:\n        links:\n          $ref: \"../core/commons.yaml#/components/schemas/links\"\n        collections:\n          type: array\n          items:\n            $ref: \"../core/commons.yaml#/components/schemas/collection\"\n  responses:\n    Collections:\n      description: |-\n        The feature collections shared by this API.\n\n        The dataset is organized as one or more feature collections. This resource\n        provides information about and access to the collections.\n\n        The response contains the list of collections. For each collection, a link\n        to the items in the collection (path `/collections/{collectionId}/items`,\n        link relation `items`) as well as key information about the collection.\n        This information includes:\n\n        * A local identifier for the collection that is unique for the dataset;\n        * 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);\n        * An optional title and description for the collection;\n        * 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;\n        * An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').\n      content:\n        application/json:\n          schema:\n            $ref: \"#/components/schemas/collections\"\n    Collection:\n      description: |-\n        Information about the feature collection with id `collectionId`.\n\n        The response contains a link to the items in the collection\n        (path `/collections/{collectionId}/items`, link relation `items`)\n        as well as key information about the collection. This information\n        includes:\n\n        * A local identifier for the collection that is unique for the dataset;\n        * 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);\n        * An optional title and description for the collection;\n        * 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;\n        * An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').\n      content:\n        application/json:\n          schema:\n            $ref: \"../core/commons.yaml#/components/schemas/collection\"\n    NotFound:\n      description: |-\n        The requested URI was not found.\n"
  },
  {
    "path": "ogcapi-features/openapi-features.yaml",
    "content": "openapi: 3.0.3\ninfo:\n  title: STAC API - Features\n  version: v1.0.0\n  description: >-\n    This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Features\n    specification. This extends OGC API - Features - Part 1: Core.\n  contact:\n    name: STAC Specification\n    url: \"http://stacspec.org\"\n  license:\n    name: Apache License 2.0\n    url: \"http://www.apache.org/licenses/LICENSE-2.0\"\n  x-conformance-classes: [\"https://api.stacspec.org/v1.0.0/ogcapi-features\"]\ntags:\n  - name: Features\n    description: |-\n      All endpoints related to OGC API - Features - Part 1: Core\npaths:\n  \"/\":\n    get:\n      tags:\n        - Features\n      summary: landing page\n      description: |-\n        The landing page provides links to the sub-resources.\n      operationId: getLandingPage\n      responses:\n        \"200\":\n          description: |-\n            The landing page provides links to the API definition\n            (link relations `service-desc` and `service-doc`),\n            the Conformance declaration (path `/conformance`,\n            link relation `conformance`), and the Feature\n            Collections (path `/collections`, link relation\n            `data`).\n          content:\n            application/json:\n              schema:\n                $ref: \"../core/openapi.yaml#/components/schemas/landingPage\"\n              example:\n                stac_version: \"1.0.0\"\n                type: Catalog\n                id: sentinel\n                title: Copernicus Sentinel Imagery\n                description: Catalog of Copernicus Sentinel 1 and 2 imagery.\n                conformsTo:\n                  - \"https://api.stacspec.org/v1.0.0/core\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30\"\n                  - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson\"\n                links:\n                  - href: \"http://data.example.org/\"\n                    rel: self\n                    type: application/json\n                    title: this document\n                  - href: \"http://data.example.org/api\"\n                    rel: service-desc\n                    type: application/vnd.oai.openapi+json;version=3.0\n                    title: the API definition\n                  - href: \"http://data.example.org/api.html\"\n                    rel: service-doc\n                    type: text/html\n                    title: the API documentation\n                  - href: \"http://data.example.org/conformance\"\n                    rel: conformance\n                    type: application/json\n                    title: OGC API conformance classes implemented by this server\n                  - href: \"http://data.example.org/collections\"\n                    rel: data\n                    type: application/json\n                    title: Information about the feature collections\n  \"/conformance\":\n    get:\n      tags:\n        - Features\n      summary: information about specifications that this API conforms to\n      description: |-\n        A list of all conformance classes specified in a standard that the\n        server conforms to.\n      operationId: getConformanceDeclaration\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/ConformanceDeclaration\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n  \"/collections\":\n    get:\n      tags:\n        - Features\n      summary: the feature collections in the dataset\n      description: |-\n        A body of Feature Collections that belong or are used together with additional links.\n        Request may not return the full set of metadata per Feature Collection.\n      operationId: getCollections\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Collections\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n  \"/collections/{collectionId}\":\n    get:\n      tags:\n        - Features\n      summary: |-\n        describe the feature collection with id `collectionId`\n      description: |-\n        A single Feature Collection for the given if `collectionId`.\n        Request this endpoint to get a full list of metadata for the Feature Collection.\n      operationId: describeCollection\n      parameters:\n        - $ref: \"#/components/parameters/collectionId\"\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Collection\"\n        \"404\":\n          $ref: \"#/components/responses/NotFound\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n  \"/collections/{collectionId}/items\":\n    get:\n      tags:\n        - Features\n      summary: fetch features\n      description: |-\n        Fetch features of the feature collection with id `collectionId`.\n\n        Every feature in a dataset belongs to a collection. A dataset may\n        consist of multiple feature collections. A feature collection is often a\n        collection of features of a similar type, based on a common schema.\n      operationId: getFeatures\n      parameters:\n        - $ref: \"#/components/parameters/collectionId\"\n        - $ref: \"#/components/parameters/limit\"\n        - $ref: \"#/components/parameters/bbox\"\n        - $ref: \"#/components/parameters/datetime\"\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Features\"\n        \"404\":\n          $ref: \"#/components/responses/NotFound\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n  \"/collections/{collectionId}/items/{featureId}\":\n    get:\n      tags:\n        - Features\n      summary: fetch a single feature\n      description: |-\n        Fetch the feature with id `featureId` in the feature collection\n        with id `collectionId`.\n      operationId: getFeature\n      parameters:\n        - $ref: \"#/components/parameters/collectionId\"\n        - $ref: \"#/components/parameters/featureId\"\n      responses:\n        \"200\":\n          $ref: \"#/components/responses/Feature\"\n        \"404\":\n          $ref: \"#/components/responses/NotFound\"\n        \"4XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\n        \"5XX\":\n          $ref: \"../core/commons.yaml#/components/responses/Error\"\ncomponents:\n  parameters:\n    bbox:\n      name: bbox\n      in: query\n      description: |-\n        Only features that have a geometry that intersects the bounding box are selected.\n        The bounding box is provided as four or six numbers, depending on whether the\n        coordinate reference system includes a vertical axis (height or depth):\n\n        * Lower left corner, coordinate axis 1\n        * Lower left corner, coordinate axis 2\n        * Minimum value, coordinate axis 3 (optional)\n        * Upper right corner, coordinate axis 1\n        * Upper right corner, coordinate axis 2\n        * Maximum value, coordinate axis 3 (optional)\n\n        The coordinate reference system of the values is WGS 84 longitude/latitude\n        (http://www.opengis.net/def/crs/OGC/1.3/CRS84).\n\n        For WGS 84 longitude/latitude the values are in most cases the sequence of\n        minimum longitude, minimum latitude, maximum longitude and maximum latitude.\n        However, in cases where the box spans the antimeridian the first value\n        (west-most box edge) is larger than the third value (east-most box edge).\n\n        If the vertical axis is included, the third and the sixth number are\n        the bottom and the top of the 3-dimensional bounding box.\n\n        If a feature has multiple spatial geometry properties, it is the decision of the\n        server whether only a single spatial geometry property is used to determine\n        the extent or all relevant geometries.\n      required: false\n      schema:\n        type: array\n        oneOf:\n          - minItems: 4\n            maxItems: 4\n          - minItems: 6\n            maxItems: 6\n        items:\n          type: number\n      style: form\n      explode: false\n    collectionId:\n      name: collectionId\n      in: path\n      description: local identifier of a collection\n      required: true\n      schema:\n        type: string\n    datetime:\n      name: datetime\n      in: query\n      description: |-\n        Either a date-time or an interval, open or closed. Date and time expressions\n        adhere to RFC 3339. Open intervals are expressed using double-dots.\n\n        Examples:\n\n        * A date-time: \"2018-02-12T23:20:50Z\"\n        * A closed interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n        * Open intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n\n        Only features that have a temporal property that intersects the value of\n        `datetime` are selected.\n\n        If a feature has multiple temporal properties, it is the decision of the\n        server whether only a single temporal property is used to determine\n        the extent or all relevant temporal properties.\n      required: false\n      schema:\n        type: string\n      style: form\n      explode: false\n    featureId:\n      name: featureId\n      in: path\n      description: local identifier of a feature\n      required: true\n      schema:\n        type: string\n    limit:\n      name: limit\n      in: query\n      description: |-\n        The optional limit parameter recommends the number of items that should be present in the response document.\n\n        If the limit parameter value is greater than advertised limit maximum, the server must return the\n        maximum possible number of items, rather than responding with an error.\n\n        Only items are counted that are on the first level of the collection in the response document.\n        Nested objects contained within the explicitly requested items must not be counted.\n\n        Minimum = 1. Maximum = 10000. Default = 10.\n      required: false\n      schema:\n        type: integer\n        minimum: 1\n        maximum: 10000\n        default: 10\n      style: form\n      explode: false\n  schemas:\n    collections:\n      type: object\n      required:\n        - links\n        - collections\n      properties:\n        links:\n          $ref: \"../core/commons.yaml#/components/schemas/links\"\n        collections:\n          type: array\n          items:\n            $ref: \"../core/commons.yaml#/components/schemas/collection\"\n    featureCollectionGeoJSON:\n      allOf:\n        - $ref: \"../core/commons.yaml#/components/schemas/featureCollectionGeoJSON\"\n        - type: object\n          required:\n            - features\n          properties:\n            features:\n              type: array\n              items:\n                $ref: \"../core/commons.yaml#/components/schemas/item\"\n            links:\n              $ref: \"../core/commons.yaml#/components/schemas/links\"\n            timeStamp:\n              $ref: \"#/components/schemas/timeStamp\"\n            numberMatched:\n              $ref: \"#/components/schemas/numberMatched\"\n            numberReturned:\n              $ref: \"#/components/schemas/numberReturned\"\n    numberMatched:\n      description: |-\n        The number of features of the feature type that match the selection\n        parameters like `bbox`.\n      type: integer\n      minimum: 0\n      example: 127\n    numberReturned:\n      description: |-\n        The number of features in the feature collection.\n\n        A server may omit this information in a response, if the information\n        about the number of features is not known or difficult to compute.\n\n        If the value is provided, the value must be identical to the number\n        of items in the \"features\" array.\n      type: integer\n      minimum: 0\n      example: 10\n    timeStamp:\n      description: This property indicates the time and date when the response was generated.\n      type: string\n      format: date-time\n      example: \"2017-08-17T08:05:32Z\"\n  responses:\n    ConformanceDeclaration:\n      description: |-\n        The URIs of all conformance classes supported by the server.\n\n        To support \"generic\" clients that want to access multiple\n        OGC API Features implementations - and not \"just\" a specific\n        API / server, the server declares the conformance\n        classes it implements and conforms to.\n      content:\n        application/json:\n          schema:\n            $ref: \"../core/commons.yaml#/components/schemas/conformanceClasses\"\n          example:\n            conformsTo:\n              - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core\"\n              - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30\"\n              - \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson\"\n    Collections:\n      description: |-\n        The feature collections shared by this API.\n\n        The dataset is organized as one or more feature collections. This resource\n        provides information about and access to the collections.\n\n        The response contains the list of collections. For each collection, a link\n        to the items in the collection (path `/collections/{collectionId}/items`,\n        link relation `items`) as well as key information about the collection.\n        This information includes:\n\n        * A local identifier for the collection that is unique for the dataset;\n        * 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);\n        * An optional title and description for the collection;\n        * 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;\n        * An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').\n      content:\n        application/json:\n          schema:\n            $ref: \"#/components/schemas/collections\"\n    Collection:\n      description: |-\n        Information about the feature collection with id `collectionId`.\n\n        The response contains a link to the items in the collection\n        (path `/collections/{collectionId}/items`, link relation `items`)\n        as well as key information about the collection. This information\n        includes:\n\n        * A local identifier for the collection that is unique for the dataset;\n        * 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);\n        * An optional title and description for the collection;\n        * 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;\n        * An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').\n      content:\n        application/json:\n          schema:\n            $ref: \"../core/commons.yaml#/components/schemas/collection\"\n    Features:\n      description: |-\n        The response is a document consisting of features in the collection.\n        The features included in the response are determined by the server\n        based on the query parameters of the request. To support access to\n        larger collections without overloading the client, the API supports\n        paged access with links to the next page, if more features are selected\n        that the page size.\n\n        The `bbox` and `datetime` parameter can be used to select only a\n        subset of the features in the collection (the features that are in the\n        bounding box or time interval). The `bbox` parameter matches all features\n        in the collection that are not associated with a location, too. The\n        `datetime` parameter matches all features in the collection that are\n        not associated with a time stamp or interval, too.\n\n        The `limit` parameter may be used to control the subset of the\n        selected features that should be returned in the response, the page size.\n        Each page may include information about the number of selected and\n        returned features (`numberMatched` and `numberReturned`) as well as\n        links to support paging (link relation `next`).\n      content:\n        application/geo+json:\n          schema:\n            $ref: \"#/components/schemas/featureCollectionGeoJSON\"\n    Feature:\n      description: |-\n        fetch the feature with id `featureId` in the feature collection\n        with id `collectionId`\n      content:\n        application/geo+json:\n          schema:\n            $ref: \"../core/commons.yaml#/components/schemas/item\"\n    NotFound:\n      description: |-\n        The requested URI was not found.\n"
  },
  {
    "path": "overview.md",
    "content": "# About\n\nThe STAC API family of specifications define a JSON-based web API to browse and query [SpatioTemporal Asset Catalog](stac-spec/)\n(STAC) objects. While the core STAC specification provides a structure and language to describe assets, users\nusually want to access\na subset of the entire catalog, such as for a certain date range, in a particular area of interest, or\nmatching metadata properties. STAC API extensions specify those query parameters, and compliant servers return STAC [Item](stac-spec/item-spec/README.md)\nobjects that\nmatch the user's query. Additional functionality can be added through the [OGC API](https://ogcapi.ogc.org/) family of\nstandards, particularly [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) (OAFeat, for our\nshorthand).  Notes on implementation recommendations may be found [here](implementation.md).\n\n## STAC API Description\n\n### Core\n\nThe [Core](core/) of STAC API returns a valid [STAC Catalog](stac-spec/catalog-spec/catalog-spec.md) and a description\nof STAC API specifications to which it conforms. The `links` section of the Catalog is the jumping-off\npoint for the more powerful capabilities - it contains a list of URLs with link\n'relationships' (`rel`) and descriptions to indicate their functionality. Note that the [STAC Core specification](stac-spec) provides\nmost of the content of API responses - the STAC API is primarily concerned with the return of STAC\n[Item](stac-spec/item-spec/README.md) and [Collection](stac-spec/collection-spec/README.md) objects via a\nweb API.  See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0/core) for more details.\n\nThere are then two major sets of functionality that build on the core, [Item Search](item-search) and [Collection and Features](ogcapi-features)\n, which are designed to be complementary, letting\nimplementations choose which parts they want to utilize.\n\n### Item Search\n\nThe [Item Search](item-search) functionality is one of the most common, provided by the `search` rel\nlocated at a `/search` endpoint. It re-uses all of the OAFeat [query\nparameters](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) specified in their 'core', and adds a\nfew more. It does not require a full implementation of OAFeat, but it is instead a simplified construct that can run a\nsearch across any group of STAC [`Item`](stac-spec/item-spec/README.md) objects. See the [rendered OpenAPI\ndocument](https://api.stacspec.org/v1.0.0/item-search) for more details.\n\n### Collections and Features\n\nThe other major functionality for a STAC API is to [serve STAC Collection and Item](ogcapi-features) objects through\nthe [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) endpoints. This enables any OAFeat client\nto access STAC Item objects in the same way they do any other data. Every STAC Collection becomes available at the\n`/collections` endpoint (making this a superset of the Collections functionality), with each\n`/collections/{collectionId}/items` endpoint allowing search of the items\nin that single collection. For STAC, this means implementing [OGC API - Features\nCore](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_core), as well as\nthe OAFeat [GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson),\nsince STAC objects are by definition also GeoJSON objects.\nFull compliance involves splitting STAC `Item` objects into\nindividual `/collections/{collectionId}/items` endpoints that expose querying single collections, as OAFeat does\nnot currently support cross-collection search. It also adds a few other requirements, which are highlighted in the\n[features description](ogcapi-features/), in order to help STAC implementors understand OAFeat without having to\nread the full specification from scratch. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0/ogcapi-features)\nfor more details.\n\n### Extensions & Fragments\n\nBoth STAC API and OAFeat allow 'extensions' that can be added for additional functionality. The STAC community has\ncreated [a number of extensions](https://stac-api-extensions.github.io) to OAFeat\nin order to meet the requirements of its implementors. Additional details about extensions can be found in the [extensions document](extensions.md).\nThese are specified in OpenAPI, which works cleanly when the new functionality is a new API location (a complete\nresource, or adding POST to an existing one). Many of the additions, however, are done at the parameter or response\nlevel, like adding a `sortby` field to return ordered results.\n\nEach *extension* is made specifically against a part of the STAC API, so that it can be specified as a conformance\nclass (e.g., that Item Search is being extended to support `sortby` but not Features). \n\nWe are working to fully align STAC's OAFeat extensions to be the same as the OGC API building blocks being worked on\nso that every STAC extension is specified at the OGC API level. The end goal is for STAC API to just present a\ncurated set of extension options.\n\n## STAC Core and OGC Versions\n\nThis 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).\nFuture versions will likely depend on [OGC API Common](https://github.com/opengeospatial/ogcapi-common) and additional parts of\nFeatures as components evolve and mature.\n\nThis 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\ndesigned to work with STAC 2.0 and above (since we use [SemVer](https://semver.org/) it may introduce backwards incompatible changes).\nThe STAC API spec is released with the latest stable STAC core specification version included in the [`/stac-spec`](stac-spec/)\ndirectory as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). To determine which version it is, just check the\n[`/stac-spec/CHANGELOG.md`](stac-spec/CHANGELOG.md) for the topmost version & release date.\n\n## Endpoints\n\nSTAC APIs follow the modern web API practices of using HTTP Request Methods (\"verbs\") and\nthe `Content-Type` header to drive behavior on resources (\"nouns\") in the endpoints listed below.\n\nThe following table describes the service resources available in a STAC API implementation that\nsupports all three of the foundation specifications. Note that the 'Endpoint'\ncolumn is more of an example in some cases. OGC API makes some endpoint locations required, those will be bolded below.\n\n| Endpoint                                        | Specified in                                                  | Link Relationship | Returns                                                                                             | Description                                                                                                                                |\n| ----------------------------------------------- | ------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `/`                                             | [Core](core/)                                                 | root              | [Catalog](stac-spec/catalog-spec/catalog-spec.md)                                                   | Extends `/` from OAFeat to return a full STAC catalog.                                                                                     |\n| `/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 |\n| `/collections`                                  | [Features](ogcapi-features/), [Collections](ogcapi-features/) | data              | JSON                                                                                                | Object with a list of Collection objects contained in the catalog and links                                                                |\n| `/conformance`                                  | [Features](ogcapi-features/)                                  | conformance       | JSON                                                                                                | Info about standards to which the API conforms                                                                                             |\n| `/api`                                          | [Features](ogcapi-features/)                                  | service-desc      | any                                                                                                 | The description of the endpoints in this service                                                                                           |\n| `/collections/{collectionId}`                   | [Features](ogcapi-features/), [Collections](ogcapi-features/) | collection        | Collection                                                                                          | Returns single Collection JSON                                                                                                             |\n| `/collections/{collectionId}/items`             | [Features](ogcapi-features/)                                  | items             | ItemCollection                                                                                      | GeoJSON FeatureCollection-conformant entity of Item objects in collection                                                                  |\n| `/collections/{collectionId}/items/{featureId}` | [Features](ogcapi-features/)                                  | item              | Returns single Item (GeoJSON Feature). This relation is usually not used in OAFeat implementations. |\n\n## Conformance Classes\n\nSTAC API is evolving to utilize OAFeat's\n[Conformance](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes)\nJSON structure. For\nSTAC API, we declare new STAC conformance classes, with the core ones detailed in the table below. [STAC\nFeatures](ogcapi-features/) requires the core OAFeat conformance classes and declares that those endpoints return\nSTAC Collection and Feature objects.\nThe core STAC conformance classes communicate the conformance JSON only in the root (`/`) document, while OGC API\nrequires they also live at the `/conformance` endpoint. STAC's conformance structure is detailed in the\n[core](core/). Note all\nconformance URIs serve up a rendered HTML version of the corresponding OpenAPI document at the given location.\n\n### Conformance Class Table\n\n| **Name**               | **Specified in**                            | **Conformance URI**                               | **Description**                                                                                                 |\n| ---------------------- | ------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| STAC API - Core        | [Core](core)                                | <https://api.stacspec.org/v1.0.0/core>            | Specifies the STAC Landing page `/`, communicating conformance and available endpoints.                         |\n| STAC API - Item Search | [Item Search](item-search)                  | <https://api.stacspec.org/v1.0.0/item-search>     | Enables search of all STAC Item objects on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. |\n| STAC API - Features    | [Collections and Features](ogcapi-features) | <https://api.stacspec.org/v1.0.0/ogcapi-features> | Specifies the use of OGC API - Features to serve STAC Item and Collection objects                               |\n| STAC API - Collections | [Collections and Features](ogcapi-features) | <https://api.stacspec.org/v1.0.0/collections>     | Specifies the use of a subset of STAC API - Features to serve Collection objects                                |\n\nAdditional conformance classes can be specified by [STAC API Extensions](extensions.md).\n\n## Example Landing Page\n\nWhen all three conformance classes (Core, Features, Item Search) are implemented, the relationships among\nvarious resources are shown in the following diagram. In each node, there is also a `self` and `root` link\nthat are not depicted to keep the diagram more concise.\n\n![Diagram of STAC link relations](stac-api.png)\n\nThe Landing Page will at least have the following `conformsTo` and `links`:\n\n```json\n{\n    \"stac_version\": \"1.0.0\",\n    \"id\": \"example-stac\",\n    \"title\": \"A simple STAC API Example\",\n    \"description\": \"This Catalog aims to demonstrate the a simple landing page\",\n    \"type\": \"Catalog\",\n    \"conformsTo\" : [\n        \"https://api.stacspec.org/v1.0.0/core\",\n        \"https://api.stacspec.org/v1.0.0/collections\",\n        \"https://api.stacspec.org/v1.0.0/ogcapi-features\",\n        \"https://api.stacspec.org/v1.0.0/item-search\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30\",\n        \"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson\"\n    ],\n    \"links\": [\n        {\n            \"rel\": \"self\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"root\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com\"\n        },\n        {\n            \"rel\": \"conformance\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/conformance\"\n        },\n        {\n            \"rel\": \"service-desc\",\n            \"type\": \"application/vnd.oai.openapi+json;version=3.0\",\n            \"href\": \"https://stac-api.example.com/api\"\n        },\n        {\n            \"rel\": \"service-doc\",\n            \"type\": \"text/html\",\n            \"href\": \"https://stac-api.example.com/api.html\"\n        },\n        {\n            \"rel\": \"data\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/collections\"\n        },\n        {\n            \"rel\": \"child\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/collections/sentinel-2\",\n        },\n        {\n            \"rel\": \"child\",\n            \"type\": \"application/json\",\n            \"href\": \"https://stac-api.example.com/collections/landsat-8\",\n        },\n        {\n            \"rel\": \"search\",\n            \"type\": \"application/geo+json\",\n            \"href\": \"https://stac-api.example.com/search\"\n        }\n    ]\n}\n```\n"
  },
  {
    "path": "package.json",
    "content": "{\n    \"name\": \"api-spec\",\n    \"version\": \"v1.0.0\",\n    \"description\": \"STAC API helpers to generate, serve and check the API spec.\",\n    \"repository\": \"https://github.com/radiantearth/stac-api-spec\",\n    \"license\": \"Apache-2.0\",\n    \"scripts\": {\n        \"serve\": \"redoc-cli serve core/openapi.yaml --watch --options.expandResponses \\\"200,201,202,203,204\\\" --options.pathInMiddlePanel true\",\n        \"check\": \"npm run check-markdown && npm run check-openapi\",\n        \"check-markdown\": \"remark . --frail --ignore-pattern stac-spec/\",\n        \"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\",\n        \"check-openapi-core\": \"spectral lint core/openapi.yaml --ruleset .circleci/.spectral.yml\",\n        \"check-openapi-commons\": \"spectral lint core/commons.yaml --ruleset .circleci/.spectral-fragments.yml\",\n        \"check-openapi-ogcapi-features\": \"spectral lint ogcapi-features/openapi-features.yaml ogcapi-features/openapi-collections.yaml --ruleset .circleci/.spectral.yml\",\n        \"check-openapi-item-search\": \"spectral lint item-search/openapi.yaml --ruleset .circleci/.spectral.yml\",\n        \"check-openapi-fragments\": \"spectral lint fragments/*/openapi.yaml --ruleset .circleci/.spectral-fragments.yml\",\n        \"build-openapi\": \".circleci/build-openapi.sh\",\n        \"publish-openapi\": \"node .circleci/publish.js\",\n        \"check-stac-spec-changes\": \"git diff --quiet HEAD ${npm_config_compare_to} -- stac-spec\"\n    },\n    \"dependencies\": {\n        \"@redocly/openapi-cli\": \"^1.0.0-beta.94\",\n        \"@stoplight/spectral-cli\": \"^6.6.0\",\n        \"gh-pages\": \"^5.0.0\",\n        \"redoc-cli\": \"^0.13.21\",\n        \"remark-cli\": \"^11.0.0\",\n        \"remark-lint\": \"^9.1.1\",\n        \"remark-gfm\": \"^3.0.1\",\n        \"remark-lint-no-html\": \"^3.1.1\",\n        \"remark-preset-lint-consistent\": \"^5.1.1\",\n        \"remark-preset-lint-markdown-style-guide\": \"^5.1.2\",\n        \"remark-preset-lint-recommended\": \"^6.1.2\",\n        \"remark-validate-links\": \"^12.1.0\"\n    },\n    \"remarkConfig\": {\n        \"plugins\": [\n            \"remark-gfm\",\n            \"validate-links\",\n            \"remark-preset-lint-consistent\",\n            \"remark-preset-lint-markdown-style-guide\",\n            \"remark-preset-lint-recommended\",\n            \"lint-no-html\",\n            [\n                \"remark-lint-emphasis-marker\",\n                \"*\"\n            ],\n            \"remark-lint-hard-break-spaces\",\n            \"remark-lint-blockquote-indentation\",\n            \"remark-lint-no-consecutive-blank-lines\",\n            [\n                \"remark-lint-maximum-line-length\",\n                150\n            ],\n            [\n                \"remark-lint-fenced-code-flag\",\n                false\n            ],\n            \"remark-lint-fenced-code-marker\",\n            \"remark-lint-no-shell-dollars\",\n            [\n                \"remark-lint-code-block-style\",\n                \"fenced\"\n            ],\n            \"remark-lint-heading-increment\",\n            \"remark-lint-no-multiple-toplevel-headings\",\n            \"remark-lint-no-heading-punctuation\",\n            [\n                \"remark-lint-maximum-heading-length\",\n                70\n            ],\n            [\n                \"remark-lint-heading-style\",\n                \"atx\"\n            ],\n            [\n                \"remark-lint-no-shortcut-reference-link\",\n                false\n            ],\n            \"remark-lint-list-item-bullet-indent\",\n            \"remark-lint-ordered-list-marker-style\",\n            \"remark-lint-ordered-list-marker-value\",\n            \"remark-lint-checkbox-character-style\",\n            [\n                \"remark-lint-unordered-list-marker-style\",\n                \"-\"\n            ],\n            [\n                \"remark-lint-list-item-indent\",\n                \"space\"\n            ],\n            \"remark-lint-table-pipes\",\n            \"remark-lint-no-literal-urls\",\n            [\n                \"remark-lint-no-file-name-irregular-characters\",\n                false\n            ],\n            [\n                \"remark-lint-list-item-spacing\",\n                false\n            ]\n        ]\n    }\n}"
  },
  {
    "path": "stac-api.gv",
    "content": "# All have self link to self (self edge)\n# All have root link to root\n\ndigraph g {\n    label = <STAC API Links>;\n    labelloc = \"t\"; \n    fontsize = \"24\"\n \n    graph [\n        rankdir = \"LR\"\n    ];\n\n    node [\n        fontsize = \"16\"\n        shape = \"ellipse\"\n    ];\n\n    edge [\n    ];\n\n    \"/\" [\n        label = \"Landing Page\\n/|<l9>links[rel=conformance]\\l|<l8>links[rel=service-doc]\\l|<l7>links[rel=service-desc]\\l|<l3>links[rel=data]\\l|<l4>links[rel=child]\\l|<l5>links[rel=child]\\l|<l6>links[rel=search]\\l\"\n        shape = \"record\"\n     ];\n\n    \"collections\" [\n        label = \"<f0> Collections\\n/collections|<c1>collections[0].links[rel=self]\\l|<c2>collections[1].links[rel=self]\\l\"\n        shape = \"record\"\n    ];\n\n    \"collectionY\" [\n        label = \"<f0> Collection y\\n/collections/y|<l0>links[rel=items]\\l\"\n        shape = \"record\"\n    ];\n\n    \"collectionX\" [\n        label = \"<f0> Collection x\\n/collections/x|<l0>links[rel=items]\\l\"\n        shape = \"record\"\n    ];\n\n    \"service-desc\" [\n        label = \"OpenAPI Spec\\n/api\"\n        shape = \"record\"\n    ];\n\n    \"service-doc\" [\n        label = \"Service Doc\\n/api.html\"\n        shape = \"record\"\n    ];\n\n    \"conformance\" [\n        label = \"Conformance\\n/conformance\"\n        shape = \"record\"\n    ];\n\n    \"collectionY-items\" [\n        label = \"<f0> Collection y Items\\n/collections/y/items|<f1> features[0].links[rel=self]\"\n        shape = \"record\"\n    ];\n\n    \"collectionX-items\" [\n        label = \"<f0> Collection x Items\\n/collections/x/items|<f1> features[0].links[rel=self]\"\n        shape = \"record\"\n    ];\n\n    \"collectionY-item1\" [\n        label = \"<f0> Item y:1\\n/collections/y/items/1|<l0>links[rel=parent]\\l|<l1>links[rel=collection]\\l\"\n        shape = \"record\"\n    ];\n\n    \"collectionX-item1\" [\n        label = \"<f0> Item x:1\\n/collections/x/items/1|<l0>links[rel=parent]\\l|<l1>links[rel=collection]\\l\"\n        shape = \"record\"\n    ];\n\n    \"item-search\" [\n        label = \"<f0> Item Search\\n/items|<f1>features[0].links[rel=self]\\l|<f2>features[1].links[rel=self]\\l\"\n        shape = \"record\"\n    ];\n\n    \"/\":l3 -> \"collections\":f0;\n    \"/\":l4 -> \"collectionX\":f0;\n    \"/\":l5 -> \"collectionY\":f0;\n    \"/\":l6 -> \"item-search\":f0;\n    \"/\":l7 -> \"service-desc\";\n    \"/\":l8 -> \"service-doc\";\n    \"/\":l9 -> \"conformance\";\n    \n    \"item-search\":f1 -> \"collectionX-item1\":f0;\n    \"item-search\":f2 -> \"collectionY-item1\":f0;\n\n    \"collections\":c2 -> \"collectionY\":f0;\n    \"collections\":c1 -> \"collectionX\":f0;\n\n    \"collectionY\":l0 -> \"collectionY-items\":f0;\n    \"collectionY-items\":f1 -> \"collectionY-item1\":f0;\n    cxi2 [shape=point,width=0.01,height=0.01];\n    cxi2 -> \"collectionY\":f0;\n\t\"collectionY-item1\":l0 -> cxi2 [dir=none];\n\t\"collectionY-item1\":l1 -> cxi2 [dir=none];\n\n    \"collectionX\":l0 -> \"collectionX-items\":f0;\n    \"collectionX-items\":f1 -> \"collectionX-item1\":f0;\n    cxi1 [shape=point,width=0.01,height=0.01];\n    cxi1 -> \"collectionX\":f0;\n\t\"collectionX-item1\":l0 -> cxi1 [dir=none];\n\t\"collectionX-item1\":l1 -> cxi1 [dir=none];\n\n \n}\n"
  },
  {
    "path": "stac-spec/.circleci/config.yml",
    "content": "version: 2\njobs:\n  test_examples_node:\n    working_directory: ~/stac\n    docker:\n      - image: circleci/node:12\n    steps:\n      - checkout\n      - run:\n          name: install\n          command: npm install\n      - run:\n          name: validate\n          command: npm run check-examples\n  # test_examples_python:\n  #   working_directory: ~/stac\n  #   docker:\n  #     - image: circleci/python:3.8\n  #   steps:\n  #     - checkout\n  #     - run:\n  #         name: install\n  #         command: pip install stac-validator\n  #     - run:\n  #         name: validate\n  #         command: find ./examples -type f -name \"*.json\" | xargs -L1 stac_validator         \n  test_docs:\n    working_directory: ~/stac\n    docker:\n      - image: circleci/node:12\n    steps:\n      - checkout\n      - run:\n          name: install\n          command: npm install\n      - run:\n          name: validate\n          command: npm run check-markdown\n  publish_schemas:\n    working_directory: ~/stac\n    docker:\n      - image: circleci/node:12\n    steps:\n      - checkout\n      - run:\n          name: install\n          command: npm install\n      - add_ssh_keys:\n          fingerprints:\n            - \"9b:0a:88:ff:12:d1:29:9a:ff:bb:72:ab:7d:81:df:59\"\n      - run:\n          name: publish\n          command: npm run publish-schemas -- $CIRCLE_TAG\nworkflows:\n  version: 2\n  ci:\n    jobs:\n      - test_examples_node\n      # - test_examples_python   \n      - test_docs\n      - publish_schemas:\n          filters:\n            tags:\n              only: /^v.*/\n            branches:\n              ignore: /^((?!dev).)*$/"
  },
  {
    "path": "stac-spec/.circleci/publish-schemas.js",
    "content": "const klaw = require('klaw-sync');\nconst path = require('path');\nconst fs = require('fs');\nconst ghpages = require('gh-pages');\n\nfunction filterFn (item) {\n\tconst basename = path.basename(item.path);\n\treturn basename === '.' || basename === 'node_modules' || basename[0] !== '.';\n}\n\nlet args = process.argv.slice(2);\nlet tag = 'dev';\nif (args.length && args[0].trim().length > 0) {\n\ttag = args[0];\n}\n\nvar folder = '.';\nvar jsonSchemaFolderPattern = path.sep + 'json-schema' + path.sep;\nfor (let file of klaw(folder, {filter: filterFn})) {\n\tif (file.path.includes(jsonSchemaFolderPattern) && path.extname(file.path) === '.json') {\n\t\tlet source = file.path;\n\t\tlet target = 'schemas' + path.sep + tag + path.sep + path.relative(folder, file.path);\n\t\tfs.mkdirSync(path.dirname(target), { recursive: true });\n\t\tfs.copyFileSync(source, target);\n\t\tconsole.log(target);\n\t}\n}\n\nghpages.publish('schemas/' + tag, {\n\tsrc: '**',\n\tdest: tag,\n\tmessage: 'Publish JSON Schemas [ci skip]',\n\tuser: {\n\t  name: 'STAC CI',\n\t  email: 'ci@stacspec.org'\n\t}\n}, error => {\n\tconsole.error(error ? error : 'Deployed to gh-pages');\n\tprocess.exit(error ? 1 : 0);\n});"
  },
  {
    "path": "stac-spec/.circleci/rc.yaml",
    "content": "plugins:\n# Check links\n  - validate-links\n# Apply some recommended defaults for consistency\n  - remark-preset-lint-consistent\n  - remark-preset-lint-recommended\n  - lint-no-html\n# General formatting\n  - - remark-lint-emphasis-marker\n    - '*'\n  - remark-lint-hard-break-spaces\n  - remark-lint-blockquote-indentation\n  - remark-lint-no-consecutive-blank-lines\n  - - remark-lint-maximum-line-length\n    - 150\n# Code\n  - remark-lint-fenced-code-flag\n  - remark-lint-fenced-code-marker\n  - remark-lint-no-shell-dollars\n  - - remark-lint-code-block-style\n    - 'fenced'\n# Headings\n  - remark-lint-heading-increment\n  - remark-lint-no-multiple-toplevel-headings\n  - remark-lint-no-heading-punctuation\n  - - remark-lint-maximum-heading-length\n    - 70\n  - - remark-lint-heading-style\n    - atx\n  - - remark-lint-no-shortcut-reference-link\n    - false\n# Lists\n  - remark-lint-list-item-bullet-indent\n  - remark-lint-ordered-list-marker-style\n  - remark-lint-ordered-list-marker-value\n  - remark-lint-checkbox-character-style\n  - - remark-lint-unordered-list-marker-style\n    - '-'\n  - - remark-lint-list-item-indent\n    - space \n# Tables\n  - remark-lint-table-pipes\n  - remark-lint-no-literal-urls"
  },
  {
    "path": "stac-spec/.github/pull_request_template.md",
    "content": "**Related Issue(s):** #\n\n\n**Proposed Changes:**\n\n1. \n2. \n\n**PR Checklist:**\n\n- [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master).\n- [ ] This PR has **no** breaking changes.\n- [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-spec/blob/dev/CHANGELOG.md)\n      **or** a CHANGELOG entry is not required.\n- [ ] This PR affects the [STAC API spec](https://github.com/radiantearth/stac-api-spec),\n      and I have opened issue/PR #XXX to track the change.\n"
  },
  {
    "path": "stac-spec/.gitignore",
    "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Runtime data\npids\n*.pid\n*.seed\n*.pid.lock\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nlib-cov\n\n# Coverage directory used by tools like istanbul\ncoverage\n\n# nyc test coverage\n.nyc_output\n\n# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)\n.grunt\n\n# Bower dependency directory (https://bower.io/)\nbower_components\n\n# node-waf configuration\n.lock-wscript\n\n# Compiled binary addons (https://nodejs.org/api/addons.html)\nbuild/Release\n\n# Dependency directories\nnode_modules/\njspm_packages/\npackage-lock.json\n\n# Typescript v1 declaration files\ntypings/\n\n# Optional npm cache directory\n.npm\n\n# Optional eslint cache\n.eslintcache\n\n# Optional REPL history\n.node_repl_history\n\n# Output of 'npm pack'\n*.tgz\n\n# Yarn Integrity file\n.yarn-integrity\n\n# dotenv environment variables file\n.env\n\n# next.js build output\n.next\n\n# IntelliJ IDEA files\n.idea/\n*.iml\n\n# Folder created when CI puhlishes JSON Schemas\nschemas/\n"
  },
  {
    "path": "stac-spec/CHANGELOG.md",
    "content": "<!--lint disable maximum-line-length-->\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)\nand this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [v1.0.0] - 2021-05-25\n\n### Added\n\n- Updated best practices to add a recommendation to include title in links where possible. ([#1133](https://github.com/radiantearth/stac-spec/pull/1133))\n\n### Changed\n\n- Updated version numbers for 1.0.0 release.\n- Final UML tweaks for latest changes. ([#1134](https://github.com/radiantearth/stac-spec/pull/1134))\n- 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))\n\n## [v1.0.0-rc.4] - 2021-05-11\n\n### Changed\n\n- 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))\n- 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))\n- Catalog and Collection JSON Schemas don't have a common JSON Schema any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122))\n\n### Removed \n\n- Catalogs don't support summaries any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122))\n\n### Fixed\n\n- Added clarification around when an extension should be included in `stac_extensions`. ([#1123](https://github.com/radiantearth/stac-spec/pull/1123))\n- JSON Schemas don't allow \"shortcuts\" for core extensions any longer. ([#1121](https://github.com/radiantearth/stac-spec/pull/1121))\n- Various examples fixes.\n\n## [v1.0.0-rc.3] - 2021-04-29\n\n### Added\n\n- Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045))\n- Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090))\n- 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))\n- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111))\n\n### Changed\n\n- 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))\n- Updated examples for automatic collection creation from code and validation ([#1080](https://github.com/radiantearth/stac-spec/pull/1080))\n- Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077))\n- The Stats Object for Summaries has been renamed to Range Object (no functional change). ([#1093](https://github.com/radiantearth/stac-spec/pull/1093))\n- `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))\n- Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106))\n- 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))\n- Clarified that leaving a field out is not equivalent to setting it as null. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111))\n\n## [v1.0.0-rc.2] - 2021-03-30\n\n### Changed\n\n- Required properties of type `string` require a minimum length of `1`. ([#1065](https://github.com/radiantearth/stac-spec/pull/1065))\n- `gsd` must be greater than 0. ([#1068](https://github.com/radiantearth/stac-spec/pull/1068))\n\n### Removed\n\n- 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))\n\n### Fixed\n\n- Examples\n- 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.\n- 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))\n\n## [v1.0.0-rc.1] - 2021-03-03\n\n### Added\n\n- 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))\n- Collection specification adds Assets (previously needed Collections Asset extension to do that). ([#1008](https://github.com/radiantearth/stac-spec/pull/1008))\n- 'via' and 'canonical' rel types are now options in Items. ([#884](https://github.com/radiantearth/stac-spec/pull/884))\n- 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))\n- '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))\n- There is a new recommendation to enable CORS. ([#940](https://github.com/radiantearth/stac-spec/pull/940))\n- A Best Practice section on 'requester pays' cloud buckets was added. ([#1021](https://github.com/radiantearth/stac-spec/pull/1021))\n- 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))\n- There is a new Best Practice recommendation to keep collections at consistent levels. ([#1009](https://github.com/radiantearth/stac-spec/pull/1009))\n\n### Changed\n\n- 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))\n- 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))\n- Enhanced the way the spec talks about ID's to encourage more global uniqueness. ([#883](https://github.com/radiantearth/stac-spec/pull/883))\n- 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))\n- 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))\n- 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))\n- Renamed \"Scientific Extension\" to \"Scientific Citation Extension\" ([#990](https://github.com/radiantearth/stac-spec/issues/990))\n- Relaxed the regular expression for DOIs in the scientific extension ([#910](https://github.com/radiantearth/stac-spec/issues/910))\n- `proj:geometry` allows all GeoJSON geometries instead of just a polygon. ([#995](https://github.com/radiantearth/stac-spec/pull/995))\n\n### Removed\n\n- 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))\n- 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))\n- 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))\n\n### Fixed\n\n- 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))\n\n## [v1.0.0-beta.2] - 2020-07-08\n\n### Added\n- JSON-schema file in the Point Cloud extension.\n\n### Changed\n- Clarification on null geometries, making bbox not required if a null geometry is used.\n- Multiple extents (bounding boxes / intervals) are allowed per Collection\n- 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.\n\n### Removed\n- Validation instructions\n\n### Fixed\n- Fixed several JSON Schemas\n- Fixed examples\n\n## [v1.0.0-beta.1] - 2020-05-29\n\n### Removed\n- 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.\n- proj4 string from proj extension\n- Various warnings about how the spec is very early and likely will change.\n- implementations.md (migrated to <https://stacspec.org>) and how-to-help.md (migrated to <https://github.com/stac-utils/stac-ecosystem>).\n- `commons` extension completely removed: Items should contain all properties and not default to a common set at the Collection level\n- 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.\n\n### Added\n- 'alternate' as a listed 'rel' type with recommended 'text/html' to communicate there is an html version.\n- Added a code of conduct based on github's template.\n- Overview document that gives a more explanatory discussion of the various parts of the spec and how they relate\n- Several new sections to 'best practices' document.\n- Added the ability to define Item properties under Assets (item-spec/item-spec.md)\n- Add `proj:shape` and `proj:transform` to the projections extension.\n- Collection-level assets extension\n- Instructions on how to run check-markdown locally\n- Timestamps extensions (adds fields `published`, `expires` and `unpublished`)\n- `created` and `updated` can be used in the assets to specify the creation / update times of the assets.\n- [Tiled Assets extension](https://github.com/stac-extensions/tiled-assets/blob/main/README.md), for representing data that has been split into tiles\n\n### Changed\n- [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\n- Moved item recommendations to best practices, and added a bit more in item spec about 'search'\n- Moved `eo:gsd` from `eo` extension to core `gsd` field in Item common metadata\n- `asset` extension renamed to `item-assets` and renamed `assets` field in Collections to `item_assets`\n- `item-assets` extension only requires any two fields to be available, not the two specific fields `title` and `type`\n- `datetime` allows `null` as value, but requires `start_datetime` and `end_datetime` then\n- Extensions `sat`, `scientific` and `view`: At least one field is required to be specified.\n- [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.\n- Improved several JSON Schemas\n\n### Fixed\n- Datacube extension: `cube:dimensions` was not flagged as required.\n\n## [v0.9.0] - 2020-02-26\n\n### Added\n- ItemCollection requires `stac_version` field, `stac_extensions` has also been added\n- A `description` field has been added to Item assets (also Asset definitions extension)\n- Field `mission` to [Common Metadata fields](item-spec/common-metadata.md)\n- Extensions:\n  - [Version Indicators extension](https://github.com/stac-extensions/version/blob/main/README.md), new `version` and `deprecated` fields in STAC Items and Collections\n  - Data Cube extension can be used in Collections, added new field `description`\n  - [Asset Extension](https://github.com/stac-extensions/item-assets/blob/main/README.md): new `description` and `roles` fields\n  - New [Projection Extension](https://github.com/stac-extensions/projection/blob/main/README.md) to describe Items with Assets that have an associated geospatial projection\n  - New [View Geometry Extension](https://github.com/stac-extensions/view/blob/main/README.md)\n- STAC API:\n  - 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\n  - Run `npm run serve` or `npm run serve-ext` to quickly render development versions of the OpenAPI spec in the browser\n- [Basics](item-spec/common-metadata.md#basics) added to Common Metadata definitions with new `description` field for\nItem properties\n- 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)\n- `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\n- Clarification text on HTTP verbs in STAC API\n\n### Changed\n- Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html)\n- Collection field `property` and the merge ability moved to a new extension 'Commons'\n- Added field `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`\n- Updated API yaml to clarify bbox filter should be implemented without brackets. Example: `bbox=160.6,-55.95,-170,-25.89`\n- Collection `summaries` merge array fields now\n- Several fields have been moved from extensions or item fields to the [Common Metadata fields](item-spec/common-metadata.md):\n  - `eo:platform` / `sar:platform` => `platform`\n  - `eo:instrument` / `sar:instrument` => `instruments`, also changed from string to array of strings\n  - `eo:constellation` / `sar:constellation` => `constellation`\n  - `dtr:start_datetime` => `start_datetime`\n  - `dtr:end_datetime` => `end_datetime`\n- Moved angle definitions from extensions `eo` and new `view` extension\n  - `eo:off_nadir` -> `view:off_nadir`\n  - `eo:azimuth` -> `view:azimuth`\n  - `eo:incidence_angle` -> `view:incidence_angle`\n  - `eo:sun_azimuth` -> `view:sun_azimuth`\n  - `eo:sun_elevation` -> `view:sun_elevation`\n- Extensions:\n  - Data Cube extension: Changed allowed formats (removed PROJ string, added PROJJSON / WKT2) for reference systems\n  - [Checksum extension](https://github.com/stac-extensions/checksum/blob/main/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash))\n  - 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)\n- STAC API:\n  - The endpoint `/stac` has been merged with `/`\n  - The endpoint `/stac/search` is now called `/search`\n  - Sort Extension - added non-JSON query/form parameter format\n  - Fields extension has a simplified format for GET parameters\n  - `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context`\n  - Removed \"next\" from the search metadata and query parameter, added POST body and headers to the links for paging support\n  - Query Extension - type restrictions on query predicates are more accurate, which may require additional implementation support\n- Item `title` definition moved from core Item fields to [Common Metadata Basics](item-spec/common-metadata.md#basics)\nfields. No change is required for STAC Items.\n- `putFeature` can return a `PreconditionFailed` to provide more explicit information when the resource has changed in the server\n- [Sort extension](https://github.com/radiantearth/stac-api-spec/tree/master/extensions/sort) now uses \"+\" and \"-\" prefixes for GET requests to denote sort order.\n- 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\n\n### Removed\n- `version` field in STAC Collections. Use [Version Extension](https://github.com/stac-extensions/version/blob/main/README.md) instead\n- `summaries` field from Catalogs. Use Collections instead\n- Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `roles` instead\n- `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead\n- Extensions:\n  - `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)\n  - Removed from EO extension field `eo:epsg` in favor of `proj:epsg`\n  - `gsd` and `accuracy` from `eo:bands` in the [EO extension](https://github.com/stac-extensions/eo/blob/main/README.md)\n  - `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md)\n  - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md)\n  - Datetime Range (`dtr`) extension. Use the [Common Metadata fields](item-spec/common-metadata.md) instead\n- STAC API:\n  - `next` from the search metadata and query parameter\n- In API, removed any mention of using media type `multipart/form-data` and `x-www-form-urlencoded`\n\n### Fixed\n\n- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private\n- Clarified how to fill `stac_extensions`\n- More clarifications; typos fixed\n- Fixed Item JSON Schema now `allOf` optional Common Metadata properties are evaluated\n- Clarified usage of optional Common Metadata fields for STAC Items\n- Clarified usage of paging options, especially in relation to what OGC API - Features offers\n- Allow Commonmark in asset description, as it's allowed everywhere else\n- Put asset description in the API\n- Fixed API spec regarding license expressions\n- Added missing schema in the API Version extension\n- Fixed links in the Landsat example in the collection-spec\n\n## [v0.8.1] - 2019-11-01\n\n### Changed\n- 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).\n\n### Fixed\n- Numerous typos, clarifications and fixes for documentation and examples.\n- Fixed STAC API definition to include STAC-related fields and examples in *OGC API - Features*-derived endpoints.\n- Fixed JSON schemas for extensions: `$id` field matches file name.\n\n## [v0.8.0] - 2019-10-11\n\n### Changed\n- 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:\n  - The structure of the field `extent` in STAC and WFS Collections changed.\n  - Query parameter `time` was renamed to `datetime` and accepts slightly different values.\n  - WFS links have additional fields `hreflang` and `length`.\n  - WFS Collections have additional fields `crs` and `itemType`.\n  - `time` API parameter changed to `datetime`\n- The API intersects parameter now accepts a GeoJSON Geometry (any type) *instead* of a GeoJSON Feature.\n- API: Clarification on `include` and `exclude` parameters in the field extension and notes on default values.\n- API: queries should contain either `bbox` or `intersects`.\n- API: Core API now has reserved parameters to prevent overlap with extensions\n- Updated bbox definitions in API, Item, and Collection specs to include support for optional elevation values.\n- Moved Single Item Extension to core (`license` and `providers` properties for Items).\n- Allow `various` for the `license` fields.\n- Clarified meaning of SAR and EO platform, constellation, and instrument\n- Numerous typos, clarification and general word-smithing\n- 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`.\n\n### Added\n- **stac_version**: Each Item must specify the STAC version.\n- **stac_extensions**: Introduced this field for Items, Catalogs and Collections.\n- Property `summaries` have been added to catalogs and collections.\n- API Transaction extension supports optimistic locking through use of the ETag header.\n- Asset Definition Extension added to Collections to allow specifying details about Assets that may appear in member Items.\n- [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.\n- [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\n- Timestamp fields added to `Item`: `created` and `updated` to refer to the datetime the metadata file was created or updated.\n- 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.\n- 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.\n- `in` operator added to the query extension (to check if value is in a list of values)\n- 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\n- [Scientific extension](https://github.com/stac-extensions/scientific/blob/main/README.md) can be used in Collections.\n\n### Fixed\n- Updated language, fixed typos and examples.\n- Renamed `pc:schema` to `pc:schemas` in the Point Cloud extension.\n\n### Changes since 0.8.0rc1\n- [Label extension](https://github.com/stac-extensions/label/blob/main/README.md):\n  - 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).\n  - 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).\n  - Renamed fields to use plural forms (`label:property` -> `label:properties`, `label:task` -> `label:tasks`, `label:method` -> `label:methods` and `label:overview` -> `label:overviews`)\n\n## [v0.7.0] - 2019-05-06\n\n### Fixed\n- Updated language / fixed typos\n- Moved static vs dynamic discussion text to catalog best practices document\n- Moved hosting of interactive api docs from swaggerhub to [stacspec.org](http://stacspec.org)\n- JSON Schemas are now all following the latest JSON Schema version, draft 07.\n\n### Changed\n- No longer require an absolute self link for Items, Collections and Catalogs.\n- Reorganized api-spec, added extensions folder to hold API extensions\n- Change the fields parameter in the API to allow filtering on any property.\n- 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.\n- Commons extension ability to 'merge' properties is now in the core specification\n\n### Added\n- Catalog best practices document, including recommendations for catalog layouts, html, and self-contained catalogs.\n- `page` parameter for STAC API\n- Optional `collection` property field in Items (previously part of the Commons extension)\n- It is now required to link to `/stac/search/` from `/stac/`\n- Added new fields to SAR extension: `sar:incidence_angle`, `sar:relative_orbit`, `sar:observation_direction`\n- Added new filter parameters `ids` and `collections` to `/stac/search/`\n\n### Removed\n- Removed the field `sar:off_nadir` from the SAR extension\n- JavaScript-based validation\n\n## [v0.6.2] - 2019-03-01\n\n### Fixed\n- Fixed several examples and typos, improved descriptions\n- Strictly checking the STAC version numbers in the JSON schemas\n- Added missing required fields in Item JSON schema\n- Changed `id` to `$id` in JSON schemas (draft-06 compatibility)\n\n### Changed\n- Extensions require examples and a JSON schema to get to the maturity level 'Pilot'\n- Updated ISERV implementation\n\n### Added\n- Checksum extension\n- Data Cube extension\n- Point Cloud extension\n- SAR extension\n\n## [v0.6.1] - 2019-01-25\n\n### Fixed\n- Added `null` as potential data type to `eo:epsg` in the EO extension.\n- Fixed several examples and typos.\n- Updated JSON Schema versions for uniformity\n- Added OpenEO GEE implementation\n- Clarified 'intersects' behavior for STAC API\n\n## [v0.6.0] - 2018-11-06\n\n### Fixed\n- Reorganized and cleaned up repository.\n- Fixed examples throughout.\n\n### Added\n- **Changelog**: This changelog added.\n- **Collections added**: Collections are a type of Catalog with additional fields, such as provider and license. Items must belong to a single Collection.\n- **Extension maturity**: Protocol for providing maturity classification for extensions based on stability and implementations.\n- **Commons extension**: The previous 'Collections' extension is now the 'Commons' extension and allows an Item to inherit properties from its Collection.\n- **Datetime-range extension**: Extension for providing start and end datetimes.\n- **Scientific extension**: Extension for providings links to scientific publications relating to the data.\n- **rel types**: A list of supported `rel` types are provided for use when specifying links, `derived_from` and `license` types added.\n- **eo:constellation**: A new field in the EO specification to specify a grouping of platforms.\n- **stac_version**: The `stac_version` field is required on all Catalogs (and Collections).\n- **JSON schemas**: Added JSON schemas where they were missing.\n- **Single Item extension**: Extension to supply License and Providers for single Items when no collection is used.\n- **UML Diagram**: See STAC-060-uml.pdf.\n- **Development Process**: See process.md for information on the STAC development process.\n\n### Changed\n- **API**: Main catalog endpoint at `/stac`, search endpoint now at `/stac/search`.\n- **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.\n- **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.\n- **links**: The links fields are now an array rather than a dictionary.\n- **properties**: Fields with the data type array or objects are allowed inside the `properties` in a STAC Item.\n- **description**: Description fields now allow formatting with CommonMark.\n- **assets**: Fields changed names: `name` to `title` and `mime_type` to `type`.\n\n### Removed\n- **provider**: Provider field in Items got removed. Use Collections or the Single Item extension instead.\n- **license**: License field in Items got removed. Use Collections or the Single Item extension instead.\n\n## [v0.5.2] - 2018-07-12\n\nMinor bug fixes on 0.5.1 for the schema files. Thanks @francbartoli\n\n## [v0.5.1] - 2018-07-06\n\nMinor bug fixes from 0.5.1 release\n\n- [Update openapi / swagger specs for new 'links'](https://github.com/radiantearth/stac-spec/commit/480d4fb02b4a7e880c7ca01320fe2773260ba595)\n- [minor fixes on collection extension](https://github.com/radiantearth/stac-spec/pull/124) - thanks @m-mohr\n- [minor cbers example updates](https://github.com/radiantearth/stac-spec/pull/123) - thanks @fredliporace\n\n## [v0.5.0] - 2018-07-01\n\nThe 0.5.0 release of the STAC spec is an iteration forward on the spec, with a number of core improvements. Highlights include:\n\n- **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 )\n\n- **Transactions Extension** - There is now a transaction extension for the STAC API, thanks to @hgs-msmith and @hgs-trutherford\n\n- **Collections iterations** @matthewhanson has evolved the collections extension, adding in some namespace type hints on it, and explaining it more clearly.\n\n- **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.\n\nFull list of issues and pull requests at <https://github.com/radiantearth/stac-spec/milestone/5?closed=1>\n\n## [v0.4.1] - 2018-04-24\n\nA few minor improvements on the release. ([issues](https://github.com/radiantearth/stac-spec/issues?utf8=%E2%9C%93&q=milestone%3A0.4.1+))\n\n- @hgs-msmith got a swagger version of the spec, and made some minor improvements to the openapi version #103 and #102\n- @francbartoli and @m-mohr pointed out some inconsistencies with landsat, so got the openapi updated #106\n- @m-mohr pointed out some issues with landsat example, so updated those #105\n- @hgs-trutherford pointed out that the planet example was a bit confusing, so updated it to the EO profile.\n\n## [v0.4.0] - 2018-04-06\n\nThe 0.4.0 is the first 'official' release of the SpatioTemporal Asset Catalog (STAC) specification!\n\nIt 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\na number of improvements from remote contributors.\n\nHighlights include:\n\n- 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.\n\n- Alignment of **STAC API** with the new [WFS3](https://github.com/opengeospatial/WFS_FES/) specification\n\n- Cleanup of the **static catalog** specification for greater clarity around the catalog\n\n- A first cut of an **Earth Observation Profile**, as well as a new collections extension to support it.\n\n- Numerous small improvements and bug fixes.\n\nSee the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/stac-spec/milestone/3) for the complete lists of improvements.\n\nThanks @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.\n\n[Unreleased]: <https://github.com/radiantearth/stac-spec/compare/master...dev>\n[v1.0.0]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.4..v1.0.0>\n[v1.0.0-rc.4]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.3..v1.0.0-rc.4>\n[v1.0.0-rc.3]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.2..v1.0.0-rc.3>\n[v1.0.0-rc.2]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.1..v1.0.0-rc.2>\n[v1.0.0-rc.1]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-beta.2..v1.0.0-rc.1>\n[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-beta.1..v1.0.0-beta.2>\n[v1.0.0-beta.1]: <https://github.com/radiantearth/stac-spec/compare/v0.9.0...v1.0.0-beta.1>\n[v0.9.0]: <https://github.com/radiantearth/stac-spec/compare/v0.8.1...v0.9.0>\n[v0.8.1]: <https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.8.1>\n[v0.8.0]: <https://github.com/radiantearth/stac-spec/compare/v0.7.0...v0.8.0>\n[v0.7.0]: <https://github.com/radiantearth/stac-spec/compare/v0.6.2...v0.7.0>\n[v0.6.2]: <https://github.com/radiantearth/stac-spec/compare/v0.6.1...v0.6.2>\n[v0.6.1]: <https://github.com/radiantearth/stac-spec/compare/v0.6.0...v0.6.1>\n[v0.6.0]: <https://github.com/radiantearth/stac-spec/compare/v0.5.2...v0.6.0>\n[v0.5.2]: <https://github.com/radiantearth/stac-spec/compare/v0.5.1...v0.5.2>\n[v0.5.1]: <https://github.com/radiantearth/stac-spec/compare/v0.5.0...v0.5.1>\n[v0.5.0]: <https://github.com/radiantearth/stac-spec/compare/v0.4.1...v0.5.0>\n[v0.4.1]: <https://github.com/radiantearth/stac-spec/compare/v0.4.0...v0.4.1>\n[v0.4.0]: <https://github.com/radiantearth/stac-spec/tree/v0.4.0>\n"
  },
  {
    "path": "stac-spec/CODE_OF_CONDUCT.md",
    "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as\ncontributors and maintainers pledge to making participation in our project and\nour community a harassment-free experience for everyone, regardless of age, body\nsize, disability, ethnicity, sex characteristics, gender identity and expression,\nlevel of experience, education, socio-economic status, nationality, personal\nappearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment\ninclude:\n\n- Using welcoming and inclusive language\n- Being respectful of differing viewpoints and experiences\n- Gracefully accepting constructive criticism\n- Focusing on what is best for the community\n- Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n- The use of sexualized language or imagery and unwelcome sexual attention or\n advances\n- Trolling, insulting/derogatory comments, and personal or political attacks\n- Public or private harassment\n- Publishing others' private information, such as a physical or electronic\n address, without explicit permission\n- Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable\nbehavior and are expected to take appropriate and fair corrective action in\nresponse to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or\nreject comments, commits, code, wiki edits, issues, and other contributions\nthat are not aligned to this Code of Conduct, or to ban temporarily or\npermanently any contributor for other behaviors that they deem inappropriate,\nthreatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces\nwhen an individual is representing the project or its community. Examples of\nrepresenting a project or community include using an official project e-mail\naddress, posting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event. Representation of a project may be\nfurther defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported by contacting the project team at [stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com). All\ncomplaints will be reviewed and investigated and will result in a response that\nis deemed necessary and appropriate to the circumstances. The project team is\nobligated to maintain confidentiality with regard to the reporter of an incident.\nFurther details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good\nfaith may face temporary or permanent repercussions as determined by other\nmembers of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,\navailable at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>\n\n[homepage]: <https://www.contributor-covenant.org>\n\nFor answers to common questions about this code of conduct, see\n<https://www.contributor-covenant.org/faq>\n"
  },
  {
    "path": "stac-spec/CONTRIBUTING.md",
    "content": "## Contributing\n\nPull Requests are the primary method of contributing to the spec itself, and everyone is welcome to submit \nchanges. Suggestions for changes to the core will be taken with higher priority if a clear implementation \nof STAC has been built that can highlight the problem. If the changes can be done as an [extension](extensions/) \ninstead of modifying the core files then that route is recommended first, and once there is uptake for the \nextension it will be considered for core.\n\nWe consider everyone using the specification to catalog their data to be a 'contributor', as STAC is\nreally about the end result of more interoperable data, not just creating a spec for the sake of it.\nSo if you want to help then the best thing you can do is make new catalogs or build software that uses\nthe spec. And please do give us feedback. The best place to do so is on our \n[gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). If you are interested in helping\nbut aren't sure where to, then see the [stac-ecosystem](https://github.com/stac-utils/stac-ecosystem) repo\nfor ideas on projects to advance STAC. The next phase of STAC's evolution will be mostly focused on\nthis broader ecosystem, while keeping the core spec as stable as we can.\n\n### Submitting Pull Requests\n\nAny proposed changes to the specification should be done as pull requests. Please make these\nrequests against the [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch (this will\nrequire you to switch from the default of 'master', which we keep so it displays first). \n\nCreating a Pull Request will show our PR template, which includes checkbox reminders for a number\nof things.\n\n- Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this \nis not required, but any change to the actual specification should definitely have one.\n- Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds\nyou to change the base in GitHub's PR creation page.\n- Make a ticket in the STAC API repo if anything here affects there.\n- Highlight if the PR makes breaking changes to the specification (in beta there can still be\nselect breaking changes, but after 1.0 this will change)\n\nAll pull requests should submit clean markdown, which is checked by the continuous integration\nsystem. Please use `npm run check` locally, as described in the [next section](#check-files), \nto ensure that the checks on the pull request succeed. If it does not then you can look at the\nmistakes online, which are the same as running `npm run check` locally would surface.\n\nAll pull requests that modify or create JSON schema files or examples should use\n[JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo. \n\nAll pull requests additionally require a review of two STAC core team members. Releases are cut\nfrom dev to master (and require 3 approvals), see the [process](process.md) document for more details.\n\n### Check files\n\nThe 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. \nTo install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).\nAlternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of `npm` with `yarn` below.\n\nFirst you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on \nyour command line run:\n\n```bash\nnpm install\n```\n\nThen to do the check for markdown and examples you run:\n\n```bash\nnpm run check\n```\n\nThis will spit out the same texts that you see online, and you can then go and fix your markdown or examples.\n\nTo just check the markdown run:\n\n```bash\nnpm run check-markdown\n```\n\nTo just check the examples run:\n\n```bash\nnpm run check-examples\n```\n\nTo automatically format / pretty-print the examples run:\n\n```bash\nnpm run format-examples\n```\n"
  },
  {
    "path": "stac-spec/LICENSE",
    "content": "                                 Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"{}\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright {yyyy} {name of copyright owner}\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n"
  },
  {
    "path": "stac-spec/README.md",
    "content": "<!--lint disable no-html-->\n<img src=\"https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png\" alt=\"stac-logo\" width=\"700\"/>\n\n[![CircleCI](https://circleci.com/gh/radiantearth/stac-spec.svg?style=svg)](https://circleci.com/gh/radiantearth/stac-spec)\n\n## About\n\nThe SpatioTemporal Asset Catalog (STAC) family of specifications aim to \nstandardize the way geospatial asset metadata is structured and queried. \nA \"spatiotemporal asset\" is any file that represents information about \nthe Earth at a certain place and time. The original focus was on scenes \nof satellite imagery, but the specifications now cover a broad variety of uses, \nincluding sources such as aircraft and drone and data such as hyperspectral optical, \nsynthetic aperture radar (SAR), video, point clouds, lidar, digital elevation \nmodels (DEM), vector, machine learning labels, and composites like NDVI and \nmosaics. STAC is intentionally designed with a minimal core and flexible \nextension mechanism to support a broad set of use cases. This specification \nhas matured over the past several years, and is used in [numerous production \ndeployments](https://stacindex.org/catalogs). \n\nThis is advantageous to providers of geospatial data, as they can simply use a\nwell-designed, standard format and API without needing to design their own proprietary one.\nThis is advantageous to consumers  of geospatial data, as they can use existing libraries \nand tools to access metadata, instead of needing to write new code to interact \nwith each data provider's proprietary formats and APIs. \n\nThe STAC specifications define related JSON object types connected by link \nrelations to support a [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)-style traversable\ninterface and a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API\nproviding additional browse and search interfaces.\nTypically, several STAC specifications are composed together to create an implementation. \nThe **Item**, **Catalog**, and **Collection** specifications define a minimal core \nof the most frequently used JSON object types. Because of the hierarchical structure \nbetween these objects, a STAC catalog can be implemented in a completely 'static' \nmanner as a group of hyperlinked Catalog, Collection, and Item URLs, enabling data \npublishers to expose their data as a browsable set of files. If more complex query \nabilities are desired, such as spatial or temporal predicates, the \n**STAC API** [specification](https://github.com/radiantearth/stac-api-spec/) can be \nimplemented as a web service interface to query over a group of STAC objects, usually \nheld in a database.\n\nTo the greatest extent possible, STAC uses and extends existing specifications. \nThe most important object in STAC is an **Item**, which is simply a [GeoJSON](http://geojson.org) **Feature** \nwith a well-defined set of additional attributes (\"foreign members\"). The **STAC API** \nextends the **[OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)** \nwith additional web service endpoints and object attributes.\n\n## Current version and branches\n\nThe [master branch](https://github.com/radiantearth/stac-spec/tree/master) is the 'stable' \nversion of the spec. It is currently version **1.0.0** of the specification. The STAC specification \nfollows [Semantic Versioning](https://semver.org/), so any breaking change will require the spec to \ngo to 2.0.0. \n\nThe [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development \ntakes place, and may have inconsistent examples. Whenever dev stabilizes, a release is cut and we \nmerge `dev` in to `master`. So `master` should be stable at any given time. \nMore information on how the STAC development process works can be found in \n[process.md](process.md).\n\n## Communication\n\nOur [gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby) is \nthe best place to ask questions or provide feedback. The majority of communication about the evolution of \nthe specification takes place in the [issue tracker](https://github.com/radiantearth/stac-spec/issues) and in \n[pull requests](https://github.com/radiantearth/stac-spec/pulls).\n\n## In this Repository\n\nThis repository contains the core object type specifications, [examples](examples/), \nvalidation schemas, and documentation about the context and plans for the evolution of the \nspecification. Each folder contains a README explaining the layout of the folder, \nthe main specification document, examples, and validating schemas. \n\nAdditionally, the [STAC API specification](https://github.com/radiantearth/stac-api-spec/) \nprovides API endpoints, based on the [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) standard,\nthat enable clients to search for Item objects that match their filtering criteria. \n\nThe **Item**, **Catalog**, **Collection**, and **STAC API** specifications are intended to be \nused together, but are designed so each piece is small, self-contained, and reusable in other contexts.\n\n- **[Overview](overview.md)** describes the three core object type specifications and how they relate to one another.\n- **[Item Specification](item-spec/)** defines a STAC **Item**, which is a [GeoJSON](http://geojson.org) **Feature**\n  with additional fields (\"foreign members\") for attributes like time and links to related entities and assets \n  (including thumbnails). This is the core entity that describes the data to be discovered.\n- **[Catalog Specification](catalog-spec/)** specifies a structure to link various STAC Items together to be crawled or browsed. It is a\n  simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways.\n- **[Collection Specification](collection-spec/)** provides additional information about a spatio-temporal collection of data.\n  In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider.\n  It includes things like the spatial and temporal extent of the data, the license, keywords, etc.\n  It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data.\n- **[Examples](examples/):** The *[examples/](examples/)* folder contains examples for all three specifications, linked together to form two \n  complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts.\n- **[Extensions](extensions/README.md)** describe how STAC can use extensions that extend the functionality of the core spec or \n  add fields for specific domains. Extensions can be published anywhere,\n  although the preferred location for public extensions is in the [GitHub `stac-extensions` organization](https://github.com/stac-extensions).\n- **Additional documents:** The supporting documents include a complementary [best practices](best-practices.md) \n  document, and information on contributing (links in the next section). We also maintain a [changelog](CHANGELOG.md) of\n  what was modified in each version. \n\n## Contributing\n\nAnyone building software that catalogs imagery or other geospatial assets is welcome to collaborate.\nBeforehand, please review our [guidelines for contributions](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md). \nYou may also be interested in our overall [process](process.md), and the [principles](principles.md) that guide our \ncollaboration\n"
  },
  {
    "path": "stac-spec/STAC-UML.drawio",
    "content": "<mxfile modified=\"2021-05-25T16:52:51.799Z\" host=\"app.diagrams.net\" agent=\"5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36\" etag=\"eD--ZDCa3gRjRkEJhZ5i\" version=\"14.7.1\" type=\"device\"><diagram id=\"TgNYBds_Jc586sA2aelI\" name=\"STAC 1.0.0\">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=</diagram></mxfile>"
  },
  {
    "path": "stac-spec/best-practices.md",
    "content": "# STAC Best Practices\n\n## Table of Contents\n\n- **[Web Best Practices](#web-practices)**\n  - [Enable Cross-origin resource sharing (CORS)](#enable-cross-origin-resource-sharing-cors)\n  - [STAC on the Web](#stac-on-the-web)\n    - [Schema.org, JSON-LD, DCAT, microformats, etc](#schemaorg-json-ld-dcat-microformats-etc)\n    - [Deploying STAC Browser](#deploying-stac-browser)\n  - [Requester Pays](#requester-pays)\n- **[Item Best Practices](#item-practices)**\n  - [Field and ID formatting](#item-ids)\n  - [Searchable Identifiers](#searchable-identifiers)\n  - [Field selection and Metadata Linking](#field-selection-and-metadata-linking)\n  - [Datetime selection](#datetime-selection)\n  - [Unlocated Items](#unlocated-items)\n    - [Unrectified Satellite Data](#unrectified-satellite-data)\n    - [Data that is not spatial](#data-that-is-not-spatial)\n  - [Representing Vector Layers in STAC](#representing-vector-layers-in-stac)\n- **[Asset Best Practices](#asset-practices)**\n  - [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets)\n  - [Working with Media Types](#working-with-media-types)\n    - [Common Media Types in STAC](#common-media-types-in-stac)\n    - [Formats with no registered media type](#formats-with-no-registered-media-type)\n  - [Asset Roles](#asset-roles)\n    - [List of Asset Roles](#list-of-asset-roles)\n      - [Thumbnail](#thumbnail)\n      - [Overview](#overview)\n      - [Visual](#visual)\n- **[Catalog & Collection Best Practices](#catalog--collection-practices)**\n  - [Static and Dynamic Catalogs](#static-and-dynamic-catalogs)\n    - [Static Catalogs](#static-catalogs)\n    - [Dynamic Catalogs](#dynamic-catalogs)\n  - [Catalog Layout](#catalog-layout)\n    - [Dynamic Catalog Layout](#dynamic-catalog-layout)\n    - [Mixing STAC Versions](#mixing-stac-versions)\n  - [Using Summaries in Collections](#using-summaries-in-collections)\n  - [Use of links](#use-of-links)\n    - [Self-contained Catalogs](#self-contained-catalogs)\n    - [Published Catalogs](#published-catalogs)\n  - [Using Relation Types](#using-relation-types)\n  - [Versioning for Catalogs](#versioning-for-catalogs)\n    - [Example](#example)\n  - [Static to Dynamic best practices](#static-to-dynamic-best-practices)\n    - [Ingestion and links](#ingestion-and-links)\n    - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services)\n  - [How to Differentiate STAC Files](#how-to-differentiate-stac-files)\n  \n\nThis document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them \nare required to meet the core specification, but following these practices will make life easier for client tooling\nand for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for\nthose who are creating STAC objects representing their data or creating tools to work with STAC. \n\nWhile the current goal of the core is to remain quite flexible and simple to meet a wide variety of use cases,\nin time some of these may evolve to become part of the core specification.\n\n## Web Practices\n\n### Enable Cross-origin resource sharing (CORS)\n\nSTAC strives to make geospatial information more accessible, by putting it on the web. Fundamental to STAC's vision is that\ndifferent tools will be able to load and display public-facing STAC data. But the web runs on a [Same origin \npolicy](https://en.wikipedia.org/wiki/Same-origin_policy), preventing web pages from loading information from other web locations\nto prevent malicious scripts from accessing sensitive data. This means that by default a web page would only be able to load STAC\n[Item](item-spec/item-spec.md) objects from the same server the page is on.\n[Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing),\nalso known as 'CORS' is a protocol to enable safe communication across origins. But most web services turn it off by default. This\nis generally a good thing, but unfortunately if CORS is not enabled then any browser-based STAC tool will not work. \n\nSo to enable all the great web tools (like [stacindex.org](http://stacindex.org)) to work with your STAC implementation it is essential to\n'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),\n[Google Cloud Storage](https://cloud.google.com/storage/docs/cross-origin), or [Apache Server](https://enable-cors.org/server_apache.html). \nMany more are listed on [enable-cors.org](https://enable-cors.org/server.html). We recommend enabling CORS for all requests ('\\*'),\nso that diverse online tools can access your data. If you aren't sure if your server has CORS enabled you can use \n[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) or\n[Collection](collection-spec/collection-spec.md) JSON and make sure it gets a response.\n\n### STAC on the Web\n\nOne of the primary goals of STAC is to make spatiotemporal data more accessible on the web. One would have a right to be \nsurprised that there is nothing about HTML in the entire specification. This is because it is difficult to specify what \nshould be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions\nof every STAC Item is paramount.\n\nThe main recommendation is to have an HTML page for every single STAC Item, Catalog and Collection. They should be visually pleasing, \ncrawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called\n[STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid STAC implementation and generate unique web\npages for each Item and Catalog (or Collection). While it has a default look and feel, the design can easily be \nmodified to match an existing web presence. And it will automatically turn any Item with a [Cloud Optimized \nGeoTIFF](http://cogeo.org) asset into an interactive, zoomable web map (using [tiles.rdnt.io](http://tiles.rdnt.io/) to render\nthe tiles on a [leaflet](https://leafletjs.com/) map). It also attempts to encapsulate a number of best practices that enable \nSTAC Items to show up in search engines, though that part is still a work in progress - contributions to STAC Browser to help\nare welcome!\n\nImplementors are welcome to generate their own web pages, and additional tools that automatically transform STAC JSON into \nhtml sites are encouraged. In time there will likely emerge a set of best practices from an array of tools, and we may be\nable 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 \nmaking data available as JSON, and then leverage tools that can evolve at the same time to make the best HTML experience. This\nenables innovation on the web generation and search engine optimization to evolve independently from the core data.\n\n#### Schema.org, JSON-LD, DCAT, microformats, etc\n\nThere is a strong desire to align STAC with the various web standards for data. These include [schema.org](http://schema.org) \ntags, [JSON-LD](https://json-ld.org/) (particularly for Google's [dataset \nsearch](https://developers.google.com/search/docs/data-types/dataset)), [DCAT](https://www.w3.org/TR/vocab-dcat/)\nand [microformats](http://microformats.org/wiki/about). STAC aims to work with as many as possible. Thusfar it has not seemed\nto 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\npages that search engines crawl, so the logical place to do the integration is by leveraging a tool that generates HTML \nfrom STAC like [STAC Browser](https://github.com/radiantearth/stac-browser/). STAC Browser has implemented a [mapping to \nschema.org](https://github.com/radiantearth/stac-spec/issues/378) fields using JSON-LD, but the exact output is still being\nrefined. It is on the roadmap to add in more mapping and do more testing of search engines crawling the HTML pages. \n\n#### Deploying STAC Browser\n\nMost public STAC implementations have a STAC Browser hosted at [stacindex.org](https://stacindex.org/catalogs).\nAnyone with a public STAC implementation is welcome to have a STAC Browser instance hosted for free,\njust submit it to [stacindex.org](https://stacindex.org/add).\nBut the stronger recommendation is to host a STAC Browser on your own domain, and to customize its \ndesign to look and feel like your main web presence. STAC aims to be decentralized, so each STAC-compliant data catalog \nshould have its own location and just be part of the wider web.\n\n### Requester Pays\n\nIt is very common that large, freely available datasets are set up with a 'requester pays' configuration. This is an option \n[on AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) and [on \nGoogle Cloud](https://cloud.google.com/storage/docs/requester-pays), that enables data providers to make their data\navailable to everyone, while the cloud platform charges access costs\n(such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data.\nFor popular datasets that are large in size the egress costs can be substantial, to the point where much\nless data would be available if the cost of distribution was always on the data provider.\n\nFor data providers using STAC with requester pays buckets, there are two main recommendations:\n\n1. Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata\n   to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of\n   the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open\n   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\n   STAC (but no guarantees and it may be on an alternate cloud).\n2. For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol\n   (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url.\n   Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication,\n   so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs\n   that will add a requestor pays parameter and will apply appropriate authentication to the request.\n   Using cloud-specific protocols will at least give users an option to register a paid account and\n   allow the data provider to properly charge for access. \n   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.\n\n## Item Practices\n\n### Item IDs\n\nWhen defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's\ndata. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing\nproviders can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally\nunique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will \nresult in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) \nendpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices.\n\n### Searchable Identifiers\n\nWhen coming up with values for fields that contain searchable identifiers of some sort, like `constellation` or `platform`,\nit is recommended that the identifiers consist of only lowercase characters, numbers, `_`, and `-`.\nExamples include `sentinel-1a` (Sentinel-1), `landsat-8` (Landsat-8) and `envisat` (Envisat).\nThis is to provide consistency for search across Collections, so that people can just search for `landsat-8`,\ninstead of thinking through all the ways providers might have chosen to name it.\n\n### Field selection and Metadata Linking\n\nIn general STAC aims to be oriented around **search**, centered on the core fields that users will want to search on to find \nimagery. The core is space and time, but there are often other metadata fields that are useful. While the specification is \nflexible enough that providers can fill it with tens or even hundreds of fields of metadata, that is not recommended. If \nproviders have lots of metadata then that can be linked to in the [Asset Object](item-spec/item-spec.md#asset-object) \n(recommended) or in a [Link Object](item-spec/item-spec.md#link-object). There is a lot of metadata that is only of relevance \nto loading and processing data, and while STAC does not prohibit providers from putting those type of fields in their items, \nit is not recommended. For very large catalogs (hundreds of millions of records),\nevery 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\n[STAC API](https://github.com/radiantearth/stac-api-spec) providers don't have bloated indices that no one actually uses.\n\n### Datetime selection\n\nThe `datetime` field in a STAC Item's properties is one of the most important parts of a STAC Item, providing the T (temporal) of \nSTAC. 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\nis straightforward - it is the capture or acquisition time. But often data is processed from a range of captures - drones usually\ngather a set of images over an hour and put them into a single image, mosaics combine data from several months, and data cubes\nrepresent slices of data over a range of time. For all these cases the recommended path is to use `start_datetime` and \n`end_datetime` fields from [common metadata](item-spec/common-metadata.md#date-and-time-range). The specification does allow one to set the \n`datetime` field to `null`, but it is strongly recommended to populate the single `datetime` field, as that is what many clients \nwill search on. If it is at all possible to pick a nominal or representative datetime then that should be used. But sometimes that \nis 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\nbeing found if you searched 1990 to 2000.\n\nExtensions that describe particular types of data can and should define their `datetime` field to be more specific. For example\na MODIS 8 day composite image can define the `datetime` to be the nominal date halfway between the two ranges. Another data type\nmight 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\nthe focus of STAC. If `datetime` is set to `null` then it is strongly recommended to use it in conjunction with an extension\nthat explains why it should not be set for that type of data. \n\n### Unlocated Items\n\nThough the [GeoJSON standard](https://tools.ietf.org/html/rfc7946) allows null geometries, in STAC we strongly recommend\nthat every item have a geometry, since the general expectation of someone using a SpatioTemporal Catalog is to be able to query\nall data by space and time. But there are some use cases where it can make sense to create a STAC Item before it gets\na geometry. The most common of these is 'level 1' satellite data, where an image is downlinked and cataloged before it has \nbeen geospatially located. \n\nThe recommendation for data that does not yet have a location is to follow the GeoJSON concept that it is an ['unlocated' \nfeature](https://tools.ietf.org/html/rfc7946#section-3.2). So if the catalog has data that is not located then it can follow \nGeoJSON and set the geometry to null. Though normally required, in this case the `bbox` field should not be included.\n\nNote that this recommendation is only for cases where data does not yet have a geometry and it cannot be estimated. There\nare further details on the two most commonly requested desired use cases for setting geometry to null:\n\n#### Unrectified Satellite Data\n\nMost satellite data is downlinked without information that precisely describes where it is located on Earth. A satellite \nimagery processing pipeline will always attempt to locate it, but often that process takes a number of hours, or never\nquite completes (like when it is too cloudy). It can be useful to start to populate the Item before it has a geometry. \nIn this case the recommendation is to use the 'estimated' position from the satellite, to populate at least the bounding box,\nand use the same broad bounds for the geometry (or leaving it null) until there is precise ground lock. This estimation is \nusually done by onboard equipment, like GPS or star trackers, but can be off by kilometers or more. But it is very useful for \nSTAC users to be able to at least find approximate area in their searches. A commonly used field for communicating ground lock \nis not yet established, but likely should be (an extension proposal would be appreciated).  If there is no way to provide an \nestimate then the data can be assigned a null geometry and no `bbox`, as described above. But the data will likely not\nshow up in STAC API searches, as most will at least implicitly use a geometry. Though this section is written with \nsatellite data in mind, one can easily imagine other data types that start with a less precise geometry but have it \nrefined after processing.\n\n#### Data that is not spatial\n\nThe 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\nnot spatial. This use case is not currently supported by STAC, as we are focused on data that is both temporal and spatial\nin nature. The [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) is an emerging standard that likely\nwill be able to handle a wider range of data than STAC. It builds on [OGC API - \nFeatures](https://github.com/opengeospatial/ogcapi-features) just like [STAC API](https://github.com/radiantearth/stac-api-spec/)\ndoes. Using [Collection Assets](collection-spec/collection-spec.md#asset-object) may also provide an option for some \nuse cases.\n\n### Representing Vector Layers in STAC\n\nMany implementors are tempted to try to use STAC for 'everything', using it as a universal catalog of all their 'stuff'.\nThe main route considered is to use STAC to describe vector layers, putting a shapefile or [geopackage](http://geopackage.org)\nas the `asset`. Though there is nothing in the specification that *prevents* this, it is not really the right level of \nabstraction. A shapefile or geopackage corresponds to a Collection, not a single Item. The ideal thing to do with\none of those is to serve it with [OGC API - Features](https://github.com/opengeospatial/ogcapi-features) standard. This\nallows each feature in the shapefile/geopackage to be represented online, and enables querying of the actual data. If\nthat is not possible then the appropriate way to handle Collection-level search is with the \n[OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API. \nBoth are compliant with OGC API - Features, adding richer search capabilities to enable finding of data. \n\n## Asset Practices\n\n### Common Use Cases of Additional Fields for Assets\n\nAs [described in the Item spec](item-spec/item-spec.md#additional-fields-for-assets), it is possible to use fields typically\nfound in Item properties at the asset level. This mechanism of overriding or providing Item Properties only in the Assets \nmakes discovery more difficult and should generally be avoided. However, there are some core and extension fields for which \nproviding them at at the Asset level can prove to be very useful for using the data.\n\n- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`,\n  but an Asset is for one specific time.\n- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets that represent instruments \n  with different spatial resolution than the overall best resolution. Note this should not be used for different \n  spatial resolutions due to specific processing of assets - look into the [raster \n  extension](https://github.com/stac-extensions/raster) for that use case.\n- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)):\n  Provide spectral band information, and order of bands, within an individual asset.\n- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)):\n  Specify different projection for some assets. If the projection is different\n  for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is \n  a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the \n  Item and the alternate projection for the affected asset(s).\n- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)):\n  If assets have different spatial resolutions and slightly different exact bounding boxes,\n  specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection.\n- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)):\n  Provide the polarization content and ordering of a specific asset, similar to `eo:bands`.\n- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)):\n  If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset.\n\n### Working with Media Types\n\n[Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for\nclients. 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\nmedia type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible.\nThe following table lists types that commonly show up in STAC assets. And the the [section](#formats-with-no-registered-media-type)\npast that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type.\n\n#### Common Media Types in STAC\n\nThe following table lists a number of commonly used media types in STAC. The first two (GeoTIFF and COG) are not fully standardized \nyet, but reflect the community consensus direction. There are many IANA registered types that commonly show up in STAC. The \nfollowing table lists some of the most common ones you may encounter or use.\n\n| Media Type                                              | Description                                                  |\n| ------------------------------------------------------- | ------------------------------------------------------------ |\n| `image/tiff; application=geotiff`                       | GeoTIFF with standardized georeferencing metadata            |\n| `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. |\n| `image/jp2`                                             | JPEG 2000                                                    |\n| `image/png`                                             | Visual PNGs (e.g. thumbnails)                                |\n| `image/jpeg`                                            | Visual JPEGs (e.g. thumbnails, oblique)                      |\n| `text/xml` or `application/xml`                         | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) |\n| `application/json`                                      | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) |\n| `text/plain`                                            | Plain text (often metadata)                                  |\n| `application/geo+json`                                  | [GeoJSON](https://geojson.org/)                              |\n| `application/geopackage+sqlite3`                        | [GeoPackage](https://www.geopackage.org/)                    |\n| `application/x-hdf5`                                    | Hierarchical Data Format version 5                           |\n| `application/x-hdf`                                     | Hierarchical Data Format versions 4 and earlier.             |\n\n*Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and\nCloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`.\nBoth can still appear in old STAC implementations, but are deprecated and should be replaced. This will, unfortunately, likely shift in the future as\n[OGC sorts out the media types](https://github.com/opengeospatial/geotiff/issues/34).*\n\n#### Formats with no registered media type\n\nIdeally every media type used is on the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml). If\nyou are using a format that is not on that list we recommend you use [custom content \ntype](https://restcookbook.com/Resources/using-custom-content-types/). These typically use the `vnd.` prefix, see [RFC 6838 \nsection-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). Ideally the format provider will actually\nregister the media type with IANA, so that other STAC clients can find it easily. But if you are only using it internally it is \n[acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory) \nit. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type.\n\n### Asset Roles\n\n[Asset roles](item-spec/item-spec.md#asset-roles) are used to describe what each asset is used for. They are particular useful \nwhen several assets have the same media type, such as when an Item has a multispectral analytic asset, a 3-band full resolution \nvisual asset, a down-sampled preview asset, and a cloud mask asset, all stored as Cloud Optimized GeoTIFF (COG) images. It is \nrecommended to use at least one role for every asset available, and using multiple roles often makes sense. For example you'd use\nboth `data` and `reflectance` if your main data asset is processed to reflectance, or `metadata` and `cloud` for an asset that \nis a cloud mask, since a mask is considered a form of metadata (it's information about the data). Or if a single asset represents\nseveral types of 'unusable data' it might include `metadata`, `cloud`, `cloud-shadow` and `snow-ice`. If there is not a clear\nrole in the [Asset Role Types](item-spec/item-spec.md#asset-role-types) or the following list then just pick a sensible name for \nthe 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 \napplicability. \n\n#### List of Asset Roles\n\nIn addition to the thumbnail, data and overview [roles listed](item-spec/item-spec.md#asset-role-types) in the Item spec, there\nare a number of roles that are emerging in practice, but don't have enough widespread use to justify standardizing them. So if\nyou 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.\n\nThe 'source' field lists where the role comes from. The ones the say Item Spec are the only 'official' roles that are fully\nstandardized. In time others on this list may migrate to a more 'official' list. Those that say 'best practice' are just from this \ndoc, the listing is the table below. The ones from extensions are mostly just 'best practices' in the extensions, as there are few\nactual role requirements.\n\n| Role Name | Source | Description                                                            |\n| --------- | -------------|----------------------------------------------------------------------- |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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))). |\n| date | Best Practice | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset |\n| graphic | Best Practice | Supporting plot, illustration, or graph associated with the Item |\n| data-mask | Best Practice | File indicating if corresponding pixels have Valid data and various types of invalid data |\n| snow-ice | Best Practice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. |\n| land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. |\n| 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 |\n| iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file |\n| 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. |\n| 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. |\n| 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. |\n\nSome of the particular asset roles also have some best practices:\n\n##### Thumbnail\n\nThumbnails are typically used to give quick overview, often embedded in a list of items. So think small with these, as \nkeeping the size down helps it load fast, and the typical display of a thumbnail won't benefit from a large size. Often 256 by\n256 pixels is used as a default. Generally they should be no more than 600 by 600 pixels. Some implementors provide different sizes \nof thumbnails - using something like thumbnail-small and thumbnail-large, with a small one being 100x100 pixels or less, for truly \nfast rendering in a small image. Be sure to name one just 'thumbnail' though, as that's the default most STAC clients will look for.\n\nThumbnails should be PNG, JPEG, or WebP, so that they can easily display in browsers, and they should be a true color composite \n(red, green, and blue bands) if there are multiple bands.\n\nIf your data for the Item does not come with a thumbnail already we do recommend generating one, which can be done quite easily. \n[GDAL](https://gdal.org/) and [Rasterio](https://rasterio.readthedocs.io/en/latest/) both make this very easy - if you need help\njust ask on the [STAC Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby).\n\n##### Overview\n\nAn overview is a high-definition browse image of the dataset, giving the user more of a sense of the data than a thumbnail could.\nIt's something that can be easily displayed on a map without tiling, or viewed at full screen resolution (but not zoomed in). Similar\nto a thumbnail it should be PNG, JPEG or WebP, for easy display in browsers, and should be a true color composite \n(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) \nto a few thousand pixels on each side.\n\n###### Visual\n\nA 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, \nbut Cloud Optimized GeoTIFF's are preferred, since the inner pyramids and tiles enable faster display of the full resolution data. \nIt is typically an composite of red, blue and green bands, often with a nice color curve and sharpening for enhanced display. It should\nbe possible to open up on non-specialist software and display just fine. It can complement assets where one band is per file (like landsat),\nby providing the key display bands combined, or can complement assets where many non-visible bands are included, by being a lighter weight\nfile that just has the bands needed for display\n\n## Catalog & Collection Practices\n\n*Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the \n[Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, \nwhich can be any mix of Catalogs Collections and Items.*\n\n### Static and Dynamic Catalogs\n\nAs mentioned in the main [overview](overview.md), there are two main types of catalogs - static\nand dynamic. This section explains each of them in more depth and shares some best practices on each.\n\n#### Static Catalogs\n\nA static catalog is an implementation of the STAC specification that does not respond dynamically to requests. It is simply\na 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\nservice like [Amazon S3](https://aws.amazon.com/s3/), [Azure Storage](https://azure.microsoft.com/en-us/services/storage/) and\n[Google Cloud Storage](https://cloud.google.com/storage/). But any http server could expose a static catalog as files.\nThe core JSON documents and link structures are encoded in the file, and work as long as things are structured properly.\nA static catalog can only really be crawled by search engines and active catalogs; it can not respond to queries.\nBut it is incredibly reliable, as there are no moving parts, no clusters or databases to maintain.\nThe goal of STAC is to expose as much asset metadata online as possible, so the static catalog offers a very low\nbarrier to entry for anyone with geospatial assets to make their data searchable.\n\nStatic catalogs tend to make extensive use of *sub-catalogs* to organize their Items into sensible browsing structures, \nas they can only have a single representation of their catalog, since the static nature means the structure is baked in.\nWhile it is up to the implementor to organize the catalog, it is recommended to arrange it in a way that would make sense \nfor a human to browse a set of STAC Items in an intuitive matter.\n\nUsers indicate their intent for a file to be parsed as a Collection or Catalog using the required `type` field on\neach entity. For Collections, this field must have the value `Collection`, while for Catalogs, it must have the\nvalue `Catalog`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json`\nor `collection.json` to distinguish the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice \nis to place the Catalog file in namespaces \"directories\". For example:\n\n- current/catalog.json\n- archive/catalog.json\n\n#### Dynamic Catalogs\n\nA dynamic catalog is implemented in software as an HTTP-based API, following the same specified JSON structure for Items, Catalogs\nand Collections. Its structure and responses are usually generated dynamically, instead of relying on a set of\nalready defined files. But the result is the same, enabling the same discovery from people browsing and search engines crawling. \nIt generally indexes data for efficient responses, and aims to be easy for existing APIs to implement as a more standard interface \nfor clients to consume. A dynamic catalog will sometimes be populated by a static catalog, or at least may have a 'backup' of its \nfields stored as a cached static catalog.\n\nDynamic catalogs often also implement the [STAC API](https://github.com/radiantearth/stac-api-spec/) specification, that \nresponds to search queries (like \"give me all imagery in Oahu gathered on January 15, 2017\"). But they are not required to.  One\ncan have a dynamic service that only implements the core STAC specification, and is crawled by STAC API implementations that\nprovide 'search'. For example a Content Management Service like Drupal or an open data catalog like CKAN could choose to expose \nits content as linked STAC Items by implementing a dynamic catalog. \n\nOne benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same Items in \ndifferent sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by\nproviders, and users could browse down to both. The leaf Items should just be linked to in a single canonical location\n(or at least use a `rel` link that indicates the location of the canonical one).\n\n### Catalog Layout\n\nCreating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, Items\nand assets, and how to name them. The specification leaves this totally open, and you can link things as you want. But \nit is recommended to be thoughtful about the organization of sub-catalogs, putting them into a structure that a person\nmight reasonably browse (since they likely will with [STAC on the Web](#stac-on-the-web) recommendations). For example\nstart with location, like a normal grid (path+row in Landsat) or administrative boundaries (country -> state-level) and \nthen year, month, day. Or do the opposite - date and then location. Making a huge unordered list is technically allowed,\nbut not helpful for discovery of data. Thus it is generally considered a best practice to make use of sub-catalogs to \nkeep the size of each sub-catalog under a megabyte. If your sub-catalog lists tens of thousands of child items then you\nshould consider an additional way to break it up. \n\nWe encourage people to explore new structures of linking data, but the following list is what a number of implementors \nended up doing. Following these recommendations makes for more legible catalogs, and many tools operate more efficiently\nif you follow these recommendations.\n\n1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog.\n2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`.\n3. Items should be named `<id>.json`.\n4. Sub-Catalogs or sub-Collections should be stored in subdirectories of their parent\n   (and only 1 subdirectory deeper than a document's parent, e.g. `.../sample/sub1/catalog.json`).\n5. Items should be stored in subdirectories of their parent Catalog or Collection. \n   This means that each Item and its assets are contained in a unique subdirectory.\n6. Limit the number of Items in a Catalog or Collection, grouping / partitioning as relevant to the dataset.\n7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy.\n   For example, if levels 2 and 4 of the hierarchy only contain Collections, \n   don't add a Catalog at levels 2 and 4.\n\nOne further recommendation to help tools is to always include the 'title' field when including a link, especially in the \n`item`, `child`, `parent` and `root` links, even if it repeats several times. This should be the same as the 'title' in the \nlink destination. Having this enables clients to display a nice human readable name of the link without having  to open the \nlink destination. \n\n#### Dynamic Catalog Layout\n\nWhile these recommendations were primarily written for [static catalogs](#static-catalogs), they apply\nequally well to [dynamic catalogs](#dynamic-catalogs). Subdirectories of course would just be URL paths \ngenerated dynamically, but the structure would be the same as is recommended.\n\nOne benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same Items in \ndifferent sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another \nby providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location \n(or at least use a rel link that indicates the location of the canonical one). It is recommended that dynamic catalogs \nprovide multiple 'views' to allow users to navigate in a way that makes sense to them, providing multiple 'sub-catalogs'\nfrom the root that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the \ncanonical 'rel' link should be used to designate the primary location of the Item to search engine crawlers.\n\n#### Mixing STAC Versions\n\nAlthough it is allowed to mix STAC versions, it should be used carefully as clients may not support all versions so that \nthe catalog could be of limited use to users. A Catalog or Collection linking to differently versioned Sub-Catalogs or Sub-Collections\nis a common use case when multiple data source are combined. Client developers should be aware of this use case. Nevertheless, it \nis strongly recommended that Catalogs don't contain differently versioned Items so that users/clients can at least use and/or download\nconsistent (Sub-)Catalogs containing either all or no data. Collections that are referenced from Items should always use the same\nSTAC version. Otherwise some behaviour of functionality may be unpredictable (e.g. merging common fields into Items or reading summaries).\n\n### Using Summaries in Collections\n\nOne of the strongest recommendations for STAC is to always provide [summaries](collection-spec/collection-spec.md#summaries) in\nyour Collections. The core team decided to not require them, in case there are future situations where providing a summary\nis too difficult. The idea behind them is not to exhaustively summarize every single field in the Collection, but to provide\na bit of a 'curated' view. \n\nSome general thinking on what to summarize is as follows:\n\n- 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\nthe data might be. For example in overhead imagery, a \n[`view:off_nadir`](https://github.com/stac-extensions/view/blob/main/README.md#item-properties-and-item-asset-fields)\nwith a range of 0 to 3 would tell people this imagery is all pretty much straight down,\nwhile a value of 15 to 40 would tell them that it's oblique imagery, or 0 to 60 that it's \na Collection with lots of different look angles. \n\n- Fields that have only one or a handful of values are also great to summarize. Collections with a single satellite may\nuse a single [`gsd`](item-spec/common-metadata.md#instrument) field in the summary, and it's quite useful for users to know\nthat all data is going to be the same resolution. Similarly it's useful to know the names of all the \n[`platform` values](item-spec/common-metadata.md#instrument) that are used in the Collection. \n\n- It is less useful to summarize fields that have numerous different discrete values that can't easily be represented\nin a range. These will mostly be string values, when there aren't just a handful of options. For example if you had a \n'location' field that gave 3 levels of administrative region (like 'San Francisco, California, United States') to help people\nunderstand more intuitively where a shot was taken. If your Collection has millions of Items, or even hundreds, you don't want\nto include all the different location string values in a summary. \n\n- Fields that consist of arrays are more of a judgement call. For example [`instruments`](item-spec/common-metadata.md#instrument)\nis straightforward and recommended, as the elements of the array are a discrete set of options. On the other hand \n[`proj:transform`](https://github.com/stac-extensions/projection/blob/main/README.md#projtransform)\nmakes no sense to summarize, as the union of all the values\nin the array are meaningless, as each Item is describing its transform, so combining them would just be a bunch of random numbers.\nSo if the values contained in the array are independently meaningful (not interconnected) and there aren't hundreds of potential\nvalues then it is likely a good candidate to summarize.\n\nWe do highly recommend including an [`eo:bands`](https://github.com/stac-extensions/eo/blob/main/README.md#eobands)\nsummary if your Items implement `eo:bands`, \nespecially if it represents just one satellite or constellation. This should be a union of all the potential bands that you \nhave in assets. It is ok to only add the summary at the Collection level without putting an explicit `eo:bands` summary at the \n`properties` level of an Item, since that is optional. This gives users of the Collection a sense of the sensor capabilities without \nhaving to examine specific Items or aggregate across every Item.\n\nNote that the ranges of summaries don't have to be exact. If you are publishing a catalog that is constantly updating with\ndata from a high agility satellite you can put the `view:off_nadir` range to be the expected values, based on the satellite\ndesign, instead of having it only represent the off nadir angles that are Items for assets already captured in the catalog.\nWe don't want growing catalogs to have to constantly check and recalculate their summaries whenever new data comes in - its\njust meant to give users a sense of what types of values they could expect. \n\n### Use of links\n\nThe STAC specifications allow both relative and absolute links, and says that `self` links are not required, but are \nstrongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it \nis essential to use different link types. The best practice is to use one of the below catalog types, applying the link \nrecommendations consistently, instead of just haphazardly applying relative links in some places and absolute ones in other places.\n\n#### Self-contained Catalogs\n\nA 'self-contained catalog' is one that is designed for portability. Users may want to download a catalog from online and be\nable to use it on their local computer, so all links need to be relative. Or a tool that creates catalogs may need to work \nwithout knowing the final location that it will live at online, so it isn't possible to set absolute 'self' URL's. These use\ncases should utilize a catalog that follows the listed principles:\n\n- **Only relative href's in structural `links`**: The full catalog structure of links down to sub-catalogs and Items, and their \nlinks back to their parents and roots, should be done with relative URL's. The structural rel types include `root`, `parent`, \n`child`, `item`, and `collection`. Other links can be absolute, especially if they describe a resource that makes less sense in\nthe catalog, like [sci:doi](https://github.com/stac-extensions/scientific/blob/main/README.md#item-and-collection-fields), \n`derived_from` or even `license` (it can be nice to include the license in the catalog, but some licenses live at a canonical \nonline location which makes more sense to refer to directly). This enables the full catalog to be downloaded or\ncopied to another location and to still be valid. This also implies no `self` link, as that link must be absolute.\n\n- **Use Asset `href` links consistently**: The links to the actual assets are allowed to be either relative or absolute. There\nare two types of 'self-contained catalogs'. \n\n#### Self-contained Metadata Only\n\nThese consist of just the STAC metadata (Collection, Catalog and Item files), and uses absolute href \nlinks to refer to the online locations of the assets. \n\n#### Self-contained with Assets\n\nThese use relative href links for the assets, and includes them in the folder structure.\nThis enables offline use of a catalog, by including all the actual data, referenced locally.\n\nSelf-contained catalogs tend to be used more as static catalogs, where they can be easily passed around. But often they will\nbe generated by a more dynamic STAC service, enabling a subset of a catalog or a portion of a search criteria to be downloaded\nand used in other contexts. That catalog could be used offline, or even published in another location.\n\nSelf-contained catalogs are not just for offline use, however - they are designed to be able to be published online and to live\non the cloud in object storage. They just aim to ease the burden of publishing, by not requiring lots of updating of links. \nAdding a single `self` link at the root is recommended for online catalogs,\nturning it into a 'relative published catalog', as detailed below.\nThis anchors it in an online location and enables provenance tracking.\n\n#### Published Catalogs\n\nWhile STAC is useful as a portable format to move between systems, the goal is really to enable search. While any combination\nof absolute and relative links is technically allowed by the specification, it is strongly recommended to follow one of the \npatterns described below when publishing online. Many clients will not properly handle arbitrary mixes of absolute and relative\nhref's. \n\nWe refer to a 'published catalog' as one that lives online in a stable location, and uses `self` links to establish its location and \nenable easy provenance tracking. There are two types of published catalogs:\n\n#### Absolute Published Catalog\n\nThis is a catalog that uses absolute links for everything, both in the `links` objects and in the\n`asset` hrefs. It includes `self` links for every Item. Generally these are implemented by dynamic catalogs, as it is quite\neasy for them to generate the proper links dynamically. But a static catalog that knows its published location could easily\nimplement it.\n\n#### Relative Published Catalog\n\nThis is a self-contained catalog as described above, except it includes an absolute `self` link at\nthe root to identify its online location. This is designed so that a self-contained catalog (of either type, with its \nassets or just metadata) can be 'published' online\nby just adding one field (the self link) to its root (Catalog or Collection). All the other links should remain the same. The resulting catalog\nis no longer compliant with the self-contained catalog recommendations, but instead transforms into a 'relative published catalog'. \nWith this, a client may resolve Item and sub-catalog self links by traversing parent and root links, but requires reading \nmultiple sources to achieve this. \n\nSo if you are writing a STAC client it is recommended to start with just supporting these two types of published catalogs. In \nturn, if your data is published online publicly or for use on an intranet then following these recommendations will ensure\nthat a wider range of clients will work with it. \n\n### Using Relation Types\n\nImplementors of STAC are highly recommended to be quite liberal with their `links`, and to use the `rel` field (in conjunction\nwith the `type` field) to communicate the structure and content of related entities. While each STAC spec describes some of the \n'custom' relations STAC has set, the ideal is to reuse official [IANA Link Relation \nTypes](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes\na number of the common official relations that are used in production STAC implementations.\n\n| Type      | Description                                                  |\n| --------- | ------------------------------------------------------------ |\n| 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. |\n| 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. |\n| 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) |\n| 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. |\n| 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. |\n| 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. |\n\nBeing liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the\n`parent` and `root` relation types will point at the same file when the child is directly below the root, and it is\nrecommended to include both. \n\n### Versioning for Catalogs\n\nIn the Item and Collection STAC JSON, versions and deprecation can be indicated with the\n[Versioning Indicators Extension](https://github.com/stac-extensions/version).\n\nThe [Items and Collections API Version Extension](https://github.com/stac-extensions/version/) provides endpoints and \nsemantics for keeping and accessing previous versions of Collections and Items. The same semantics can be used in static \ncatalogs to preserve previous versions of the documents and link them together.\n\nIn order to achieve this, the static catalog must make sure that for every record created, a copy of the record is also \ncreated in a separate location and it is named with the version id adopted by the catalog. See \n[here](https://github.com/stac-extensions/version/blob/main/README.md#version-id) for recommendations on versioning schema.\n\nThe main record should also provide a link to the versioned record following the linking patterns described \n[here](https://github.com/stac-extensions/version/blob/main/README.md#relation-types). For every update to the record, the same \ncycle is repeated:\n\n1. Add link from the updated record to the previous version\n2. Create a copy of the updated record and name it correctly\n\n#### Example\n\nWhen the record `my_item.json` is created, a copy of it is also created. `my_item.json` includes `permalink` to `my_item_01.json`.\nThe version suffix of the file name is taken from the version field of the record when it is available.\n\n- `root / collections / example_collection / items / my_item / my_item.json`\n- `root / collections / example_collection / items / my_item / my_item_01.json`\n\nWhen `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`.\nThis ensures that `my_item_02.json` includes a link to `my_item_01.json`\n\n- `root / collections / example_collection / items / my_item / my_item.json`\n- `root / collections / example_collection / items / my_item / my_item_01.json`\n- `root / collections / example_collection / items / my_item / my_item_02.json`\n\n### Static to Dynamic best practices\n\nMany implementors are using static catalogs to be the reliable core of their dynamic services, or layering their STAC API\non top of any static catalog that is published. These are some recommendations on how to handle this:\n\n#### Ingestion and links\n\nImplementors have found that it's best to 'ingest' a static STAC into an internal datastore (often elasticsearch, but a \ntraditional database could work fine too) and then generate the full STAC API responses from that internal representation.\nThere are instances that have the API refer directly to the static STAC Items, but this only works well if the static STAC \ncatalog is an 'absolute published catalog'. So the recommendation is to always use absolute links - either in the static \npublished catalog, or to create new absolute links for the STAC search/ endpoint \nresponses, with the API's location at the base url. The `/` endpoint with the catalog could either link directly\nto the static catalog, or can follow the 'dynamic catalog layout' recommendations above with a new set of URL's.\n\nIdeally each Item would use its `links` to provide a reference back to the static location. The location of the static\nItem should be treated as the canonical location, as the generated API is more likely to move or be temporarily down. The\nspec provides the `derived_from` rel field, which fits well enough, but `canonical` is likely the more appropriate one\nas everything but the links should be the same.\n\n#### Keep catalogs in sync with cloud notification and queue services\n\nThere is a set of emerging practices to use services like Amazon's Simple Queue Service (SQS)\nand Simple Notification Service (SNS) to keep catalogs in sync.\nThere is a great [blog post](https://aws.amazon.com/blogs/publicsector/keeping-a-spatiotemporal-asset-catalog-stac-up-to-date-with-sns-sqs/)\non the CBERS STAC implementation on AWS.\nThe core idea is that a static catalog should emit a notification whenever it changes. The recommendation for SNS is to use the STAC \nItem JSON as the message body, with some fields such as a scene’s datetime and geographic bounding box that allows \nbasic geographic filtering from listeners. \n\nThe dynamic STAC API would then listen to the notifications and update its internal datastore whenever new data comes into\nthe static catalog. Implementors have had success using AWS Lambda to do a full 'serverless' updating of the elasticsearch\ndatabase, but it could just as easily be a server-based process.\n\n## How to Differentiate STAC Files\n\nAny 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, \nCollection or Catalog. As of 1.0.0 this is done primarily\nwith the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it.\n\n```shell\nif type is 'Collection'\n  => Collection\nelse if type is 'Catalog'\n  => Catalog\nelse if type is 'Feature' and stac_version is defined\n  => Item\nelse\n  => Invalid (JSON)\n```\n\nWhen crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types\n) (`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\n`root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the the `type` field\nin 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\nis for the Media Type, but there are not specific media types for Catalog and Collection. See the sections on [STAC media \ntypes](catalog-spec/catalog-spec.md#media-types), and [Asset media types](item-spec/item-spec.md#asset-media-type) for more information.\n\nIn versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections.\nSee [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works\nfor older STAC versions.\n"
  },
  {
    "path": "stac-spec/catalog-spec/README.md",
    "content": "# STAC Catalog Specification\n\nA STAC [Catalog](catalog-spec.md) is a top-level object that logically groups other Catalog, Collection, \nand [Item](../item-spec/item-spec.md) objects.  A Catalog contains an array of Link objects to these other \nobjects and can include additional metadata to describe the objects contained therein. It is defined in full \nin the [STAC Catalog Specification](catalog-spec.md).\n\nFor more information on how the parts of STAC fit together see the [overview](../overview.md) document.\n\nA Catalog is typically the \"entry point\" into a STAC object hierarchy.\nFor example, the root endpoint (\"landing page\") of a STAC API implementation is a Catalog.\nFor many static STAC catalogs (e.g., those defined only by a set of files on disk or in a cloud object store),\nthe root URL points to a Catalog that acts as the starting point to traverse the entire catalog of Catalog, Collection, and Item objects. \n\nWhile STAC Catalogs mostly describe a structure of links and Items,\na key related specification is the [STAC Collection Specification](../collection-spec/collection-spec.md),\nwhich contains fields that further describe the group of Items in a Catalog. \n\nA STAC Catalog requires a subset of the fields required by a Collection.\nThese are distinguished from one another by the `type` field, which will have the value `Catalog` or `Collection`.\nThis means that a Collection can be changed to a Catalog simply by changing this `type` field.\nThe parent-child relationships among Catalogs and Collections are for objects of these types,\nas there is no subtyping relationship between the Collection and Catalog types, even through they share field names.\n\nCatalogs are designed so that a simple file server on the web or object store like Amazon S3 can store JSON that defines a \nfull Catalog. More dynamic services can also return a Catalog structure, and the [STAC API](https://github.com/radiantearth/stac-api-spec)\nspecification contains an OpenAPI definition of the standard way to do this, at the `/` endpoint. \n\n## In this directory\n\n**Specification:** The main Catalog specification is in *[catalog-spec.md](catalog-spec.md)*.\nIt includes in depth explanation of the structures and fields.\n\n**Schemas:** The schemas to validate the core Catalog definition are found in the *[json-schema/](json-schema/)* folder.\nThe primary one is *[catalog.json](json-schema/catalog.json)*.\n\n## Catalog Evolution \n\nThe Catalog specification is maturing, but it is still relatively early days. The core of Catalog has been defined very\nnarrowly, to just describe a structure that can be followed by people or machines, so most additional functionality will\nbe defined in additional specifications and extensions. The only anticipated changes to the core of Catalog are to add in\nadditional extension mechanisms for others to use.\n"
  },
  {
    "path": "stac-spec/catalog-spec/catalog-spec.md",
    "content": "# STAC Catalog Specification <!-- omit in toc --> \n\n- [Catalog fields](#catalog-fields)\n  - [Additional Field Information](#additional-field-information)\n    - [stac_version](#stac_version)\n    - [stac_extensions](#stac_extensions)\n  - [Link Object](#link-object)\n    - [Relation types](#relation-types)\n- [Media Types](#media-types)\n  - [Media Type for STAC Catalogs](#media-type-for-stac-catalogs)\n  - [STAC Media Types](#stac-media-types)\n- [Extensions](#extensions)\n\nThis document explains the structure and content of a STAC **Catalog** object. A STAC Catalog object \nrepresents a logical group of other Catalog, \n[Collection](../collection-spec/collection-spec.md), and [Item](../item-spec/item-spec.md) objects. \nThese Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called \nsub-catalogs) that contain links to Collections and Items. The division of sub-catalogs is up to the implementor,\nbut is generally done to aid the ease of online browsing by people. \n\nA Catalog object will typically be the entry point into a STAC catalog. Their \npurpose is discovery: to be browsed by people or be crawled\nby clients to build a searchable index.  \n\nAny JSON object that contains all the required fields is a valid STAC Catalog object.\n\n- [Examples](../examples/)\n  - See an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid\n  Catalog file, demonstrating linking to items (it is also a Collection, so has additional fields)\n- [JSON Schema](json-schema/catalog.json)\n\nThe [Catalog section of the Overview](../overview.md#catalog-overview) document provides background information on \nthe structure of Catalogs as well as links to best practices. This specification lays out the requirements\nand fields to be compliant.\n\nThis Catalog specification primarily defines a structure for information to be discoverable. Any use \nthat is publishing a set of related spatiotemporal assets is strongly recommended to also use the \nSTAC Collection specification to provide additional information about the set of Items \ncontained in a Catalog, in order to give contextual information to aid in discovery.\nSTAC Collections all have the same fields as STAC Catalogs, but with different allowed \nvalues for `type` and `stac_extensions`.\n\n## Catalog fields\n\n| Element         | Type          | Description                                                  |\n| --------------- | ------------- | ------------------------------------------------------------ |\n| type            | string        | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. |\n| stac_version    | string        | **REQUIRED.** The STAC version the Catalog implements. |\n| stac_extensions | \\[string]     | A list of extension identifiers the Catalog implements.                 |\n| id              | string        | **REQUIRED.** Identifier for the Catalog.                    |\n| title           | string        | A short descriptive one-line title for the Catalog.          |\n| 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. |\n| links           | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |\n\n### Additional Field Information\n\n#### stac_version\n\nIn general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind.\n\n#### stac_extensions\n\nA list of extensions the Catalog implements.\nThe list consists of URLs to JSON Schema files that can be used for validation.\nThis list must only contain extensions that extend the Catalog specification itself,\nsee the 'Scope' for each of the extensions.\nThis must **not** declare the extensions that are only implemented in child Collection objects or child Item objects.\n\n### Link Object\n\nThis object describes a relationship with another entity. Data providers are advised to be liberal\nwith links.\n\n| Field Name | Type   | Description |\n| ---------- | ------ | ----------- |\n| href       | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |\n| rel        | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter [\"Relation types\"](#relation-types) for more information. |\n| type       | string | [Media type](#media-types) of the referenced entity. |\n| title      | string | A human readable title to be used in rendered displays of the link. |\n\nFor a full discussion of the situations where relative and absolute links are recommended see the\n['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.\n\n#### Relation types\n\nThe following types are commonly used as `rel` types in the Link Object of a STAC Catalog:\n\n| Type    | Description |\n| ------- | ----------- |\n| 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. |\n| 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. |\n| parent  | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. |\n| child   | URL to a child STAC entity (Catalog or Collection). |\n| item    | URL to a STAC Item. |\n\n**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are\nallowed if there is an intent to populate it or its children were removed.\n\nThere are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as \nthey are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use\nthe ones above.\n\n## Media Types\n\nOne of the best ways to help inform web clients about the content in a link is to use a common [Media \nType](https://en.wikipedia.org/wiki/Media_type) in the `type` field. In STAC the `type` field is used in both the \n'[Link](#link-object)'' and '[Asset](../item-spec/item-spec.md#asset-object)' Objects. It is quite useful for STAC browsers to better determine\nwhat to render and display to users searching and browsing the Catalog.  Media types are often referred to by the \nnow deprecated term \"MIME types\". \n\n### Media Type for STAC Catalogs\n\nA STAC Catalog is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the \n[`application/json`](https://tools.ietf.org/html/rfc8259#section-11) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) \n(previously known as the MIME Type). \n\n### STAC Media Types\n\nThe following table lists the Media Types to use for STAC structures.\n\n| Media Type             | Description                                                |\n| ---------------------- | ---------------------------------------------------------- |\n| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md)                   |\n| `application/json`     | A STAC Catalog            |\n| `application/json`     | A STAC [Collection](../collection-spec/collection-spec.md) |\n\n## Extensions\n\nThe [extensions page](../extensions/) gives an overview about relevant extensions for STAC Catalogs.\n"
  },
  {
    "path": "stac-spec/catalog-spec/json-schema/catalog.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/catalog-spec/json-schema/catalog.json#\",\n  \"title\": \"STAC Catalog Specification\",\n  \"description\": \"This object represents Catalogs in a SpatioTemporal Asset Catalog.\",\n  \"allOf\": [\n    {\n      \"$ref\": \"#/definitions/catalog\"\n    }\n  ],\n  \"definitions\": {\n    \"catalog\": {\n      \"title\": \"STAC Catalog\",\n      \"type\": \"object\",\n      \"required\": [\n        \"stac_version\",\n        \"type\",\n        \"id\",\n        \"description\",\n        \"links\"\n      ],\n      \"properties\": {\n        \"stac_version\": {\n          \"title\": \"STAC version\",\n          \"type\": \"string\",\n          \"const\": \"1.0.0\"\n        },\n        \"stac_extensions\": {\n          \"title\": \"STAC extensions\",\n          \"type\": \"array\",\n          \"uniqueItems\": true,\n          \"items\": {\n            \"title\": \"Reference to a JSON Schema\",\n            \"type\": \"string\",\n            \"format\": \"iri\"\n          }\n        },\n        \"type\": {\n          \"title\": \"Type of STAC entity\",\n          \"const\": \"Catalog\"\n        },\n        \"id\": {\n          \"title\": \"Identifier\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"title\": {\n          \"title\": \"Title\",\n          \"type\": \"string\"\n        },\n        \"description\": {\n          \"title\": \"Description\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"links\": {\n          \"title\": \"Links\",\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/link\"\n          }\n        }\n      }\n    },\n    \"link\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"rel\",\n        \"href\"\n      ],\n      \"properties\": {\n        \"href\": {\n          \"title\": \"Link reference\",\n          \"type\": \"string\",\n          \"format\": \"iri-reference\",\n          \"minLength\": 1\n        },\n        \"rel\": {\n          \"title\": \"Link relation type\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"type\": {\n          \"title\": \"Link type\",\n          \"type\": \"string\"\n        },\n        \"title\": {\n          \"title\": \"Link title\",\n          \"type\": \"string\"\n        }\n      }\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/collection-spec/README.md",
    "content": "# STAC Collection Specification\n\nA STAC [Collection](collection-spec.md) object is used to describe a group of related \nItems. It builds on fields defined for a [Catalog](../catalog-spec/catalog-spec.md) object\nby further defining and explaining logical groups of [Items](../item-spec/item-spec.md). A\nCollection can have parent Catalog and Collection objects, as well as child Item, Catalog, \nand Collection objects. These parent-child relationships among objects of these types, as there is no \nsubtyping relationship between the Collection and Catalog types, even through they share field names.\n\nA Collection provides a flexible mechanism to provide additional metadata about a set of Items.  \nGenerally, is used to describe a set of assets that \nare defined with the same properties and share higher-level metadata. There is no \nstandardized name for this sort of logical grouping, but other places it is called a \"\ndataset series\" (ESA, ISO 19115), \"collection\" (CNES, NASA), \"dataset\" (JAXA), or \"product\"\n(JAXA). In GIS terms, the Items are\n'[features](https://en.wikipedia.org/wiki/Simple_Features)' (that link to assets) and \na Collection is the 'layer'. STAC uses the same terms as the\n[OGC Features API](https://ogcapi.ogc.org/features/). A STAC Collection is a valid \n[Feature API Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4), \nextending it with additional fields.\n\nThus, the additional fields in a Collection detail the type of information a user would want to \nknow about the group of Items it contains. Items are required to provide a link back to their \ncollection definition. But the Collection is independent of STAC Items and STAC Catalogs, and thus \nother parties can also use this specification standalone, as a way to describe collections in a \nlightweight way. For more details on how the STAC specs fit together see the [overview](../overview.md) \ndocument. \n\n## In this directory\n\n**Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*.\nIt includes an overview and in depth explanation of the \nstructures and fields.\n\n**Schemas:** The schemas to validate the STAC Collection definition are found in the \n*[json-schema/](json-schema/)* folder. The primary one is *[collection.json](json-schema/collection.json)*.\n\n## Collection Flexibility\n\nSTAC Collections are defined for flexibility. They only require a handful of fields, and\nimplementors are free to add most any JSON field or object that they want via extensions.\nThis flexibility and extensibility is a design goal, so that it is quite easy to implement\na collection and be able to adapt it to most any data model.\n\nImplementors are encouraged to do what makes sense for them, and to check out the [examples](../examples/) and \n[other implementations](https://stacindex.org/catalogs) for current best practices.\n"
  },
  {
    "path": "stac-spec/collection-spec/collection-spec.md",
    "content": "# STAC Collection Specification <!-- omit in toc --> \n\n- [Overview](#overview)\n- [Collection fields](#collection-fields)\n  - [Additional Field Information](#additional-field-information)\n    - [stac_version](#stac_version)\n    - [stac_extensions](#stac_extensions)\n    - [id](#id)\n    - [license](#license)\n    - [summaries](#summaries)\n    - [assets](#assets)\n  - [Extent Object](#extent-object)\n    - [Spatial Extent Object](#spatial-extent-object)\n    - [Temporal Extent Object](#temporal-extent-object)\n  - [Provider Object](#provider-object)\n  - [Link Object](#link-object)\n    - [Relation types](#relation-types)\n  - [Asset Object](#asset-object)\n  - [Range Object](#range-object)\n  - [JSON Schema Object](#json-schema-object)\n- [Media Type for STAC Collections](#media-type-for-stac-collections)\n- [Standalone Collections](#standalone-collections)\n\n## Overview\n\nThe STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata. The \nCollection Specification shares all fields with the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) (with different allowed \nvalues for `type` and `stac_extensions`) and adds fields to describe the whole dataset and the included set of Items. Collections \ncan have both parent Catalogs and Collections and child Items, Catalogs and Collections. \n\nA STAC Collection is represented in JSON format.\nAny JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog.\n\nSTAC Collections are compatible with the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4) JSON \nspecified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they are extended with additional fields.  \n\n- [Examples](../examples/):\n  - Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items.\n  - Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items.\n  - Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight\n  various [extension](../extensions) functionality, but serves as another example.\n- [JSON Schema](json-schema/collection.json)\n\n## Collection fields\n\n| Element         | Type                                             | Description                                                  |\n| --------------- | ------------------------------------------------ | ------------------------------------------------------------ |\n| type            | string                                           | **REQUIRED.** Must be set to `Collection` to be a valid Collection. |\n| stac_version    | string                                           | **REQUIRED.** The STAC version the Collection implements. |\n| stac_extensions | \\[string]                                        | A list of extension identifiers the Collection implements.   |\n| id              | string                                           | **REQUIRED.** Identifier for the Collection that is unique across the provider. |\n| title           | string                                           | A short descriptive one-line title for the Collection.       |\n| 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. |\n| keywords        | \\[string]                                        | List of keywords describing the Collection.                  |\n| 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. |\n| 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. |\n| extent          | [Extent Object](#extent-object)                  | **REQUIRED.** Spatial and temporal extents.                  |\n| summaries       | Map<string, \\[\\*]\\|[Range Object](#range-object)\\|[JSON Schema Object](#json-schema-object)> | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). |\n| links           | \\[[Link Object](#link-object)]                   | **REQUIRED.** A list of references to other documents.       |\n| assets          | Map<string, [Asset Object](#asset-object)>       | Dictionary of asset objects that can be downloaded, each with a unique key. |\n\n### Additional Field Information\n\n#### stac_version\n\nIn general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind.\n\n#### stac_extensions\n\nA list of extensions the Collection implements.\nThe list consists of URLs to JSON Schema files that can be used for validation.\nThis list must only contain extensions that extend the Collection specification itself,\nsee the the 'Scope' for each of the extensions.\nThis must **not** declare the extensions that are only implemented in child Collection objects or child Item objects.\n\n#### id\n\nIt is important that Collection identifiers are unique across the provider. And providers should strive as much as possible to make\ntheir Collection ids 'globally' unique, prefixing any common information with a unique string. This could be the provider's name if\nit is a fairly unique name, or their name combined with the domain they operate in.\n\n#### license\n\nCollection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/).\nAlternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply.\nIn all cases links to the license texts SHOULD be added, see the `license` link relation type.\nIf no link to a license is included and the `license` field is set to `proprietary`, the Collection is private,\nand consumers have not been granted any explicit right to use the data.\n\n#### summaries\n\nCollections are *strongly recommended* to provide summaries of the values of fields that they can expect from the `properties` \nof STAC Items contained in this Collection. This enables users to get a good sense of what the ranges and potential values of \ndifferent fields in the Collection are, without having to inspect a number of Items (or crawl them exhaustively to get a definitive answer). \nSummaries are often used to give users a sense of the data in [Standalone Collections](#standalone-collections),\ndescribing the potential values even when it can't be accessed as Items. They also give clients enough information to \nbuild tailored user interfaces for querying the data, by presenting the potential values that are available.\n Fields selected to be included in summaries should capture all the potential values of the \n field that appear in every Item underneath the collection, including in any nested sub-Catalogs.\n\nA summary for a field can be specified in three ways:\n\n1. 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.\n   If the field summarizes an array (e.g. [`instruments`](../item-spec/common-metadata.md#instrument)),\n   the field's array elements of each Item must be merged to a single array with unique elements.\n2. A Range in a [Range Object](#range-object): Statistics by default only specify the range (minimum and maximum values),\n   but can optionally be accompanied by additional statistical values.\n   The range specified by the `minimum` and `maximum` properties can specify the potential range of values,\n   but it is recommended to be as precise as possible.\n3. Extensible JSON Schema definitions for fine-grained information, see the [JSON Schema Object](#json-schema-object)\n   section for more.\n\nAll values must follow the schema of the property field they summarize, unless the field is an array as described in (1) above.\nSo the values in the array or the values given for `minimum` and `maximum` must comply to the original data type\nand any further restrictions that apply for the property they summarize.\nFor example, the `minimum` for `gsd` can't be lower than zero and the summaries for `platform` and `instruments`\nmust each be an array of strings (or alternatively minimum and maximum values, but that's not very meaningful).\n\nIt is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items.\nNevertheless, it is not very useful to list all potential `title` values of the Items.\nAlso, a range for the `datetime` property may be better suited to be included in the STAC Collection's `extent` field.\nIn general, properties that are covered by the Collection specification should not be repeated in the summaries.\n\nSee the [examples folder](../examples) for Collections with summaries to get a sense of how to use them.\n\n#### assets\n\nThis provides an optional mechanism to expose assets that don't make sense at the Item level.\nIt is a dictionary of [Asset Objects](#asset-object) associated with the Collection that can be\ndownloaded or streamed, each with a unique key.\nIn general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers.\nProviders may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them.\nTo communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object).\nThe definition provided here, at the Collection level, is the same as the\n[Asset Object in Items](../item-spec/item-spec.md#asset-object).\n\nThere are a few guidelines for using the asset construct at the Collection level:\n\n- Collection-level assets SHOULD NOT list any files also available in Items.\n- If possible, item-level assets are always the preferable way to expose assets.\n\nCollection-level assets can be useful in some scenarios, for example:\n1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item.\n   This can be Collection-level metadata or a thumbnail for visualization purposes.\n2. Individual Items can't properly be distinguished for some data structures,\n   e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files.\n3. Exposing assets for\n   \"[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)\".\n\nOftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use\nItems as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another\noption.\n\n### Extent Object\n\nThe object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified.\n\n| Element  | Type                                              | Description                                                           |\n| -------- | ------------------------------------------------- | --------------------------------------------------------------------- |\n| spatial  | [Spatial Extent Object](#spatial-extent-object)   | **REQUIRED.** Potential *spatial extents* covered by the Collection.  |\n| temporal | [Temporal Extent Object](#temporal-extent-object) | **REQUIRED.** Potential *temporal extents* covered by the Collection. |\n\n#### Spatial Extent Object\n\nThe object describes the spatial extents of the Collection.\n\n| Element | Type         | Description                                                          |\n| ------- | ------------ | -------------------------------------------------------------------- |\n| bbox    | \\[\\[number]] | **REQUIRED.** Potential *spatial extents* covered by the Collection. |\n\n**bbox**: Each outer array element can be a separate spatial extent describing the bounding boxes\nof the assets represented by this Collection using either 2D or 3D geometries.\n\nThe first bounding box always describes the overall spatial extent of the data. All subsequent bounding boxes can be\nused to provide a more precise description of the extent and identify clusters of data.\nClients only interested in the overall spatial extent will only need to access the first item in each array.\nIt is recommended to only use multiple bounding boxes if a union of them would then include\na large uncovered area (e.g. the union of Germany and Chile).\n\nThe length of the inner array must be 2*n where n is the number of dimensions.\nThe array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in\nLongitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84).\nWhen using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters\nand the elevation of the northeasterly most extent is the maximum.\n\nThe coordinate reference system of the values is WGS 84 longitude/latitude.\nExample that covers the whole Earth: `[[-180.0, -90.0, 180.0, 90.0]]`.\nExample 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]]`.\n\n#### Temporal Extent Object\n\nThe object describes the temporal extents of the Collection.\n\n| Element  | Type               | Description                                                           |\n| -------- | ------------------ | --------------------------------------------------------------------- |\n| interval | \\[\\[string\\|null]] | **REQUIRED.** Potential *temporal extents* covered by the Collection. |\n\n**interval**: Each outer array element can be a separate temporal extent.\nThe first time interval always describes the overall temporal extent of the data. All subsequent time intervals\ncan be used to provide a more precise description of the extent and identify clusters of data.\nClients only interested in the overall extent will only need to access the first item in each array.\nIt is recommended to only use multiple temporal extents if a union of them would then include a large\nuncovered time span (e.g. only having data for the years 2000, 2010 and 2020).\n\nEach inner array consists of exactly two elements, either a timestamp or `null`.\n\nTimestamps consist of a date and time in UTC and MUST be formatted according to\n[RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\nThe temporal reference system is the Gregorian calendar.\n\nOpen date ranges are supported by setting the start and/or the end time to `null`.\nExample for data from the beginning of 2019 until now: `[[\"2019-01-01T00:00:00Z\", null]]`.\nIt is recommended to provide at least a rough guideline on the temporal extent and thus\nit's not recommended to set both start and end time to `null`. Nevertheless, this is possible\nif there's a strong use case for an open date range to both sides.\n\n### Provider Object\n\nThe object provides information about a provider.\nA provider is any of the organizations that captures or processes the content of the Collection\nand therefore influences the data offered by this Collection.\nMay also include information about the final storage provider hosting the data.\n\n| Field Name  | Type      | Description                                                  |\n| ----------- | --------- | ------------------------------------------------------------ |\n| name        | string    | **REQUIRED.** The name of the organization or the individual. |\n| 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. |\n| roles       | \\[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. |\n| url         | string    | Homepage on which the provider describes the dataset and publishes contact information. |\n\n**roles**: The provider's role(s) can be one or more of the following elements:\n\n- *licensor*: The organization that is licensing the dataset under the license specified in the Collection's `license` field.\n- *producer*: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data.\n- *processor*: A processor is any provider who processed data to a derived product.\n- *host*: The host is the actual provider offering the data on their storage.\n  There should be no more than one host, specified as last element of the list.\n\n### Link Object\n\nThis object describes a relationship with another entity. Data providers are advised to be liberal with links.\n\n| Field Name | Type   | Description                                                  |\n| ---------- | ------ | ------------------------------------------------------------ |\n| href       | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |\n| rel        | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter \"[Relation types](#relation-types)\" for more information. |\n| type       | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |\n| title      | string | A human readable title to be used in rendered displays of the link. |\n\nFor a full discussion of the situations where relative and absolute links are recommended see the\n['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.\n\n#### Relation types\n\nSTAC Collections use a variety of `rel` types in the link object,\nto describe the exact nature of the link between this Collection and the entity it is linking to.\nIt is recommended to use the official\n[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible.\nThe following table explains places where custom STAC `rel` types are used for ollections.\nThis 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.\n\n| Type    | Description                                                  |\n| ------- | ------------------------------------------------------------ |\n| 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. |\n| 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. |\n| parent  | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. |\n| child   | URL to a child STAC entity (Catalog or Collection). |\n| 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). |\n| 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. |\n| 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. |\n\nA more complete list of possible `rel` types and their meaning in STAC can be found in the\n[Using Relation Types](../best-practices.md#using-relation-types) best practice. \n\n**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog.\nThis is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs,\nit is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection\nwith the [`collection` relation type](../item-spec/item-spec.md#relation-types).\n\n### Asset Object\n\nAn Asset is an object that contains a URI to data associated with the Collection that can be downloaded\nor streamed. The definition provided here, at the Collection level, is the same as the\n[Asset Object in Items](../item-spec/item-spec.md#asset-object). It is allowed to add additional fields.\n\n| Field Name  | Type      | Description |\n| ----------- | --------- | ----------- |\n| href        | string    | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |\n| title       | string    | The displayed title for clients and users. |\n| 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. |\n| 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. |\n| roles       | \\[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. |\n\n### Range Object\n\nFor summaries that would normally consist of a lot of continuous values, statistics can be added instead.\nBy default, only ranges with a minimum and a maximum value can be specified.\nRanges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values only,\nwhich means they need to have a rank order.\nTherefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times.\nImplementors are free to add other derived statistical values to the object, for example `mean` or `stddev`.\n\n| Field Name | Type           | Description |\n| ---------- | -------------- | ----------- |\n| minimum    | number\\|string | **REQUIRED.** Minimum value. |\n| maximum    | number\\|string | **REQUIRED.** Maximum value. |\n\n### JSON Schema Object\n\nFor a full understanding of the summarized field, a JSON Schema can be added for each summarized field.\nThis allows very fine-grained information for each field and each value as JSON Schema is also extensible.\nEach schema must be valid against all corresponding values available for the property in the sub-Items.\n\nIt is recommended to use [JSON Schema draft-07](https://json-schema.org/specification-links.html#draft-7)\nto align with the JSON Schemas provided by STAC. Empty schemas are not allowed.\n\nFor an introduction to JSON Schema, see \"[Learn JSON Schema](https://json-schema.org/learn/)\".\n\n## Media Type for STAC Collections\n\nA STAC Collection is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the \n[`application/json`](https://tools.ietf.org/html/rfc8259#section-11) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) \n(previously known as the MIME Type). \n\n## Standalone Collections\n\nSTAC Collections which don't link to any Item are called **standalone Collections**.\nTo describe them with more fields than the Collection fields has to offer,\nit is allowed to re-use the metadata fields defined by extensions for Items in the `summaries` field.\nThis makes much sense for fields such as `platform` or `proj:epsg`, which are often the same for a whole Collection,\nbut doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection.\nThe data provider is free to decide, which fields are reasonable to be used.\n"
  },
  {
    "path": "stac-spec/collection-spec/json-schema/collection.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json#\",\n  \"title\": \"STAC Collection Specification\",\n  \"description\": \"This object represents Collections in a SpatioTemporal Asset Catalog.\",\n  \"allOf\": [\n    {\n      \"$ref\": \"#/definitions/collection\"\n    }\n  ],\n  \"definitions\": {\n    \"collection\": {\n      \"title\": \"STAC Collection\",\n      \"description\": \"These are the fields specific to a STAC Collection. All other fields are inherited from STAC Catalog.\",\n      \"type\": \"object\",\n      \"required\": [\n        \"stac_version\",\n        \"type\",\n        \"id\",\n        \"description\",\n        \"license\",\n        \"extent\",\n        \"links\"\n      ],\n      \"properties\": {\n        \"stac_version\": {\n          \"title\": \"STAC version\",\n          \"type\": \"string\",\n          \"const\": \"1.0.0\"\n        },\n        \"stac_extensions\": {\n          \"title\": \"STAC extensions\",\n          \"type\": \"array\",\n          \"uniqueItems\": true,\n          \"items\": {\n            \"title\": \"Reference to a JSON Schema\",\n            \"type\": \"string\",\n            \"format\": \"iri\"\n          }\n        },\n        \"type\": {\n          \"title\": \"Type of STAC entity\",\n          \"const\": \"Collection\"\n        },\n        \"id\": {\n          \"title\": \"Identifier\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"title\": {\n          \"title\": \"Title\",\n          \"type\": \"string\"\n        },\n        \"description\": {\n          \"title\": \"Description\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"keywords\": {\n          \"title\": \"Keywords\",\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"string\"\n          }\n        },\n        \"license\": {\n          \"title\": \"Collection License Name\",\n          \"type\": \"string\",\n          \"pattern\": \"^[\\\\w\\\\-\\\\.\\\\+]+$\"\n        },\n        \"providers\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\n              \"name\"\n            ],\n            \"properties\": {\n              \"name\": {\n                \"title\": \"Organization name\",\n                \"type\": \"string\"\n              },\n              \"description\": {\n                \"title\": \"Organization description\",\n                \"type\": \"string\"\n              },\n              \"roles\": {\n                \"title\": \"Organization roles\",\n                \"type\": \"array\",\n                \"items\": {\n                  \"type\": \"string\",\n                  \"enum\": [\n                    \"producer\",\n                    \"licensor\",\n                    \"processor\",\n                    \"host\"\n                  ]\n                }\n              },\n              \"url\": {\n                \"title\": \"Organization homepage\",\n                \"type\": \"string\",\n                \"format\": \"iri\"\n              }\n            }\n          }\n        },\n        \"extent\": {\n          \"title\": \"Extents\",\n          \"type\": \"object\",\n          \"required\": [\n            \"spatial\",\n            \"temporal\"\n          ],\n          \"properties\": {\n            \"spatial\": {\n              \"title\": \"Spatial extent object\",\n              \"type\": \"object\",\n              \"required\": [\n                \"bbox\"\n              ],\n              \"properties\": {\n                \"bbox\": {\n                  \"title\": \"Spatial extents\",\n                  \"type\": \"array\",\n                  \"minItems\": 1,\n                  \"items\": {\n                    \"title\": \"Spatial extent\",\n                    \"type\": \"array\",\n                    \"oneOf\": [\n                      {\n                        \"minItems\":4,\n                        \"maxItems\":4\n                      },\n                      {\n                        \"minItems\":6,\n                        \"maxItems\":6\n                      }\n                    ],\n                    \"items\": {\n                      \"type\": \"number\"\n                    }\n                  }\n                }\n              }\n            },\n            \"temporal\": {\n              \"title\": \"Temporal extent object\",\n              \"type\": \"object\",\n              \"required\": [\n                \"interval\"\n              ],\n              \"properties\": {\n                \"interval\": {\n                  \"title\": \"Temporal extents\",\n                  \"type\": \"array\",\n                  \"minItems\": 1,\n                  \"items\": {\n                    \"title\": \"Temporal extent\",\n                    \"type\": \"array\",\n                    \"minItems\": 2,\n                    \"maxItems\": 2,\n                    \"items\": {\n                      \"type\": [\n                        \"string\",\n                        \"null\"\n                      ],\n                      \"format\": \"date-time\",\n                      \"pattern\": \"(\\\\+00:00|Z)$\"\n                    }\n                  }\n                }\n              }\n            }\n          }\n        },\n        \"assets\": {\n          \"$ref\": \"../../item-spec/json-schema/item.json#/definitions/assets\"\n        },\n        \"links\": {\n          \"title\": \"Links\",\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/link\"\n          }\n        },\n        \"summaries\": {\n          \"$ref\": \"#/definitions/summaries\"\n        }\n      }\n    },\n    \"link\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"rel\",\n        \"href\"\n      ],\n      \"properties\": {\n        \"href\": {\n          \"title\": \"Link reference\",\n          \"type\": \"string\",\n          \"format\": \"iri-reference\",\n          \"minLength\": 1\n        },\n        \"rel\": {\n          \"title\": \"Link relation type\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"type\": {\n          \"title\": \"Link type\",\n          \"type\": \"string\"\n        },\n        \"title\": {\n          \"title\": \"Link title\",\n          \"type\": \"string\"\n        }\n      }\n    },\n    \"summaries\": {\n      \"type\": \"object\",\n      \"additionalProperties\": {\n        \"anyOf\": [\n          {\n            \"title\": \"JSON Schema\",\n            \"type\": \"object\",\n            \"minProperties\": 1,\n            \"allOf\": [\n              {\n                \"$ref\": \"http://json-schema.org/draft-07/schema\"\n              }\n            ]\n          },\n          {\n            \"title\": \"Range\",\n            \"type\": \"object\",\n            \"required\": [\n              \"minimum\",\n              \"maximum\"\n            ],\n            \"properties\": {\n              \"minimum\": {\n                \"title\": \"Minimum value\",\n                \"type\": [\n                  \"number\",\n                  \"string\"\n                ]\n              },\n              \"maximum\": {\n                \"title\": \"Maximum value\",\n                \"type\": [\n                  \"number\",\n                  \"string\"\n                ]\n              }\n            }\n          },\n          {\n            \"title\": \"Set of values\",\n            \"type\": \"array\",\n            \"minItems\": 1,\n            \"items\": {\n              \"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.\"\n            }\n          }\n        ]\n      }\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/examples/README.md",
    "content": "# STAC Examples\n\nThis directory contains various examples for all parts of the STAC specification.\nIt is structured to be two valid STACs, meaning both [catalog.json](catalog.json) and [collection.json](collection.json)\nshould successfully load in various tools. They do not follow *all* the [best practices](../best-practices.md) for STAC, mostly\ndue 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.\n\nThe various fields are mostly fictional, to be able to demonstrate the various aspects of the spec as tersely as possible. To get a sense\nof real world STAC implementations we recommend exploring the [stac-examples](http://github.com/stac-utils/stac-examples) repo, which \ngathers in one place copies of STAC [Items](../item-spec/item-spec.md) and [Collection](../collection-spec/collection-spec.md) \nfrom a number of different production catalogs that all follow good STAC practices. And you should also explore the various catalogs\nlisted on [STAC Index](http://stacindex.org), to see full catalogs in production.\n\n## Organization\n\nThis directory contains two STAC implementations, both valid, but simplified a bit to be illustrative of the key concepts, so \nthey do not quite follow all the best practices. \n\n### Simple Collection\n\nThis STAC implementation consists of three files, all contained at the root of the examples directory\n\n**[collection.json](collection.json)** is a minimal 'simple collection', that links to three items. \n\n**[simple-item.json](simple-item.json)** is the most minimal possible compliant Item record. Most all data will\ninclude additional fields, as STAC is designed to be a minimal common subset. But it is useful for showing exactly what is\nrequired.\n\n**[core-item.json](core-item.json)** is a more realistic example, for a hypothetical analytic image \nacquisition from a satellite company called 'Remote Data'. It includes additional fields covering the [common \nmetadata](../item-spec/common-metadata.md). It also links to a variety of assets that is typical for\nsatellite imagery, as most providers include a number of complementary files.\n\n**[extended-item.json](extended-item.json)** is arguably an even more realistic example, as it includes a number of the\n[extensions](../extensions/) that are commonly used, to demonstrate how implementations tend to start with the core, and add in\na number of the core extensions. \n\n**[collectionless-item.json](collectionless-item.json)** demonstrates the common metadata that is only used when an Item does not have \na collection. It is recommended to organize items in collections, but we wanted to show how this works. This is not technically in the\n'simple collection' of this section, but it follows the same pattern, so is included here.\n\n### Nested Catalog\n\nThis STAC implementation shows a common pattern, starting with a catalog that links to a number of distinct collections, which may\nlink down to a number of items.\n\n**[catalog.json](catalog.json)** is a minimal catalog implementation, linking to two other collections.\n\n**[collection-only/collection.json](collection-only/collection.json)** is a collection that does not link to any items. This\ndemonstrates how is is possible to make use of STAC Collections without needing items, to serve as nice summarizing metadata for \ntools that work with full layers / collections. This example collection is based on real Sentinel-2 values, so is not quite fictional,\nbut should be taken as just an example.\n\n**[extensions-collection/collection.json](extensions-collection/collection.json)** contains a small number of items, that demonstrate\nmore functionality available in STAC [extensions](../extensions/). These are linked to directly from the individual extensions. These\nitems follow the recommendations for [Catalog Layout Best Practices](../best-practices.md#catalog-layout).\n\n## In Depth\n\nAs mentioned above, the files in this examples directory form valid STAC implementations. They are all based on a \nfictional remote sensing company called 'Remote Data', with a URL at remotedata.io. This domain has not been set up, so those links\nwill not work, but any valid data provider should provide valid links to their homepage. \n\nThe examples use the `rd:` prefix to show how providers can use custom fields when there are not set fields. In the examples these\ndo not link to a schema which is completely valid, but it is recommended that providers do write a JSON schema that can validate \ntheir custom fields (we will work to add an example schema for the `rd:` fields in the future). \n\n### Catalog Type\n\nOne of the most important STAC Best Practices is to [use links consistently](../best-practices.md#use-of-links), following one of the\ndescribed 'catalog types'. The catalogs described here are [Relative Published Catalogs](../best-practices.md#relative-published-catalog),\nthat use absolute URL's to refer to their assets (so would be an example of a [Self-contained Metadata \nOnly](../best-practices.md#self-contained-metadata-only) catalog that is published).\n\n### Differences with STAC Best Practices\n\nOne of the most important documents in this repository is the one about [best practices](../best-practices.md). It describes a number\nof practical recommendations gained by people actually implementing STAC. The core spec is designed to be as flexible as possible, so\nthat it is not too rigid and unable to handle unanticipated needs. But we recommend following as many of the best practices as is \nfeasible, as it will help ensure various STAC tools work much better. The examples in this folder don't align with all the best\npractices, mostly because they are meant to demonstrate things as tersely as possible, and also because they live directly inside\na github repository. As many people will look at these examples and take them as 'how things should be' we felt its important to\nhighlight where things here differ from the actual best practices.\n\n#### Catalog Layout\n\nAnother important recommendations concerns the [layout of STAC catalogs](../best-practices.md#catalog-layout). This is important\nfor tools to be able to expect a certain layout, and most tools will follow the described layout. The simple collection that consists\nof 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\nthe 'examples' folder, so people don't have to dig deep into folders to get a quick example. But a proper catalog layout would\nput the items in sub-directories, along with their assets.\n"
  },
  {
    "path": "stac-spec/examples/catalog.json",
    "content": "{\n  \"id\": \"examples\",\n  \"type\": \"Catalog\",\n  \"title\": \"Example Catalog\",\n  \"stac_version\": \"1.0.0\",\n  \"description\": \"This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.\",\n  \"links\": [\n    {\n      \"rel\": \"root\",\n      \"href\": \"./catalog.json\",\n      \"type\": \"application/json\"\n    },\n    {\n      \"rel\": \"child\",\n      \"href\": \"./extensions-collection/collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection Demonstrating STAC Extensions\"\n    },\n    {\n      \"rel\": \"child\",\n      \"href\": \"./collection-only/collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection with no items (standalone)\"\n    },\n    {\n      \"rel\": \"child\",\n      \"href\": \"./collection-only/collection-with-schemas.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection with no items (standalone with JSON Schemas)\"\n    },\n    {\n      \"rel\": \"item\",\n      \"href\": \"./collectionless-item.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection with no items (standalone)\"\n    },\n    {\n      \"rel\": \"self\",\n      \"href\": \"https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/catalog.json\",\n      \"type\": \"application/json\"\n    }\n  ]\n}\n"
  },
  {
    "path": "stac-spec/examples/collection-only/collection-with-schemas.json",
    "content": "{\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/sat/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/view/v1.0.0/schema.json\"\n  ],\n  \"id\": \"sentinel-2\",\n  \"type\": \"Collection\",\n  \"title\": \"Sentinel-2 MSI: MultiSpectral Instrument, Level-2A\",\n  \"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\",\n  \"license\": \"proprietary\",\n  \"extent\": {\n    \"spatial\": {\n      \"bbox\": [\n        [\n          -180,\n          -82.852377834669,\n          180,\n          82.819463367711\n        ]\n      ]\n    },\n    \"temporal\": {\n      \"interval\": [\n        [\n          \"2017-04-12T02:57:21.459000Z\",\n          \"2021-04-22T11:30:12.767000Z\"\n        ]\n      ]\n    }\n  },\n  \"links\": [\n    {\n      \"rel\": \"parent\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"license\",\n      \"href\": \"https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf\",\n      \"title\": \"Legal notice on the use of Copernicus Sentinel Data and Service Information\"\n    }\n  ],\n  \"providers\": [\n    {\n      \"name\": \"European Union/ESA/Copernicus\",\n      \"roles\": [\n        \"producer\",\n        \"licensor\"\n      ],\n      \"url\": \"https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi\"\n    },\n    {\n      \"name\": \"AWS\",\n      \"roles\": [\n        \"host\"\n      ],\n      \"url\": \"https://registry.opendata.aws/sentinel-2/\"\n    },\n    {\n      \"name\": \"jeobrowser\",\n      \"roles\": [\n        \"processor\"\n      ],\n      \"url\": \"https://github.com/jjrom/resto\"\n    }\n  ],\n  \"summaries\": {\n    \"datetime\": {\n      \"minimum\": \"2017-04-12T02:57:21Z\",\n      \"maximum\": \"2021-04-22T11:30:12Z\"\n    },\n    \"instruments\": {\n      \"type\": \"string\",\n      \"const\": \"msi\",\n      \"title\": \"Multispectral Intrument\",\n      \"count\": 6613431\n    },\n    \"resto:landcover\": {\n      \"type\": \"string\",\n      \"oneOf\": [\n        {\n          \"const\": \"cultivated\",\n          \"title\": \"Cultivated\",\n          \"count\": 490750\n        },\n        {\n          \"const\": \"desert\",\n          \"title\": \"Desert\",\n          \"count\": 543120\n        },\n        {\n          \"const\": \"flooded\",\n          \"title\": \"Flooded\",\n          \"count\": 5187\n        },\n        {\n          \"const\": \"forest\",\n          \"title\": \"Forest\",\n          \"count\": 767807\n        },\n        {\n          \"const\": \"herbaceous\",\n          \"title\": \"Herbaceous\",\n          \"count\": 674281\n        },\n        {\n          \"const\": \"ice\",\n          \"title\": \"Ice\",\n          \"count\": 231285\n        },\n        {\n          \"const\": \"urban\",\n          \"title\": \"Urban\",\n          \"count\": 1219\n        },\n        {\n          \"const\": \"water\",\n          \"title\": \"Water\",\n          \"count\": 2303314\n        }\n      ]\n    },\n    \"resto:location\": {\n      \"type\": \"string\",\n      \"oneOf\": [\n        {\n          \"const\": \"tropical\",\n          \"title\": \"Tropical\",\n          \"count\": 1807474\n        },\n        {\n          \"const\": \"southern\",\n          \"title\": \"Southern\",\n          \"count\": 1671685\n        },\n        {\n          \"const\": \"northern\",\n          \"title\": \"Northern\",\n          \"count\": 4876669\n        },\n        {\n          \"const\": \"equatorial\",\n          \"title\": \"Equatorial\",\n          \"count\": 27302\n        },\n        {\n          \"const\": \"coastal\",\n          \"title\": \"Coastal\",\n          \"count\": 1495516\n        }\n      ]\n    },\n    \"platform\": {\n      \"type\": \"string\",\n      \"oneOf\": [\n        {\n          \"const\": \"sentinel-2b\",\n          \"title\": \"Sentinel 2B\",\n          \"count\": 3495597\n        },\n        {\n          \"const\": \"sentinel-2a\",\n          \"title\": \"Sentinel 2A\",\n          \"count\": 3117831\n        }\n      ]\n    },\n    \"resto:season\": {\n      \"type\": \"integer\",\n      \"oneOf\": [\n        {\n          \"const\": 0,\n          \"title\": \"Winter\",\n          \"count\": 1621108\n        },\n        {\n          \"const\": 2,\n          \"title\": \"Summer\",\n          \"count\": 2279472\n        },\n        {\n          \"const\": 1,\n          \"title\": \"Spring\",\n          \"count\": 1577067\n        },\n        {\n          \"const\": 3,\n          \"title\": \"Autumn\",\n          \"count\": 1098015\n        }\n      ]\n    },\n    \"eo:bands\": [\n      {\n        \"title\": \"B1\",\n        \"common_name\": \"coastal\",\n        \"center_wavelength\": 4.439,\n        \"gsd\": 60\n      },\n      {\n        \"title\": \"B2\",\n        \"common_name\": \"blue\",\n        \"center_wavelength\": 4.966,\n        \"gsd\": 10\n      },\n      {\n        \"title\": \"B3\",\n        \"common_name\": \"green\",\n        \"center_wavelength\": 5.6,\n        \"gsd\": 10\n      },\n      {\n        \"title\": \"B4\",\n        \"common_name\": \"red\",\n        \"center_wavelength\": 6.645,\n        \"gsd\": 10\n      },\n      {\n        \"title\": \"B5\",\n        \"center_wavelength\": 7.039,\n        \"gsd\": 20\n      },\n      {\n        \"title\": \"B6\",\n        \"center_wavelength\": 7.402,\n        \"gsd\": 20\n      },\n      {\n        \"title\": \"B7\",\n        \"center_wavelength\": 7.825,\n        \"gsd\": 20\n      },\n      {\n        \"title\": \"B8\",\n        \"common_name\": \"nir\",\n        \"center_wavelength\": 8.351,\n        \"gsd\": 10\n      },\n      {\n        \"title\": \"B8A\",\n        \"center_wavelength\": 8.648,\n        \"gsd\": 20\n      },\n      {\n        \"title\": \"B9\",\n        \"center_wavelength\": 9.45,\n        \"gsd\": 60\n      },\n      {\n        \"title\": \"B10\",\n        \"center_wavelength\": 1.3735,\n        \"gsd\": 60\n      },\n      {\n        \"title\": \"B11\",\n        \"common_name\": \"swir16\",\n        \"center_wavelength\": 1.6137,\n        \"gsd\": 20\n      },\n      {\n        \"title\": \"B12\",\n        \"common_name\": \"swir22\",\n        \"center_wavelength\": 2.2024,\n        \"gsd\": 20\n      }\n    ]\n  }\n}"
  },
  {
    "path": "stac-spec/examples/collection-only/collection.json",
    "content": "{\n  \"type\": \"Collection\",\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/projection/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/view/v1.0.0/schema.json\"\n  ],\n  \"id\": \"sentinel-2\",\n  \"title\": \"Sentinel-2 MSI: MultiSpectral Instrument, Level-1C\",\n  \"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\",\n  \"license\": \"proprietary\",\n  \"keywords\": [\n    \"copernicus\",\n    \"esa\",\n    \"eu\",\n    \"msi\",\n    \"radiance\",\n    \"sentinel\"\n  ],\n  \"providers\": [\n    {\n      \"name\": \"European Union/ESA/Copernicus\",\n      \"roles\": [\n        \"producer\",\n        \"licensor\"\n      ],\n      \"url\": \"https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi\"\n    }\n  ],\n  \"extent\": {\n    \"spatial\": {\n      \"bbox\": [\n        [\n          -180,\n          -56,\n          180,\n          83\n        ]\n      ]\n    },\n    \"temporal\": {\n      \"interval\": [\n        [\n          \"2015-06-23T00:00:00Z\",\n          null\n        ]\n      ]\n    }\n  },\n  \"assets\": {\n    \"metadata_iso_19139\": {\n      \"roles\": [\n        \"metadata\",\n        \"iso-19139\"\n      ],\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/sentinel-2-iso-19139.xml\",\n      \"title\": \"ISO 19139 metadata\",\n      \"type\": \"application/vnd.iso.19139+xml\"\n    }\n  },\n  \"summaries\": {\n    \"datetime\": {\n      \"minimum\": \"2015-06-23T00:00:00Z\",\n      \"maximum\": \"2019-07-10T13:44:56Z\"\n    },\n    \"platform\": [\n      \"sentinel-2a\",\n      \"sentinel-2b\"\n    ],\n    \"constellation\": [\n      \"sentinel-2\"\n    ],\n    \"instruments\": [\n      \"msi\"\n    ],\n    \"view:off_nadir\": {\n      \"minimum\": 0,\n      \"maximum\": 100\n    },\n    \"view:sun_elevation\": {\n      \"minimum\": 6.78,\n      \"maximum\": 89.9\n    },\n    \"gsd\": [\n      10,\n      30,\n      60\n    ],\n    \"proj:epsg\": [\n      32601,\n      32602,\n      32603,\n      32604,\n      32605,\n      32606,\n      32607,\n      32608,\n      32609,\n      32610,\n      32611,\n      32612,\n      32613,\n      32614,\n      32615,\n      32616,\n      32617,\n      32618,\n      32619,\n      32620,\n      32621,\n      32622,\n      32623,\n      32624,\n      32625,\n      32626,\n      32627,\n      32628,\n      32629,\n      32630,\n      32631,\n      32632,\n      32633,\n      32634,\n      32635,\n      32636,\n      32637,\n      32638,\n      32639,\n      32640,\n      32641,\n      32642,\n      32643,\n      32644,\n      32645,\n      32646,\n      32647,\n      32648,\n      32649,\n      32650,\n      32651,\n      32652,\n      32653,\n      32654,\n      32655,\n      32656,\n      32657,\n      32658,\n      32659,\n      32660\n    ],\n    \"eo:bands\": [\n      {\n        \"name\": \"B1\",\n        \"common_name\": \"coastal\",\n        \"center_wavelength\": 4.439\n      },\n      {\n        \"name\": \"B2\",\n        \"common_name\": \"blue\",\n        \"center_wavelength\": 4.966\n      },\n      {\n        \"name\": \"B3\",\n        \"common_name\": \"green\",\n        \"center_wavelength\": 5.6\n      },\n      {\n        \"name\": \"B4\",\n        \"common_name\": \"red\",\n        \"center_wavelength\": 6.645\n      },\n      {\n        \"name\": \"B5\",\n        \"center_wavelength\": 7.039\n      },\n      {\n        \"name\": \"B6\",\n        \"center_wavelength\": 7.402\n      },\n      {\n        \"name\": \"B7\",\n        \"center_wavelength\": 7.825\n      },\n      {\n        \"name\": \"B8\",\n        \"common_name\": \"nir\",\n        \"center_wavelength\": 8.351\n      },\n      {\n        \"name\": \"B8A\",\n        \"center_wavelength\": 8.648\n      },\n      {\n        \"name\": \"B9\",\n        \"center_wavelength\": 9.45\n      },\n      {\n        \"name\": \"B10\",\n        \"center_wavelength\": 1.3735\n      },\n      {\n        \"name\": \"B11\",\n        \"common_name\": \"swir16\",\n        \"center_wavelength\": 1.6137\n      },\n      {\n        \"name\": \"B12\",\n        \"common_name\": \"swir22\",\n        \"center_wavelength\": 2.2024\n      }\n    ]\n  },\n  \"links\": [\n    {\n      \"rel\": \"parent\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"license\",\n      \"href\": \"https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf\",\n      \"title\": \"Legal notice on the use of Copernicus Sentinel Data and Service Information\"\n    }\n  ]\n}\n"
  },
  {
    "path": "stac-spec/examples/collection.json",
    "content": "{\n  \"id\": \"simple-collection\",\n  \"type\": \"Collection\",\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/projection/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/view/v1.0.0/schema.json\"\n  ],\n  \"stac_version\": \"1.0.0\",\n  \"description\": \"A simple collection demonstrating core catalog fields with links to a couple of items\",\n  \"title\": \"Simple Example Collection\",\n  \"providers\": [\n    {\n      \"name\": \"Remote Data, Inc\",\n      \"description\": \"Producers of awesome spatiotemporal assets\",\n      \"roles\": [\n        \"producer\",\n        \"processor\"\n      ],\n      \"url\": \"http://remotedata.io\"\n    }\n  ],\n  \"extent\": {\n    \"spatial\": {\n      \"bbox\": [\n        [\n          172.91173669923782,\n          1.3438851951615003,\n          172.95469614953714,\n          1.3690476620161975\n        ]\n      ]\n    },\n    \"temporal\": {\n      \"interval\": [\n        [\n          \"2020-12-11T22:38:32.125Z\",\n          \"2020-12-14T18:02:31.437Z\"\n        ]\n      ]\n    }\n  },\n  \"license\": \"CC-BY-4.0\",\n  \"summaries\": {\n    \"platform\": [\n      \"cool_sat1\",\n      \"cool_sat2\"\n    ],\n    \"constellation\": [\n      \"ion\"\n    ],\n    \"instruments\": [\n      \"cool_sensor_v1\",\n      \"cool_sensor_v2\"\n    ],\n    \"gsd\": {\n      \"minimum\": 0.512,\n      \"maximum\": 0.66\n    },\n    \"eo:cloud_cover\": {\n      \"minimum\": 1.2,\n      \"maximum\": 1.2\n    },\n    \"proj:epsg\": {\n      \"minimum\": 32659,\n      \"maximum\": 32659\n    },\n    \"view:sun_elevation\": {\n      \"minimum\": 54.9,\n      \"maximum\": 54.9\n    },\n    \"view:off_nadir\": {\n      \"minimum\": 3.8,\n      \"maximum\": 3.8\n    },\n    \"view:sun_azimuth\": {\n      \"minimum\": 135.7,\n      \"maximum\": 135.7\n    }\n  },\n  \"links\": [\n    {\n      \"rel\": \"root\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"item\",\n      \"href\": \"./simple-item.json\",\n      \"type\": \"application/geo+json\",\n      \"title\": \"Simple Item\"\n    },\n    {\n      \"rel\": \"item\",\n      \"href\": \"./core-item.json\",\n      \"type\": \"application/geo+json\",\n      \"title\": \"Core Item\"\n    },\n    {\n      \"rel\": \"item\",\n      \"href\": \"./extended-item.json\",\n      \"type\": \"application/geo+json\",\n      \"title\": \"Extended Item\"\n    },\n    {\n      \"rel\": \"self\",\n      \"href\": \"https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/collection.json\",\n      \"type\": \"application/json\"\n    }\n  ]\n}\n"
  },
  {
    "path": "stac-spec/examples/collectionless-item.json",
    "content": "{\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/view/v1.0.0/schema.json\"\n  ],\n  \"type\": \"Feature\",\n  \"id\": \"CS3-20160503_132131_08\",\n  \"bbox\": [\n    -122.59750209,\n    37.48803556,\n    -122.2880486,\n    37.613537207\n  ],\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [\n          -122.308150179,\n          37.488035566\n        ],\n        [\n          -122.597502109,\n          37.538869539\n        ],\n        [\n          -122.576687533,\n          37.613537207\n        ],\n        [\n          -122.2880486,\n          37.562818007\n        ],\n        [\n          -122.308150179,\n          37.488035566\n        ]\n      ]\n    ]\n  },\n  \"properties\": {\n    \"title\": \"Full Item\",\n    \"description\": \"A sample STAC Item demonstrates an Item that does not have a collection, which is not recommended, but allowed by the spec.\",\n    \"datetime\": null,\n    \"start_datetime\": \"2016-05-03T13:22:30Z\",\n    \"end_datetime\": \"2016-05-03T13:27:30Z\",\n    \"created\": \"2016-05-04T00:00:01Z\",\n    \"updated\": \"2017-01-01T00:30:55Z\",\n    \"license\": \"various\",\n    \"providers\": [\n      {\n        \"name\": \"Remote Data, Inc\",\n        \"description\": \"Producers of awesome spatiotemporal assets\",\n        \"roles\": [\n          \"producer\",\n          \"processor\"\n        ],\n        \"url\": \"http://remotedata.it\"\n      }\n    ],\n    \"platform\": \"cool_sat2\",\n    \"instruments\": [\n      \"cool_sensor_v1\"\n    ],\n    \"view:sun_elevation\": 33.4,\n    \"gsd\": 0.512,\n    \"cs:type\": \"scene\",\n    \"cs:anomalous_pixels\": 0.14,\n    \"cs:earth_sun_distance\": 1.014156,\n    \"cs:sat_id\": \"CS3\",\n    \"cs:product_level\": \"LV1B\"\n  },\n  \"links\": [\n    {\n      \"rel\": \"root\",\n      \"href\": \"./catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"href\": \"./catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"alternate\",\n      \"type\": \"text/html\",\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html\",\n      \"title\": \"HTML representation of this STAC Item\"\n    },\n    {\n      \"rel\": \"license\",\n      \"type\": \"text/html\",\n      \"href\": \"http://remotedata.io/license.html\",\n      \"title\": \"Data License for Remote Data, Inc.\"\n    }\n  ],\n  \"assets\": {\n    \"analytic\": {\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/analytic.tif\",\n      \"title\": \"4-Band Analytic\",\n      \"eo:bands\": [\n        {\n          \"name\": \"band1\"\n        },\n        {\n          \"name\": \"band1\"\n        },\n        {\n          \"name\": \"band2\"\n        },\n        {\n          \"name\": \"band3\"\n        }\n      ]\n    },\n    \"thumbnail\": {\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png\",\n      \"title\": \"Thumbnail\",\n      \"type\": \"image/png\",\n      \"roles\": [\n        \"thumbnail\"\n      ]\n    },\n    \"udm\": {\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/UDM.tif\",\n      \"title\": \"Unusable Data Mask\"\n    },\n    \"json-metadata\": {\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/extended-metadata.json\",\n      \"title\": \"Extended Metadata\",\n      \"type\": \"application/json\",\n      \"roles\": [\n        \"metadata\"\n      ]\n    },\n    \"ephemeris\": {\n      \"href\": \"http://cool-sat.com/catalog/CS3-20160503_132130_04/S3-20160503_132130_04.EPH\",\n      \"title\": \"Satellite Ephemeris Metadata\"\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/examples/core-item.json",
    "content": "{\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [],\n  \"type\": \"Feature\",\n  \"id\": \"20201211_223832_CS2\",\n  \"bbox\": [\n    172.91173669923782,\n    1.3438851951615003,\n    172.95469614953714,\n    1.3690476620161975\n  ],\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ]\n      ]\n    ]\n  },\n  \"properties\": {\n    \"title\": \"Core Item\",\n    \"description\": \"A sample STAC Item that includes examples of all common metadata\",\n    \"datetime\": null,\n    \"start_datetime\": \"2020-12-11T22:38:32.125Z\",\n    \"end_datetime\": \"2020-12-11T22:38:32.327Z\",\n    \"created\": \"2020-12-12T01:48:13.725Z\",\n    \"updated\": \"2020-12-12T01:48:13.725Z\",\n    \"platform\": \"cool_sat1\",\n    \"instruments\": [\n      \"cool_sensor_v1\"\n    ],\n    \"constellation\": \"ion\",\n    \"mission\": \"collection 5624\",\n    \"gsd\": 0.512\n  },\n  \"collection\": \"simple-collection\",\n  \"links\": [\n    {\n      \"rel\": \"collection\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"alternate\",\n      \"type\": \"text/html\",\n      \"href\": \"http://remotedata.io/catalog/20201211_223832_CS2/index.html\",\n      \"title\": \"HTML version of this STAC Item\"\n    }\n  ],\n  \"assets\": {\n    \"analytic\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif\",\n      \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n      \"title\": \"4-Band Analytic\",\n      \"roles\": [\n        \"data\"\n      ]\n    },\n    \"thumbnail\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg\",\n      \"title\": \"Thumbnail\",\n      \"type\": \"image/png\",\n      \"roles\": [\n        \"thumbnail\"\n      ]\n    },\n    \"visual\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif\",\n      \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n      \"title\": \"3-Band Visual\",\n      \"roles\": [\n        \"visual\"\n      ]\n    },\n    \"udm\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif\",\n      \"title\": \"Unusable Data Mask\",\n      \"type\": \"image/tiff; application=geotiff;\"\n    },\n    \"json-metadata\": {\n      \"href\": \"http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json\",\n      \"title\": \"Extended Metadata\",\n      \"type\": \"application/json\",\n      \"roles\": [\n        \"metadata\"\n      ]\n    },\n    \"ephemeris\": {\n      \"href\": \"http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH\",\n      \"title\": \"Satellite Ephemeris Metadata\"\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/examples/extended-item.json",
    "content": "{\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/projection/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/scientific/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/view/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/remote-data/v1.0.0/schema.json\"\n  ],\n  \"type\": \"Feature\",\n  \"id\": \"20201211_223832_CS2\",\n  \"bbox\": [\n    172.91173669923782,\n    1.3438851951615003,\n    172.95469614953714,\n    1.3690476620161975\n  ],\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ]\n      ]\n    ]\n  },\n  \"properties\": {\n    \"title\": \"Extended Item\",\n    \"description\": \"A sample STAC Item that includes a variety of examples from the stable extensions\",\n    \"datetime\": \"2020-12-14T18:02:31.437000Z\",\n    \"created\": \"2020-12-15T01:48:13.725Z\",\n    \"updated\": \"2020-12-15T01:48:13.725Z\",\n    \"platform\": \"cool_sat2\",\n    \"instruments\": [\n      \"cool_sensor_v2\"\n    ],\n    \"gsd\": 0.66,\n    \"eo:cloud_cover\": 1.2,\n    \"proj:epsg\": 32659,\n    \"proj:shape\": [\n      5558,\n      9559\n    ],\n    \"proj:transform\": [\n      0.5,\n      0,\n      712710,\n      0,\n      -0.5,\n      151406,\n      0,\n      0,\n      1\n    ],\n    \"view:sun_elevation\": 54.9,\n    \"view:off_nadir\": 3.8,\n    \"view:sun_azimuth\": 135.7,\n    \"rd:type\": \"scene\",\n    \"rd:anomalous_pixels\": 0.14,\n    \"rd:earth_sun_distance\": 1.014156,\n    \"rd:sat_id\": \"cool_sat2\",\n    \"rd:product_level\": \"LV3A\",\n    \"sci:doi\": \"10.5061/dryad.s2v81.2/27.2\"\n  },\n  \"collection\": \"simple-collection\",\n  \"links\": [\n    {\n      \"rel\": \"collection\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"alternate\",\n      \"type\": \"text/html\",\n      \"href\": \"http://remotedata.io/catalog/20201211_223832_CS2/index.html\",\n      \"title\": \"HTML version of this STAC Item\"\n    }\n  ],\n  \"assets\": {\n    \"analytic\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif\",\n      \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n      \"title\": \"4-Band Analytic\",\n      \"roles\": [\n        \"data\"\n      ],\n      \"eo:bands\": [\n        {\n          \"name\": \"band1\",\n          \"common_name\": \"blue\",\n          \"center_wavelength\": 470,\n          \"full_width_half_max\": 70\n        },\n        {\n          \"name\": \"band2\",\n          \"common_name\": \"green\",\n          \"center_wavelength\": 560,\n          \"full_width_half_max\": 80\n        },\n        {\n          \"name\": \"band3\",\n          \"common_name\": \"red\",\n          \"center_wavelength\": 645,\n          \"full_width_half_max\": 90\n        },\n        {\n          \"name\": \"band4\",\n          \"common_name\": \"nir\",\n          \"center_wavelength\": 800,\n          \"full_width_half_max\": 152\n        }\n      ]\n    },\n    \"thumbnail\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg\",\n      \"title\": \"Thumbnail\",\n      \"type\": \"image/png\",\n      \"roles\": [\n        \"thumbnail\"\n      ]\n    },\n    \"visual\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif\",\n      \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n      \"title\": \"3-Band Visual\",\n      \"roles\": [\n        \"visual\"\n      ],\n      \"eo:bands\": [\n        {\n          \"name\": \"band3\",\n          \"common_name\": \"red\",\n          \"center_wavelength\": 645,\n          \"full_width_half_max\": 90\n        },\n        {\n          \"name\": \"band2\",\n          \"common_name\": \"green\",\n          \"center_wavelength\": 560,\n          \"full_width_half_max\": 80\n        },\n        {\n          \"name\": \"band1\",\n          \"common_name\": \"blue\",\n          \"center_wavelength\": 470,\n          \"full_width_half_max\": 70\n        }\n      ]\n    },\n    \"udm\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif\",\n      \"title\": \"Unusable Data Mask\",\n      \"type\": \"image/tiff; application=geotiff;\"\n    },\n    \"json-metadata\": {\n      \"href\": \"http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json\",\n      \"title\": \"Extended Metadata\",\n      \"type\": \"application/json\",\n      \"roles\": [\n        \"metadata\"\n      ]\n    },\n    \"ephemeris\": {\n      \"href\": \"http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH\",\n      \"title\": \"Satellite Ephemeris Metadata\"\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/examples/extensions-collection/collection.json",
    "content": "{\n  \"id\": \"extensions-collection\",\n  \"type\": \"Collection\",\n  \"stac_version\": \"1.0.0\",\n  \"description\": \"A heterogenous collection containing deeper examples of various extensions\",\n  \"links\": [\n    {\n      \"rel\": \"parent\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"item\",\n      \"href\": \"./proj-example/proj-example.json\",\n      \"title\": \"Proj extension example\"\n    },\n    {\n      \"rel\": \"license\",\n      \"href\": \"https://remotedata.io/license.html\",\n      \"title\": \"Remote Data License Terms\"\n    }\n  ],\n  \"stac_extensions\": [],\n  \"title\": \"Collection of Extension Items\",\n  \"keywords\": [\n    \"examples\",\n    \"sar\",\n    \"projection\"\n  ],\n  \"providers\": [\n    {\n      \"name\": \"Remote Data, Inc.\",\n      \"roles\": [\n        \"producer\",\n        \"licensor\"\n      ],\n      \"url\": \"https://remotedata.io\"\n    }\n  ],\n  \"extent\": {\n    \"spatial\": {\n      \"bbox\": [\n        [\n          -180,\n          -56,\n          180,\n          83\n        ]\n      ]\n    },\n    \"temporal\": {\n      \"interval\": [\n        [\n          \"2009-05-20T02:40:01.042784Z\",\n          \"2018-11-03T23:59:55.112875Z\"\n        ]\n      ]\n    }\n  },\n  \"license\": \"PDDL-1.0\"\n}\n"
  },
  {
    "path": "stac-spec/examples/extensions-collection/proj-example/proj-example.json",
    "content": "{\n  \"type\": \"Feature\",\n  \"stac_version\": \"1.0.0\",\n  \"id\": \"proj-example\",\n  \"properties\": {\n    \"datetime\": \"2018-10-01T01:08:32.033000Z\",\n    \"proj:epsg\": 32614,\n    \"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]]\",\n    \"proj:projjson\": {\n      \"$schema\": \"https://proj.org/schemas/v0.2/projjson.schema.json\",\n      \"type\": \"ProjectedCRS\",\n      \"name\": \"WGS 84 / UTM zone 14N\",\n      \"base_crs\": {\n        \"name\": \"WGS 84\",\n        \"datum\": {\n          \"type\": \"GeodeticReferenceFrame\",\n          \"name\": \"World Geodetic System 1984\",\n          \"ellipsoid\": {\n            \"name\": \"WGS 84\",\n            \"semi_major_axis\": 6378137,\n            \"inverse_flattening\": 298.257223563\n          }\n        },\n        \"coordinate_system\": {\n          \"subtype\": \"ellipsoidal\",\n          \"axis\": [\n            {\n              \"name\": \"Geodetic latitude\",\n              \"abbreviation\": \"Lat\",\n              \"direction\": \"north\",\n              \"unit\": \"degree\"\n            },\n            {\n              \"name\": \"Geodetic longitude\",\n              \"abbreviation\": \"Lon\",\n              \"direction\": \"east\",\n              \"unit\": \"degree\"\n            }\n          ]\n        },\n        \"id\": {\n          \"authority\": \"EPSG\",\n          \"code\": 4326\n        }\n      },\n      \"conversion\": {\n        \"name\": \"UTM zone 14N\",\n        \"method\": {\n          \"name\": \"Transverse Mercator\",\n          \"id\": {\n            \"authority\": \"EPSG\",\n            \"code\": 9807\n          }\n        },\n        \"parameters\": [\n          {\n            \"name\": \"Latitude of natural origin\",\n            \"value\": 0,\n            \"unit\": \"degree\",\n            \"id\": {\n              \"authority\": \"EPSG\",\n              \"code\": 8801\n            }\n          },\n          {\n            \"name\": \"Longitude of natural origin\",\n            \"value\": -99,\n            \"unit\": \"degree\",\n            \"id\": {\n              \"authority\": \"EPSG\",\n              \"code\": 8802\n            }\n          },\n          {\n            \"name\": \"Scale factor at natural origin\",\n            \"value\": 0.9996,\n            \"unit\": \"unity\",\n            \"id\": {\n              \"authority\": \"EPSG\",\n              \"code\": 8805\n            }\n          },\n          {\n            \"name\": \"False easting\",\n            \"value\": 500000,\n            \"unit\": \"metre\",\n            \"id\": {\n              \"authority\": \"EPSG\",\n              \"code\": 8806\n            }\n          },\n          {\n            \"name\": \"False northing\",\n            \"value\": 0,\n            \"unit\": \"metre\",\n            \"id\": {\n              \"authority\": \"EPSG\",\n              \"code\": 8807\n            }\n          }\n        ]\n      },\n      \"coordinate_system\": {\n        \"subtype\": \"Cartesian\",\n        \"axis\": [\n          {\n            \"name\": \"Easting\",\n            \"abbreviation\": \"E\",\n            \"direction\": \"east\",\n            \"unit\": \"metre\"\n          },\n          {\n            \"name\": \"Northing\",\n            \"abbreviation\": \"N\",\n            \"direction\": \"north\",\n            \"unit\": \"metre\"\n          }\n        ]\n      },\n      \"area\": \"World - N hemisphere - 102°W to 96°W - by country\",\n      \"bbox\": {\n        \"south_latitude\": 0,\n        \"west_longitude\": -102,\n        \"north_latitude\": 84,\n        \"east_longitude\": -96\n      },\n      \"id\": {\n        \"authority\": \"EPSG\",\n        \"code\": 32614\n      }\n    },\n    \"proj:geometry\": {\n      \"coordinates\": [\n        [\n          [\n            169200,\n            3712800\n          ],\n          [\n            403200,\n            3712800\n          ],\n          [\n            403200,\n            3951000\n          ],\n          [\n            169200,\n            3951000\n          ],\n          [\n            169200,\n            3712800\n          ]\n        ]\n      ],\n      \"type\": \"Polygon\"\n    },\n    \"proj:bbox\": [\n      169200,\n      3712800,\n      403200,\n      3951000\n    ],\n    \"proj:centroid\": {\n      \"lat\": 34.595302781575604,\n      \"lon\": -101.34448382627504\n    },\n    \"proj:shape\": [\n      8391,\n      8311\n    ],\n    \"proj:transform\": [\n      30,\n      0,\n      224985,\n      0,\n      -30,\n      6790215,\n      0,\n      0,\n      1\n    ]\n  },\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [\n          152.52758,\n          60.63437\n        ],\n        [\n          149.1755,\n          61.19016\n        ],\n        [\n          148.13933,\n          59.51584\n        ],\n        [\n          151.33786,\n          58.97792\n        ],\n        [\n          152.52758,\n          60.63437\n        ]\n      ]\n    ]\n  },\n  \"links\": [\n    {\n      \"rel\": \"root\",\n      \"href\": \"../../catalog.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Example Catalog\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"href\": \"../collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection of Extension Items\"\n    },\n    {\n      \"rel\": \"collection\",\n      \"href\": \"../collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Collection of Extension Items\"\n    }\n  ],\n  \"assets\": {\n    \"B1\": {\n      \"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\",\n      \"type\": \"image/tiff; application=geotiff\",\n      \"title\": \"Band 1 (coastal)\",\n      \"eo:bands\": [\n        {\n          \"name\": \"B1\",\n          \"common_name\": \"coastal\",\n          \"center_wavelength\": 0.44,\n          \"full_width_half_max\": 0.02\n        }\n      ]\n    },\n    \"B8\": {\n      \"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\",\n      \"type\": \"image/tiff; application=geotiff\",\n      \"title\": \"Band 8 (panchromatic)\",\n      \"eo:bands\": [\n        {\n          \"name\": \"B8\",\n          \"center_wavelength\": 0.59,\n          \"full_width_half_max\": 0.18\n        }\n      ],\n      \"proj:shape\": [\n        16781,\n        16621\n      ],\n      \"proj:transform\": [\n        15,\n        0,\n        224992.5,\n        0,\n        -15,\n        6790207.5,\n        0,\n        0,\n        1\n      ]\n    }\n  },\n  \"bbox\": [\n    148.13933,\n    59.51584,\n    152.52758,\n    60.63437\n  ],\n  \"stac_extensions\": [\n    \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\",\n    \"https://stac-extensions.github.io/projection/v1.0.0/schema.json\"\n  ],\n  \"collection\": \"landsat-8-l1\"\n}\n"
  },
  {
    "path": "stac-spec/examples/simple-item.json",
    "content": "{\n  \"stac_version\": \"1.0.0\",\n  \"stac_extensions\": [],\n  \"type\": \"Feature\",\n  \"id\": \"20201211_223832_CS2\",\n  \"bbox\": [\n    172.91173669923782,\n    1.3438851951615003,\n    172.95469614953714,\n    1.3690476620161975\n  ],\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3438851951615003\n        ],\n        [\n          172.95469614953714,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3690476620161975\n        ],\n        [\n          172.91173669923782,\n          1.3438851951615003\n        ]\n      ]\n    ]\n  },\n  \"properties\": {\n    \"datetime\": \"2020-12-11T22:38:32.125000Z\"\n  },\n  \"collection\": \"simple-collection\",\n  \"links\": [\n    {\n      \"rel\": \"collection\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"root\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    },\n    {\n      \"rel\": \"parent\",\n      \"href\": \"./collection.json\",\n      \"type\": \"application/json\",\n      \"title\": \"Simple Example Collection\"\n    }\n  ],\n  \"assets\": {\n    \"visual\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif\",\n      \"type\": \"image/tiff; application=geotiff; profile=cloud-optimized\",\n      \"title\": \"3-Band Visual\",\n      \"roles\": [\n        \"visual\"\n      ]\n    },\n    \"thumbnail\": {\n      \"href\": \"https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg\",\n      \"title\": \"Thumbnail\",\n      \"type\": \"image/jpeg\",\n      \"roles\": [\n        \"thumbnail\"\n      ]\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/extensions/README.md",
    "content": "# Extensions\n\n- [Overview](#overview)\n- [Using Extensions](#using-extensions)\n  - [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions)\n- [Stable STAC Extensions](#stable-stac-extensions)\n- [Community Extensions](#community-extensions)\n  - [Proposed extensions](#proposed-extensions)\n- [Extending STAC](#extending-stac)\n  - [General Conventions](#general-conventions)\n  - [Proposing new extensions](#proposing-new-extensions)\n  - [Extension Maturity](#extension-maturity)\n  - [Prefixes](#prefixes)\n  - [Use of arrays and objects](#use-of-arrays-and-objects)\n\n## Overview\n\nOne of the most important aspects of the SpatioTemporal Asset Catalog specification is its extensibility. The core\nSTAC specification defines only a minimal core, but is designed for extension. It is expected that most real-world\nimplementations will use several 'extensions' to fully describe their data. This document describes how extensions\nwork, and links to the 'core' extensions included in this repo, as well as to a variety of 'community' extensions.\n\n**For the complete list of available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).**\n\nExtensions to the core STAC specification provide additional JSON fields that can be used to better describe\nthe data. Most tend to be about describing a particular domain or type of data, but some imply\nfunctionality.\n\nExtensions include a JSON Schema precisely describing the structure, a natural language description of the fields, and thorough examples.\n\nAnybody can create an extension for their data, and data providers often work together to share\nfields between them to create a shared community extensions. See the section below on '[Extending STAC](#extending-stac)')\nfor information on how to get started. And everyone is encouraged to link to the extension in the table below, so others\ncan be aware of it.\n\nEach extension has at least one *owner*. You can find extension owners in each extension's README.\n\n## Using Extensions\n\nWhen deciding how to model data in STAC it is highly recommended to first look at the [list of \nextensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This\nincreases interoperability, as users know that the meaning of your fields is the same as in other STAC \nimplementations. Many clients will also understand more mature extensions for better display and querying. \n\nTo incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions`\narray of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions), \n[Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions)\nobject. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators\ncan fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as \nidentifiers for specific version of the extension that the STAC object implements. The extension ID can be\nfound listed as the 'identifier' in the second line of the README of any extension made with the [extension \ntemplate](https://github.com/stac-extensions/template), and new ones get published automatically with any release made \nwith the template.\n\n### Extension IDs in `stac_extensions`\n\nThe logic for when an object should list an extension ID in its `stac_extension` array is as follows:\n\n- If the object directly implements the extension (by following the specified requirements - usually by including \nfields, but occasionally implementing alternate behaviors), the  `stac_extensions` of that object should contain the extension ID.\n- If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that\n  Asset should contain the extension ID.\n- If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then\n  the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field\n  contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array.\n- If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension\n  ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the\n  [item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition\n  which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`.\n\n## Stable STAC Extensions\n\nThese extensions are considered stable and are widely used in many production implementations. As additional extensions advance\nthrough the [Extension Maturity](#extension-maturity) classification they, will be added here.\n\n| Extension Title                                                       |     Description                |\n|-----------------------------------------------------------------------|--------------------------------|\n| [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. |\n| [Projection](https://github.com/stac-extensions/projection/)          | Provides a way to describe Items whose assets are in a geospatial projection. |\n| [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.  |\n| [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 |\n\n## Community Extensions\n\nThere are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the\n[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. For \nan overview of all extensions with their [Extension Maturity](#extension-maturity) classification see the \n[STAC extensions overview page](https://stac-extensions.github.io/).\n\n### Proposed extensions\n\nBeyond the community extensions there have been a number of extensions that people have proposed to the STAC community. These\ncan be found in the STAC [Issue Tracker](https://github.com/radiantearth/stac-spec/issues) under the \n[new extension](https://github.com/radiantearth/stac-spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+extension%22) label.\nThese are ideas that others would likely use and potentially collaborate on. Anyone is free to add new\nideas there, and see the section below on [proposing new extensions](#proposing-new-extensions) for the\nworkflow to advance ideas into full-fledged community extensions.\n\n## Extending STAC\n\nAnyone is welcome to create an extension. There are several types of extensions, some just add additional fields,\nsome change the behavior of STAC and some introduce completely new functionality. New extensions should try to align\nwith existing extensions as well as possible and may even re-use fields and their definitions until they may get split\ninto a new extension that combines commonly used fields across multiple extensions.\nBest practices for extension proposals are still emerging in this section.\n\n### General Conventions\n\nCreating a new extension usually involves defining a set of logically grouped fields, and specifying what the allowed values\nfor those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one \ncan theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects.\n\n1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object,\n   rather than directly in the Item object.\n2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa.\n   For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in\n   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.\n3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or\n   [Collection](../collection-spec/collection-spec.md) should be added to the root of the object.\n4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema.\n\n### Proposing new extensions\n\nExtensions can be hosted anywhere, but should use the\n[extension template](https://github.com/stac-extensions/stac-extensions.github.io#using-the-stac-extensions-template) \nas a starting point. If you'd like to add a repository to the [stac-extensions](https://github.com/stac-extensions) \nGitHub organization, just ask on [Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby)! This is fine for \nwork-in-progress extensions. You can also host the extension repository in your own GitHub account, and optionally \ntransfer it to the stac-extensions org later.\n\nFor new extensions that require community discussion, we recommend the following workflow:\n\n- Use the stac-extensions template to sketch out your proposed extension\n- Open an issue on this repository with the prefix \"New Extension: \" and describe the extension. Include a link to the extension repository.\n- Discussion can occur on that issue, or discussion can move to issues/pull requests on the extension repository directly.\n- Once the extension has an initial release, the issue on stac-spec will be closed.\n\n### Extension Maturity\n\nThere are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions\nlisted here included must include a maturity classification, so that STAC spec users can easily get a sense of how\nmuch they can count on the extension. Extension creators are encouraged to list their extensions here, even if it is just\nan rough proposal, so others can potentially collaborate.\n\n| Maturity Classification |  Min Impl # | Description | Stability |\n| ----------------------- | ----------- | ----------- | --------- |\n| 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. |\n| 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 |\n| 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. |\n| 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. |\n| 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 |\n\nMaturity mostly comes through diverse implementations, so the minimum number of implementations\ncolumn is the main gating function for an extension to mature. But extension authors can also\nchoose to hold back the maturity advancement if they don't feel they are yet ready to commit to\nthe less breaking changes of the next level.\n\nA 'mature' classification level will likely be added once there are extensions that have been\nstable for over a year and are used in twenty or more implementations.\n\n### Prefixes\n\nA STAC Item can combine schema information from several different sources - the core STAC Item information,\nan earth observation community extension, and a vendor specific provider. It can be difficult to distinguish exactly where each definition\ncame from, and to pull out the most relevant information, especially when vendors often will dump in all the metadata they have in to the\nSTAC definition.\n\nSo one idea is to have prefixes to differentiate specific vendors (like `dg:` for DigitalGlobe), and for communities of practice\n(like `eo:` for Electro-Optical). These wouldn't be full namespacing, though an extension for like JSON-LD could potentially\nevolve to make fully resolved namespacing an option.\n\nAn example of this can be seen in a Landsat example:\n\n```js\n  \"properties\": {\n    \"datetime\":\"2018-01-01T13:21:30Z\",\n\n    \"start_datetime\":\"2018-01-01T13:21:30Z\",\n    \"end_datetime\":\"2018-01-01T13:31:30Z\",\n\n    \"view:off_nadir\": -0.001,\n    \"eo:cloud_cover\": 10.31,\n    \"view:sun_azimuth\": 149.01607154,\n    \"view:sun_elevation\": 59.21424700,\n    \"gsd\": 30,\n\n    \"l8:data_type\": \"L1T\",\n    \"l8:wrs_path\": 153,\n    \"l8:wrs_row\": 25,\n    \"l8:earth_sun_distance\": 1.0141560,\n    \"l8:ground_control_points_verify\": 114,\n    \"l8:geometric_rmse_model\": 7.562,\n    \"l8:image_quality_tirs\": 9,\n    \"l8:ground_control_points_model\": 313,\n    \"l8:geometric_rmse_model_x\": 5.96,\n    \"l8:geometric_rmse_model_y\": 4.654,\n    \"l8:geometric_rmse_verify\": 5.364,\n    \"l8:image_quality_oli\": 9\n  }\n```\n\n### Use of arrays and objects\n\nFor extensions, it is recommended to\n\n1. Use arrays only as enumerations/lists (possibly sorted), without implying additional meaning (such as order)\n2. To avoid using nested objects, in favor of multiple attributes with a similar naming scheme.\n\nFor example, if one would like to define an extension to contain a start and a end date,\nthere are multiple options (tl;dr: option **3** is recommended):\n\n1. Define an object, for example: `\"date_range\": {\"start\": \"2018-01-01\", \"end\": \"2018-01-31\"}`.\n   This is **discouraged** as it is more complex to search in objects.\n2. Define an two-element array where the first element is the start date and the second element is the end date,\n   for example `\"date_range\": [\"2018-01-01\", \"2018-01-31\"]`.\n   This is **discouraged** as it would conflict with Collection `summaries`,\n   which always considers arrays as true (potentially sorted) enumeration without any additional meaning.\n3. Define two separate fields, e.g. `\"date_range_start\": \"2018-01-01\", \"date_range_end\": \"2018-01-31\"`.\n   This is **recommended** as it avoids the conflicts above and is usually better displayed in software that only understands GeoJSON\n   but has no clue about STAC.\n   This is due to the fact that most legacy software can not display arrays or objects GeoJSON `properties` properly.\n\nThis rules only applies to the fields defined directly for the Item's `properties`.\nFor 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.\nSo 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.\n"
  },
  {
    "path": "stac-spec/item-spec/README.md",
    "content": "# STAC Item Specification\n\nThe [STAC Item](item-spec.md) object is the most important object in a STAC system. An\n**Item** is the entity that contains metadata for a scene and links to the assets. \n\nItem objects are the leaf nodes for a graph of [Catalog](../catalog-spec/catalog-spec.md) \nand [Collection](../collection-spec/collection-spec.md) objects. See the \n[overview](../overview.md) document for more information about how these objects relate \nto each other.\n\n## In this directory\n\n**Specification:** The STAC Item specification is in \n*[item-spec.md](item-spec.md)*. It includes an overview and an in-depth explanation of the fields.\n\n**Schemas:** The OpenAPI specification in *[item.json](json-schema/item.json)* \ndefines an **Item** object. The [basics](json-schema/basics.json), \n[datetime](json-schema/datetime.json), [instrument](json-schema/instrument.json), \n[licensing](json-schema/licensing.json), and [provider](json-schema/provider.json)\nschemas validate additional fields defined in *[Common Metadata](common-metadata.md)*.\n\n**Common Metadata:** A set of commonly-used fields for STAC Items is listed in \n*[common-metadata.md](common-metadata.md)*.\n"
  },
  {
    "path": "stac-spec/item-spec/common-metadata.md",
    "content": "# STAC Common Metadata\n\nThis document outlines commonly used fields in STAC.\nThey are often used in [STAC Item properties](item-spec.md#properties-object),\nbut can also be used in other places, e.g. an [Item Asset](item-spec.md#asset-object)\nor [Collection Asset](../collection-spec/collection-spec.md#asset-object).\n\n- [STAC Common Metadata](#stac-common-metadata)\n  - [Basics](#basics)\n  - [Date and Time](#date-and-time)\n    - [Date and Time Range](#date-and-time-range)\n  - [Licensing](#licensing)\n    - [Relation types](#relation-types)\n  - [Provider](#provider)\n    - [Provider Object](#provider-object)\n  - [Instrument](#instrument)\n\nVarious *examples* are available in the folder [`examples`](../examples/).\n*JSON Schemas* can be found in the folder [`json-schema`](json-schema/).\n\nBy default, these fields are only included and validated against in the core [Item schema](json-schema/item.json).\n\nImplementation of any of the fields is not required, unless explicitly required by a specification using the field.\nFor example, `datetime` is required in STAC Items.\n\n## Basics\n\nDescriptive fields to give a basic overview of a STAC Item.\n\n- [JSON Schema](json-schema/basics.json)\n\n| Field Name  | Type   | Description                                                  |\n| ----------- | ------ | ------------------------------------------------------------ |\n| title       | string | A human readable title describing the Item. |\n| 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. |\n\n## Date and Time\n\n- [JSON Schema](json-schema/datetime.json)\n\nFields to provide additional temporal information such as ranges with a start and an end datetime stamp.\n\n| Field Name | Type         | Description |\n| ---------- | ------------ | ----------- |\n| datetime   | string\\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. |\n| created    | string       | Creation date and time of the corresponding data (see below), in UTC. |\n| updated    | string       | Date and time the corresponding data (see below) was updated last, in UTC. |\n\nAll timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\n**created** and **updated** have different meaning depending on where they are used.\nIf those fields are available in the Item `properties`, they identify the creation and update times of the metadata.\nHaving those fields in the Item `assets` refers to the creation and update times of the actual data linked to in the Asset Object.\n\n*NOTE: There are more date and time related fields available in the [Timestamps \nextension](https://github.com/stac-extensions/timestamps), which is not an official extension*.\n\n### Date and Time Range\n\nWhile a STAC Item can have a nominal datetime describing the capture, these properties allow an Item to have a range\nof capture dates and times. An example of this is the [MODIS 16 day vegetation index product](https://lpdaac.usgs.gov/products/mod13q1v006/).\n\n**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.\nSo if you use `start_datetime` you need to add `end_datetime` and vice-versa.\nBoth fields are also REQUIRED if the `datetime` field is set to `null`.\nThe datetime property in a STAC Item and these fields are not mutually exclusive.\n\n| Field Name     | Type   | Description                                                  |\n| -------------- | ------ | ------------------------------------------------------------ |\n| 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). |\n| 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). |\n\n## Licensing\n\nInformation about the license(s) of the data, which is not necessarily the same license that applies to the metadata.\n**Licensing information should be defined at the [Collection](../collection-spec/collection-spec.md) level if possible.**\n\n- [JSON Schema](json-schema/licensing.json)\n\n| Field Name | Type   | Description |\n| ---------- | ------ | ----------- |\n| 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. |\n\n**license**: Data license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use\n`proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply.\nIn all cases links to the license texts SHOULD be added, see the [`license` link relation type](#relation-types).\nIf no link to a license is included and the `license` field is set to `proprietary`, the Collection is private,\nand consumers have not been granted any explicit right to use the data.\n\n### Relation types\n\n| Type         | Description                                                  |\n| ------------ | ------------------------------------------------------------ |\n| 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. |\n\n## Provider\n\nInformation about the organizations capturing, producing, processing, hosting or publishing this data.\n**Provider information should be defined at the Collection level if possible.**\n\n- [JSON Schema](json-schema/provider.json)\n\n| Field Name | Type   | Description |\n| ---------- | ------ | ----------- |\n| 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.  |\n\n### Provider Object\n\nThe object provides information about a provider.\nA provider is any of the organizations that captures or processes the content of the assets and\ntherefore influences the data offered by the STAC implementation.\nMay also include information about the final storage provider hosting the data.\n\n| Field Name  | Type      | Description                                                  |\n| ----------- | --------- | ------------------------------------------------------------ |\n| name        | string    | **REQUIRED.** The name of the organization or the individual. |\n| 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. |\n| roles       | \\[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. |\n| url         | string    | Homepage on which the provider describes the dataset and publishes contact information. |\n\n#### roles\n\nThe provider's role(s) can be one or more of the following elements:\n\n- *licensor*: The organization that is licensing the dataset under the license specified in the Collection's `license` field.\n- *producer*: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data.\n- *processor*: A processor is any provider who processed data to a derived product.\n- *host*: The host is the actual provider offering the data on their storage.\n  There should be no more than one host, specified as the last element of the provider list.\n\n## Instrument\n\nAdds metadata specifying a platform and instrument used in a data collection mission. These fields will often be combined\nwith domain-specific extensions that describe the actual data, such as the `eo` or `sar` extensions.\n\n- [JSON Schema](json-schema/instrument.json)\n\n| Field Name    | Type      | Description |\n| ------------- | --------- | ----------- |\n| platform      | string    | Unique name of the specific platform to which the instrument is attached. |\n| instruments   | \\[string] | Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). |\n| constellation | string    | Name of the constellation to which the platform belongs. |\n| mission       | string    | Name of the mission for which data is collected. |\n| gsd           | number    | Ground Sample Distance at the sensor, in meters (m), must be greater than 0. |\n\n### Additional Field Information\n\n#### platform\n\nThe unique name of the specific platform the instrument is attached to. For satellites this would\nbe the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include\n`landsat-8` (Landsat-8), `sentinel-2a` and `sentinel-2b` (Sentinel-2), `terra` and `aqua` (part of NASA EOS,\ncarrying the MODIS instruments), `mycorp-uav-034` (hypothetical drone name), and `worldview02`\n(Maxar/DigitalGlobe WorldView-2).\n\n#### instruments\n\nAn array of all the sensors used in the creation of the data. For example, data from the Landsat-8\nplatform is collected with the OLI sensor as well as the TIRS sensor, but the data is distributed together so would be\nspecified as `['oli', 'tirs']`. Other instrument examples include `msi` (Sentinel-2), `aster` (Terra), and `modis`\n(Terra and Aqua), `c-sar` (Sentinel-1) and `asar` (Envisat).\n\n#### constellation\n\nThe name of a logical collection of one or more platforms that have similar payloads and have\ntheir orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and\nradiometric characteristics. This field allows users to search for related data sets without the need to specify which\nspecific platform the data came from, for example, from either of the Sentinel-2 satellites. Examples include `landsat-8`\n(Landsat-8, a constellation consisting of a single platform), `sentinel-2`\n([Sentinel-2](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation)),\n`rapideye` (operated by Planet Labs), and `modis` (NASA EOS satellites Aqua and Terra).  In the case of `modis`, this\nis technically referring to a pair of sensors on two different satellites, whose data is combined into a series of\nrelated products. Additionally, the Aqua satellite is technically part of the A-Train constellation and Terra is not\npart of a constellation, but these are combined to form the logical collection referred to as MODIS.\n\n#### mission\n\nThe name of the mission or campaign for collecting data. This could be a discrete set of data collections\nover a period of time (such as collecting drone imagery), or could be a set of tasks of related tasks from a satellite\ndata collection.\n\n#### gsd\n\nThe nominal Ground Sample Distance for the data, as measured in meters on the ground. There are many\ndefinitions of GSD. The value of this field should be related to the spatial resolution at the sensor, rather\nthan the pixel size of images after orthorectification, pansharpening, or scaling.\nThe GSD of a sensor can vary depending on geometry (off-nadir / grazing angle) and wavelength, so it is at the\ndiscretion of the implementer to decide which value most accurately represents the GSD. For example, Landsat8\noptical and short-wave IR bands are all 30 meters, but the panchromatic band is 15 meters. The\n`gsd` should be 30 meters in this case because that is the nominal spatial resolution at the sensor. The Planet\nPlanetScope Ortho Tile Product has an `gsd` of 3.7 (or 4 if rounding), even though the pixel size of the images is 3.125.\nFor example, one might choose for WorldView-2 the Multispectral 20° off-nadir value of 2.07\nand for WorldView-3 the Multispectral 20° off-nadir value of 1.38.\n"
  },
  {
    "path": "stac-spec/item-spec/item-spec.md",
    "content": "# STAC Item Specification <!-- omit in toc --> \n\n- [Overview](#overview)\n- [Item fields](#item-fields)\n  - [Additional Field Information](#additional-field-information)\n    - [stac_version](#stac_version)\n    - [stac_extensions](#stac_extensions)\n    - [id](#id)\n    - [assets](#assets)\n    - [bbox](#bbox)\n  - [Properties Object](#properties-object)\n    - [datetime](#datetime)\n    - [Additional Fields](#additional-fields)\n  - [Link Object](#link-object)\n    - [Relation types](#relation-types)\n      - [derived_from](#derived_from)\n    - [Collections](#collections)\n  - [Asset Object](#asset-object)\n    - [Asset Media Type](#asset-media-type)\n    - [Asset Roles](#asset-roles)\n      - [Asset Role Types](#asset-role-types)\n    - [Additional Fields for Assets](#additional-fields-for-assets)\n- [Media Type for STAC Item](#media-type-for-stac-item)\n- [Extensions](#extensions)\n\n## Overview\n\nThis document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) Item. An **Item** is a\n[GeoJSON](http://geojson.org/) [Feature](https://tools.ietf.org/html/rfc7946#section-3.2) augmented with\n[foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC object.\nThese include fields that identify the time range and assets of the Item. An Item is the core\nobject in a STAC Catalog, containing the core metadata that enables any client to search or crawl\nonline catalogs of spatial 'assets' (e.g., satellite imagery, derived data, DEMs).\n\nThe same Item definition is used in both [STAC Catalogs](../catalog-spec/README.md) and\nthe [Item-related API endpoints](https://github.com/radiantearth/stac-api-spec/blob/master/api-spec.md#ogc-api---features-endpoints).\nCatalogs are simply sets of Items that are linked online, generally served by simple web servers\nand used for crawling data. The search endpoint enables dynamic queries, for example selecting all\nItems in Hawaii on June 3, 2015, but the results they return are FeatureCollections of Items.\n\nItems are represented in JSON format and are very flexible. Any JSON object that contains all the\nrequired fields is a valid STAC Item.\n\n- Examples:\n  - See the [minimal example](../examples/simple-item.json),\n    as well as a [more fleshed example](../examples/core-item.json) that contains a number of current best practices.\n  - Real world [implementations](https://stacindex.org/catalogs) are also available.\n- [JSON Schema](json-schema/item.json)\n\n## Item fields\n\nThis object describes a STAC Item. The fields `id`, `type`, `bbox`, `geometry` and `properties` are\ninherited from GeoJSON.\n\n| Field Name | Type                                                                       | Description |\n| ---------- | -------------------------------------------------------------------------- | ----------- |\n| type       | string                                                                     | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. |\n| stac_version | string                                                                   | **REQUIRED.** The STAC version the Item implements. |\n| stac_extensions | \\[string]                                                             | A list of extensions the Item implements. |\n| id         | string                                                                     | **REQUIRED.** Provider identifier. The ID should be unique within the  [Collection](../collection-spec/collection-spec.md) that contains the Item. |\n| 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). |\n| 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). |\n| properties | [Properties Object](#properties-object)                                    | **REQUIRED.** A dictionary of additional metadata for the Item. |\n| 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. |\n| assets     | Map<string, [Asset Object](#asset-object)>                                 | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. |\n| 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. |\n\n### Additional Field Information\n\n#### stac_version\n\nIn general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind.\n\n#### stac_extensions\n\nA list of extensions the Item implements.\nThe list consists of URLs to JSON Schema files that can be used for validation.\nThis list must only contain extensions that extend the Item specification itself,\nsee the the 'Scope' for each of the extensions.\n\n#### id\n\nIt is important that an Item identifier is unique within a Collection, and that the \n[Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to\ngive a globally unique identifier. Items are *[strongly recommended](#collections)* to have Collections, and not having one makes\nit more difficult to be used in the wider STAC ecosystem.\nIf an Item does not have a Collection, then the Item identifier should be unique within its root Catalog or root Collection.\n\nAs most geospatial assets are already uniquely defined by some \nidentification scheme from the data provider it is recommended to simply use that ID.\nData providers are advised to include sufficient information to make their IDs globally unique,\nincluding things like unique satellite IDs.\nSee the [id section of best practices](../best-practices.md#item-ids) for additional recommendations.\n\n#### assets\n\nThis is a dictionary of [Asset Objects](#asset-object) data associated with the Item that can be\ndownloaded or streamed, each with a unique key.\nIn general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers.\nProviders may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them.\nTo communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object).\n\nAssets should include the main asset, as well as any 'sidecar' files that are related and help a\nclient make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.),\nunusable data masks, satellite ephemeris data, etc. Some assets (like Landsat data) are represented\nby multiple files - all should be linked to. It is generally recommended that different processing\nlevels or formats are not exhaustively listed in an Item, but instead are represented by related\nItems that are linked to, but the best practices around this are still emerging.\n\n#### bbox\n\nBounding Box of the asset represented by this Item using either 2D or 3D geometries,\nformatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5).\nThe length of the array must be 2\\*n where n is the number of dimensions.\nThe array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in\nLongitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84).\nWhen using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters\nand the elevation of the northeasterly most extent is the maximum.\nThis field enables more naive clients to easily index and search geospatially.\nSTAC compliant APIs are required to compute intersection operations with the Item's geometry field, not its bbox.\n\n### Properties Object\n\nAdditional metadata fields can be added to the GeoJSON Object Properties. The only required field\nis `datetime` but it is recommended to add more fields, see [Additional Fields](#additional-fields)\nresources below.\n\n| Field Name | Type         | Description                                                  |\n| ---------- | ------------ | ------------------------------------------------------------ |\n| 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. |\n\n#### datetime\n\nThis is likely the acquisition (in the case of single camera type captures) or the 'nominal'\nor representative time in the case of assets that are combined together. Though time can be a\ncomplex thing to capture, for this purpose keep in mind the STAC spec is primarily searching for\ndata, so use whatever single date and time is most useful for a user to search for. STAC content\nextensions may further specify the meaning of the main `datetime` field, and many will also add more\ndatetime fields. **All times in STAC metadata should be in [Coordinated Universal \nTime](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC).**\nIf there's clearly no meaningful single 'nominal' time, it is allowed to use `null` instead.\nIn this case it is **required** to specify a temporal interval with the fields `start_datetime`\nand `end_datetime` from [common metadata](common-metadata.md#date-and-time-range). For example, if\nyour data is a time-series that covers 100 years, it's not very meaningful to set the datetime to a\nsingle timestamp as it would not be found in most searches that searches for a decade of data in that\nperiod although the Item actually covers the decade. See [datetime selection](../best-practices.md#datetime-selection)\nin the best practices document for more information.\n\n#### Additional Fields\n\nProviders should include metadata fields that are relevant for users of STAC, but it is recommended\nto [select only those necessary for search](../best-practices.md#field-selection-and-metadata-linking).\nWhere possible metadata fields should be mapped to the STAC Common Metadata and widely used extensions,\nto enable cross-catalog search on known fields.\n\n- [STAC Common Metadata](common-metadata.md#stac-common-metadata) - A list of fields commonly used\nthroughout all domains. These optional fields are included for STAC Items by default.\n- [Extensions](../extensions/README.md) - Additional fields that are more specific,\nsuch as [EO](https://github.com/stac-extensions/eo), [View](https://github.com/stac-extensions/view).\n- [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom\nfields but it is recommended to add multiple fields for related values instead of a nested object,\ne.g., two fields `view:azimuth` and `view:off_nadir` instead of a field `view` with an object\nvalue containing the two fields. The convention (as used within Extensions) is for related fields \nto use a common prefix on the field names to group them, e.g. `view`. A nested data structure should\nonly be used when the data itself is nested, as with `eo:bands`.\n\n### Link Object\n\nThis object describes a relationship with another entity. Data providers are advised to be liberal\nwith the links section, to describe things like the Catalog an Item is in, related Items, parent or\nchild Items (modeled in different ways, like an 'acquisition' or derived data).\nIt is allowed to add additional fields such as a `title` and `type`.\n\n| Field Name | Type   | Description |\n| ---------- | ------ | ----------- |\n| href       | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |\n| rel        | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter \"Relation types\" for more information. |\n| type       | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |\n| title      | string | A human readable title to be used in rendered displays of the link. |\n\nFor a full discussion of the situations where relative and absolute links are recommended see the\n['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.\n\n#### Relation types\n\nSTAC Items use a variety of `rel` types in the link object,\nto describe the exact nature of the link between this Item and the entity it is linking to.\nIt is recommended to use the official\n[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible.\nThe following table explains places where STAC use custom `rel` types are used with Items.\nThis happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context.\n\n| Type         | Description                                                  |\n| ------------ | ------------------------------------------------------------ |\n| 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. |\n| root         | URL to the root STAC entity (Catalog or Collection). |\n| parent       | URL to the parent STAC entity (Catalog or Collection). |\n| 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. |\n| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. |\n\nA more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation \nTypes](../best-practices.md#using-relation-types) best practice. \n\n##### derived_from\n\n*Note regarding the type `derived_from`: A full provenance model is far beyond the scope of STAC,\nand the goal is to align with any good independent spec that comes along for that.\nBut the derived_from field is seen as a way to encourage fuller specs and at least start a linking\nstructure that can be used as a jumping off point for more experiments in provenance tracking*\n\n#### Collections\n\nItems are *strongly recommended* to provide a link to a STAC Collection definition.\nIt is important as Collections provide additional information about a set of items,\nfor example the license, provider and other information\ngiving context on the overall set of data that an individual Item is a part of.\n\nIf Items are part of a STAC Collection, the\n[STAC Collection spec *requires* Items to link back to the Collection](../collection-spec/collection-spec.md#relation-types).\nLinking back must happen in two places:\n\n1. The field `collection` in an Item must be filled (see section 'Item fields'). It is the `id` of a STAC Collection.\n2. An Item must also provide a link to the STAC Collection using the [`collection` relation type](#relation-types):\n   ```js\n   \"links\": [\n     { \"rel\": \"collection\", \"href\": \"link/to/collection/record.json\" }\n   ]\n   ```\n\n### Asset Object\n\nAn Asset is an object that contains a URI to data associated with the Item that can be downloaded\nor streamed. It is allowed to add additional fields.\n\n| Field Name  | Type      | Description |\n| ----------- | --------- | ----------- |\n| href        | string    | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |\n| title       | string    | The displayed title for clients and users. |\n| 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. |\n| 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. |\n| roles       | \\[string] | The [semantic roles](#asset-roles) of the asset, similar to the use of `rel` in links. |\n\n[Additional fields](#additional-fields) *may* be added to the assets, though this\nis recommended only in special cases. See [Additional Fields for Assets](#additional-fields-for-assets)) for more information.\n\n#### Asset Media Type\n\nAny media type can be used in an Item's asset `type` field, and [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) \nMedia Types are preferred. STAC Items that have sidecar metadata files associated with a data asset (e.g, `.tfw`, Landsat 8 MTL files)\nshould use media types appropriate for the the metadata file.  For example, if it is a plain text file, then `text/plain`\nwould be appropriate; if it is an XML, then `text/xml` is appropriate. For more information on media types as well as a \nlist of [common media types](../best-practices.md#common-media-types-in-stac) used in STAC see the [best practice on \nworking with media types](../best-practices.md#working-with-media-types).\n\n#### Asset Roles\n\nThe `roles` field is used to describe the purpose of each asset. It is recommended to include one for every asset, to give users\na sense of why they might want to make use of the asset. There are some emerging standards that enable clients to take particular\naction when they encounter particular roles, listed below. But implementors are encouraged to come up with their own terms to \ndescribe the role.\n\n##### Asset Role Types\n\nLike the Link `rel` field, the `roles` field can be given any value, however here are a few standardized role names. \n\n| Role Name | Description                                                                           |\n| --------- | ------------------------------------------------------------------------------------- |\n| 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. |\n| 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. |\n| 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. |\n| metadata  | A metadata sidecar file describing the data in this Item, for example the Landsat-8 MTL file. |\n\nIt is STRONGLY RECOMMENDED to add to each STAC Item\n- a thumbnail with the role `thumbnail` for preview purposes\n- one or more data file although it doesn't need to use the suggested role `data`\n\nNote that multiple roles per asset are encouraged: pick all the ones that apply. So many should have the 'data' role, and then\nanother role to describe how the data is used. For more information on how to use roles see the [Asset \nRoles](../best-practices.md#asset-roles) section of the Best Practices document. It includes a [list of asset \nroles](../best-practices.md#list-of-asset-roles) that include many more ideas on roles to use. As they reach more widespread \nadoption we will include them here.\n\n#### Additional Fields for Assets\n\nAs detailed above, Items contain properties, which are the main source of metadata for searching across Items. Many content\nextensions can add further property fields as well. Any property that can be specified for an Item can also be specified for\na specific asset. This can be used to override a property defined in the Item, or to specify fields for which there is no\nsingle value for all assets.\n\n**It is important to note that the STAC API does not facilitate searching across Asset properties in this way, and this\nshould be used sparingly.** It is primarily used to define properties at the Asset level that may be used during use of\nthe data instead of for searching.\n\nFor example, `gsd` defined for an Item represents the best Ground Sample Distance (resolution) for the data within the Item.\nHowever, some assets may be lower resolution and thus have a higher `gsd`. The `eo:bands` field from the EO extension defines\nan array of spectral bands. However, it may be useful instead to specify the bands that are used in a particular asset.\n\nFor an example see the [sentinel2-sample](https://github.com/stac-utils/stac-examples/blob/main/sentinel2/sentinel2-sample.json).\nThe Sentinel-2 overall `gsd` is 10m, because this is\nthe best spatial resolution among all the bands and is defined in Item properties so it can be searched on. In the example\nBand 5 and others have a `gsd` of 20m, so that asset specifies the `gsd` as well, which overrides the Item `gsd` for this\none asset. The example also includes reduced resolution versions of files included as assets, using `gsd` to represent\nthe proper resolution.\n\nFor `eo:bands`, it could be put in Item properties as an array of all the bands, but in this case it's not. Instead,\nthe assets each define an array containing the spectral band information for that asset (in the order the bands appear\nin the file).\n\nFor examples of fields that this construct is recommended for,\nsee the [section of STAC Best Practices](../best-practices.md#common-use-cases-of-additional-fields-for-assets)\nthat talks about common use cases of additional fields for assets.\n\n## Media Type for STAC Item\n\nA STAC Item is a GeoJSON file ([RFC 7946](https://tools.ietf.org/html/rfc7946)), and thus should use the \n[`application/geo+json`](https://tools.ietf.org/html/rfc7946#section-12) as the [Media Type](https://en.wikipedia.org/wiki/Media_type) \n(previously known as the MIME Type). \n\n## Extensions\n\nThere are emerging best practices, which in time will evolve in to specification extensions for\nparticular domains or uses.\n\nThe [extensions page](../extensions/README.md) gives an overview about relevant extensions for STAC Items.\n"
  },
  {
    "path": "stac-spec/item-spec/json-schema/basics.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/basics.json#\",\n  \"title\": \"Basic Descriptive Fields\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"title\": {\n      \"title\": \"Item Title\",\n      \"description\": \"A human-readable title describing the Item.\",\n      \"type\": \"string\"\n    },\n    \"description\": {\n      \"title\": \"Item Description\",\n      \"description\": \"Detailed multi-line description to fully explain the Item.\",\n      \"type\": \"string\"\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/item-spec/json-schema/datetime.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#\",\n  \"title\": \"Date and Time Fields\",\n  \"type\": \"object\",\n  \"dependencies\": {\n    \"start_datetime\": {\n      \"required\": [\n        \"end_datetime\"\n      ]\n    },\n    \"end_datetime\": {\n      \"required\": [\n        \"start_datetime\"\n      ]\n    }\n  },\n  \"properties\": {\n    \"datetime\": {\n      \"title\": \"Date and Time\",\n      \"description\": \"The searchable date/time of the assets, in UTC (Formatted in RFC 3339) \",\n      \"type\": [\"string\", \"null\"],\n      \"format\": \"date-time\",\n      \"pattern\": \"(\\\\+00:00|Z)$\"\n    },\n    \"start_datetime\": {\n      \"title\": \"Start Date and Time\",\n      \"description\": \"The searchable start date/time of the assets, in UTC (Formatted in RFC 3339) \",\n      \"type\": \"string\",\n      \"format\": \"date-time\",\n      \"pattern\": \"(\\\\+00:00|Z)$\"\n    }, \n    \"end_datetime\": {\n      \"title\": \"End Date and Time\", \n      \"description\": \"The searchable end date/time of the assets, in UTC (Formatted in RFC 3339) \",                  \n      \"type\": \"string\",\n      \"format\": \"date-time\",\n      \"pattern\": \"(\\\\+00:00|Z)$\"\n    },\n    \"created\": {\n      \"title\": \"Creation Time\",\n      \"type\": \"string\",\n      \"format\": \"date-time\",\n      \"pattern\": \"(\\\\+00:00|Z)$\"\n    },\n    \"updated\": {\n      \"title\": \"Last Update Time\",\n      \"type\": \"string\",\n      \"format\": \"date-time\",\n      \"pattern\": \"(\\\\+00:00|Z)$\"\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/item-spec/json-schema/instrument.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/instrument.json#\",\n  \"title\": \"Instrument Fields\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"platform\": {\n      \"title\": \"Platform\",\n      \"type\": \"string\"\n    },\n    \"instruments\": {\n      \"title\": \"Instruments\",\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"constellation\": {\n      \"title\": \"Constellation\",\n      \"type\": \"string\"\n    },\n    \"mission\": {\n      \"title\": \"Mission\",\n      \"type\": \"string\"\n    },\n    \"gsd\": {\n      \"title\": \"Ground Sample Distance\",\n      \"type\": \"number\",\n      \"exclusiveMinimum\": 0\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/item-spec/json-schema/item.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#\",\n  \"title\": \"STAC Item\",\n  \"type\": \"object\",\n  \"description\": \"This object represents the metadata for an item in a SpatioTemporal Asset Catalog.\",\n  \"allOf\": [\n    {\n      \"$ref\": \"#/definitions/core\"\n    }\n  ],\n  \"definitions\": {\n    \"common_metadata\": {\n      \"allOf\": [\n        {\n          \"$ref\": \"basics.json\"\n        },\n        {\n          \"$ref\": \"datetime.json\"\n        },\n        {\n          \"$ref\": \"instrument.json\"\n        },\n        {\n          \"$ref\": \"licensing.json\"\n        },\n        {\n          \"$ref\": \"provider.json\"\n        }\n      ]\n    },\n    \"core\": {\n      \"allOf\": [\n        {\n          \"$ref\": \"https://geojson.org/schema/Feature.json\"\n        },\n        {\n          \"oneOf\": [\n            {\n              \"type\": \"object\",\n              \"required\": [\n                \"geometry\",\n                \"bbox\"\n              ],\n              \"properties\": {\n                \"geometry\": {\n                  \"$ref\": \"https://geojson.org/schema/Geometry.json\"\n                },\n                \"bbox\": {\n                  \"type\": \"array\",\n                  \"oneOf\": [\n                    {\n                      \"minItems\": 4,\n                      \"maxItems\": 4\n                    },\n                    {\n                      \"minItems\": 6,\n                      \"maxItems\": 6\n                    }\n                  ],\n                  \"items\": {\n                    \"type\": \"number\"\n                  }\n                }\n              }\n            },\n            {\n              \"type\": \"object\",\n              \"required\": [\n                \"geometry\"\n              ],\n              \"properties\": {\n                \"geometry\": {\n                  \"type\": \"null\"\n                },\n                \"bbox\": {\n                  \"not\": {}\n                }\n              }\n            }\n          ]\n        },\n        {\n          \"type\": \"object\",\n          \"required\": [\n            \"stac_version\",\n            \"id\",\n            \"links\",\n            \"assets\",\n            \"properties\"\n          ],\n          \"properties\": {\n            \"stac_version\": {\n              \"title\": \"STAC version\",\n              \"type\": \"string\",\n              \"const\": \"1.0.0\"\n            },\n            \"stac_extensions\": {\n              \"title\": \"STAC extensions\",\n              \"type\": \"array\",\n              \"uniqueItems\": true,\n              \"items\": {\n                \"title\": \"Reference to a JSON Schema\",\n                \"type\": \"string\",\n                \"format\": \"iri\"\n              }\n            },\n            \"id\": {\n              \"title\": \"Provider ID\",\n              \"description\": \"Provider item ID\",\n              \"type\": \"string\",\n              \"minLength\": 1\n            },\n            \"links\": {\n              \"title\": \"Item links\",\n              \"description\": \"Links to item relations\",\n              \"type\": \"array\",\n              \"items\": {\n                \"$ref\": \"#/definitions/link\"\n              }\n            },\n            \"assets\": {\n              \"$ref\": \"#/definitions/assets\"\n            },\n            \"properties\": {\n              \"allOf\": [\n                {\n                  \"$ref\": \"#/definitions/common_metadata\"\n                },\n                {\n                  \"anyOf\": [\n                    {\n                      \"required\": [\n                        \"datetime\"\n                      ],\n                      \"properties\": {\n                        \"datetime\": {\n                          \"not\": {\n                            \"type\": \"null\"\n                          }\n                        }\n                      }\n                    },\n                    {\n                      \"required\": [\n                        \"datetime\",\n                        \"start_datetime\",\n                        \"end_datetime\"\n                      ]\n                    }\n                  ]\n                }\n              ]\n            }\n          },\n          \"if\": {\n            \"properties\": {\n              \"links\": {\n                \"contains\": {\n                  \"required\": [\n                    \"rel\"\n                  ],\n                  \"properties\": {\n                    \"rel\": {\n                      \"const\": \"collection\"\n                    }\n                  }\n                }\n              }\n            }\n          },\n          \"then\": {\n            \"required\": [\n              \"collection\"\n            ],\n            \"properties\": {\n              \"collection\": {\n                \"title\": \"Collection ID\",\n                \"description\": \"The ID of the STAC Collection this Item references to.\",\n                \"type\": \"string\",\n                \"minLength\": 1\n              }\n            }\n          },\n          \"else\": {\n            \"properties\": {\n              \"collection\": {\n                \"not\": {}\n              }\n            }\n          }\n        }\n      ]\n    },\n    \"link\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"rel\",\n        \"href\"\n      ],\n      \"properties\": {\n        \"href\": {\n          \"title\": \"Link reference\",\n          \"type\": \"string\",\n          \"format\": \"iri-reference\",\n          \"minLength\": 1\n        },\n        \"rel\": {\n          \"title\": \"Link relation type\",\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"type\": {\n          \"title\": \"Link type\",\n          \"type\": \"string\"\n        },\n        \"title\": {\n          \"title\": \"Link title\",\n          \"type\": \"string\"\n        }\n      }\n    },\n    \"assets\": {\n      \"title\": \"Asset links\",\n      \"description\": \"Links to assets\",\n      \"type\": \"object\",\n      \"additionalProperties\": {\n        \"$ref\": \"#/definitions/asset\"\n      }\n    },\n    \"asset\": {\n      \"allOf\": [\n        {\n          \"type\": \"object\",\n          \"required\": [\n            \"href\"\n          ],\n          \"properties\": {\n            \"href\": {\n              \"title\": \"Asset reference\",\n              \"type\": \"string\",\n              \"format\": \"iri-reference\",\n              \"minLength\": 1\n            },\n            \"title\": {\n              \"title\": \"Asset title\",\n              \"type\": \"string\"\n            },\n            \"description\": {\n              \"title\": \"Asset description\",\n              \"type\": \"string\"\n            },\n            \"type\": {\n              \"title\": \"Asset type\",\n              \"type\": \"string\"\n            },\n            \"roles\": {\n              \"title\": \"Asset roles\",\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        },\n        {\n          \"$ref\": \"#/definitions/common_metadata\"\n        }\n      ]\n    }\n  }\n}\n"
  },
  {
    "path": "stac-spec/item-spec/json-schema/licensing.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/licensing.json#\",\n  \"title\": \"Licensing Fields\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"license\": {\n      \"type\": \"string\",\n      \"pattern\": \"^[\\\\w\\\\-\\\\.\\\\+]+$\"\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/item-spec/json-schema/provider.json",
    "content": "{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$id\": \"https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/provider.json#\",\n  \"title\": \"Provider Fields\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"providers\": {\n      \"title\": \"Providers\",\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"object\",\n        \"required\": [\n          \"name\"\n        ],\n        \"properties\": {\n          \"name\": {\n            \"title\": \"Organization name\",\n            \"type\": \"string\",\n            \"minLength\": 1\n          },\n          \"description\": {\n            \"title\": \"Organization description\",\n            \"type\": \"string\"\n          },\n          \"roles\": {\n            \"title\": \"Organization roles\",\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\",\n              \"enum\": [\n                \"producer\",\n                \"licensor\",\n                \"processor\",\n                \"host\"\n              ]\n            }\n          },\n          \"url\": {\n            \"title\": \"Organization homepage\",\n            \"type\": \"string\",\n            \"format\": \"iri\"\n          }\n        }\n      }\n    }\n  }\n}"
  },
  {
    "path": "stac-spec/overview.md",
    "content": "# STAC Overview\n\nThere are three component specifications that together make up the core SpatioTemporal Asset Catalog specification.\nEach can be used alone, but they work best in concert with one another. The [STAC API specification](https://github.com/radiantearth/stac-api-spec) \nbuilds on top of that core, but is out of scope for this overview. An [Item](item-spec/item-spec.md) represents a \nsingle [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as [GeoJSON](https://geojson.org/) so it can be searched. \nThe [Catalog](catalog-spec/catalog-spec.md) specification provides structural elements, to group Items\nand [Collections](collection-spec/collection-spec.md). Collections *are* catalogs, that add more required metadata and \ndescribe a group of related Items. For more on the differences see the [section below](#catalogs-vs-collections).\n\nA [UML diagram](https://en.wikipedia.org/wiki/Unified_Modeling_Language) of the [STAC model](STAC-UML.pdf) is also \nprovided to help with navigating the specification. \n\n## Foundations\n\nSTAC is built on top of many great standards and practices. Every part of STAC is \n[JSON](https://www.json.org/json-en.html), and [GeoJSON](https://geojson.org/) provides the core geometry fields \nand [features](https://en.wikipedia.org/wiki/Simple_Features) definition. All fields are described in the \nspecifications, and the acceptable values are defined with [JSON Schema](https://json-schema.org/). The released\nJSON Schemas provide the core testing definitions, and are used in an array of validation tools. We also rely\non [RFC 8288 (Web Linking)](https://tools.ietf.org/rfc/rfc8288.txt) to express relationships between resources,\nand IANA [Media Types](https://en.wikipedia.org/wiki/Media_type) to describe file formats and format contents.\nThe [OGC API - Features](https://ogcapi.ogc.org/features/) standard is a final core building block. The STAC\nCollection extends the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_)\nJSON defined in OGC API - Features (and the full API definition is the foundation for the STAC API specification).\n\nThe STAC specifications are written to be understandable without needing a full background in these. But if you \nwant to get deep into STAC tool implementation and are not familiar with any of the standards mentioned above it is \nrecommended to read up on them. STAC development is guided by set of core philosophical tenets, like \nbuilding small reusable parts that are loosely coupled, focusing on developers, and more - see our the \n[principles](principles.md) document to learn more.\n\n*Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat\nthem differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should \nnot be used unless the STAC spec defines its use - instead the field should be left out entirely.* \n\n## Item Overview\n\nFundamental to any SpatioTemporal Asset Catalog, an [Item](item-spec/item-spec.md) object represents a unit of\ndata and metadata, typically representing a single scene of data at one place and time.   A STAC Item is a \n[GeoJSON](http://geojson.org/) [Feature](https://tools.ietf.org/html/rfc7946#section-3.2)\nand can be easily read by any modern GIS or geospatial library, and it describes a \n[SpatioTemporal Asset](#what-is-a-spatiotemporal-asset). \nThe STAC Item JSON specification uses the GeoJSON geometry to describe the location of the asset, and \nthen includes additional information:\n\n- the time the asset represents;\n- a thumbnail for quick browsing;\n- asset links, to enable direct download or streaming access of the asset;\n- relationship links, allowing users to traverse other related resources and STAC Items.\n\nA STAC Item can contain additional fields and JSON structures to communicate more information about the\nasset, so it can be easily searched. STAC provides a core set of \n[Common Metadata](item-spec/common-metadata.md)\nand there is a wider community working on a variety of [STAC Extensions](extensions/) that provide shared metadata for \nmore specific domains. Both aim to describe data with well known, well\ndefined terms to enable consistent publishing and better search. For more recommendations on selecting fields\nfor an Item see [this section](best-practices.md#field-selection-and-metadata-linking) of the best practices document.\n\n### What is a SpatioTemporal Asset\n\nA 'spatiotemporal asset' is any file that represents information about the earth captured in a certain \nspace and time. Examples include Imagery (from satellites, planes and drones), SAR, Point Clouds (from\nLiDAR, Structure from Motion, etc), Data Cubes, Full Motion Video, and data derived from any of those.\nThe key is that the GeoJSON is not the actual 'thing', but instead references files and serves as an\nindex to the 'assets'. It is [not recommended](best-practices.md#representing-vector-layers-in-stac) \nto use STAC to refer to traditional vector data layers (shapefile, geopackage) as assets, as they\ndon't quite fit conceptually. \n\n## Catalogs vs Collections\n\nBefore we go deep into the Catalogs and Collections, it is worth explaining the relationship \nbetween the two and when you might want to use one or the other. \n\nA Catalog is a very simple construct - it just provides links to Items or to other Catalogs. \nThe closest analog is a folder in a file structure, it is the container for Items, but it can \nalso hold other containers (folders / catalogs). \n\nThe Collection entity shares most fields with the Catalog entity but has a number of additional fields:\nlicense, extent (spatial and temporal), providers, keywords and summaries. Every Item in a Collection links\nback to their Collection, so clients can easily find fields like the license. Thus every Item implicitly \nshares the fields described in their parent Collection. Collection entities can be used just like Catalog \nentities to provide structure, as they provide all the same options for linking and organizing.\n\nBut what *should* go in a Collection, versus just in a Catalog?  A Collection will generally consist of\na set of assets that are defined with the same properties and share higher level metadata. In the \nsatellite world these would typically all come from the same sensor or constellation. It corresponds\ndirectly to what others call a \"dataset series\" (ESA, ISO 19115), \"collection\" (CNES, NASA), and \n\"dataset\" (JAXA, DCAT). So if all your Items have the same properties, they probably belong in \nthe same Collection. But the construct is deliberately flexible, as there may be good reasons\nto break the recommendation.\n\nCatalogs in turn are used for two main things:\n\n- Split overly large collections into groups\n- Group collections into a catalog of Collections (e.g. as entry point for navigation to several Collections).\n\nThe first case allows users to browse down into the Items of large collections. A collection like\nLandsat usually would start with path and row Catalogs to group by geography, and then year, \nmonth and day groups to enable deeper grouping. [Dynamic catalogs](best-practices.md#dynamic-catalogs) can\nprovide multiple grouping paths, serving as a sort of faceted search.\n\nThe second case is used when one wants to represent diverse data in a single place. If an organization\nhas an internal catalog with Landsat 8, Sentinel 2, NAIP data and several commercial imagery providers\nthen they'd have a root Catalog that would link to a number of different Collections. \n\nSo in conclusion it's best to use Collections for what you want user to find as starting point, and then\nCatalogs are just for structuring and grouping the data. Future work includes a mechanism to actually\nsearch Collection-level data, hopefully in concert with other specifications.\n\n## Catalog Overview\n\n*NOTE: The below examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to \nserve as a Catalog*\n\nThere are two required element types of a Catalog: Catalog and Item. A STAC Catalog\npoints to [STAC Items](item-spec/README.md), or to other STAC catalogs. It provides a simple\nlinking structure that can be used recursively so that many Items can be included in \na single Catalog, organized however the implementor desires. \n\nSTAC makes no formal distinction between a \"root\" Catalog and the \"child\" Catalogs. A root Catalog\nis simply the top-most Catalog or Collection -- it has no parent. A nested catalog structure is useful (and\nrecommended) for breaking up massive numbers of catalog Items into logical groupings. For example,\nit might make sense to organize a catalog by date (year, month, day), or geography (continent,\ncountry, state/prov). See the [Catalog Layout](best-practices.md#catalog-layout) best practices\nsection for more.\n\nA simple STAC structure might look like this:\n\n- catalog (root)\n  - catalog\n    - catalog\n      - item\n        - asset\n      - item\n        - asset\n    - item\n      - asset\n      - asset\n\nThis example might be considered a somewhat \"typical\" structure. However, Catalogs and Items can\ndescribe a number of different relationships. The following shows various relationships between\ncatalogs and items:\n\n- `Catalog` -> `Item` (this is a common structure for a catalog to list links to Items)\n- `Catalog` -> `Catalog` (this is a common tree structure to group sets of Items. Each catalog in\n  this relationship may also include Item links as well as catalog links)\n\nThe relationships are all described by a common `links` object structure, making use of\nthe `rel` field to further describe the relationship. \n\nThere are a few types of catalogs that implementors occasionally refer to. These get defined by the `links` structure.\n\n- 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\n  might have sub-catalogs for each Path and Row, so as to create a nice tree structure for users to follow.\n- A **root catalog** is a Catalog that only links to sub-catalogs. These are typically entry points for browsing data. Often\n  they will contain the [STAC Collection](collection-spec/) definition, but in implementations that publish diverse information it may\n  contain sub-catalogs that provide a variety of Collections.\n- A **parent catalog** is the Catalog that sits directly above a sub-catalog. Following parent catalog links continuously\n  will naturally end up at a root catalog definition.\n \nIt should be noted that a Catalog does not have to link back to all the other Catalogs that point to it. Thus a published \nroot catalog might be a sub-catalog of someone else's structure. The goal is for data providers to publish all the \ninformation and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are\nlinked to across the web.\n\n### Static and Dynamic Catalogs\n\nThe Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as\nsimply putting linked json files on a file server or an object storage service (like [AWS S3](https://aws.amazon.com/s3/)),\nor it can be generated on the fly by a live server. The first type of implementation is often called a 'static catalog',\nand any catalog that is not just files is called a 'dynamic catalog'. You can read more about the two types along with\nrecommendations in [this section](best-practices.md#static-and-dynamic-catalogs) of the best practices document, \nalong with how to keep a [dynamic catalog in sync](best-practices.md#static-to-dynamic-best-practices) with a static one.\n\n### Catalog Best Practices\n\nIn addition to information about different catalog types, the [best practices document](best-practices.md) has\na number of suggestions on how to organize and implement good catalogs. The [catalog specification](catalog-spec/catalog-spec.md)\nis designed for maximum flexbility, so none of these are required, but they provide guidance for implementors who\nwant to follow what most of the STAC community is doing.\n\n- [Catalog Layout](best-practices.md#catalog-layout) is likely the most important section, as following its \nrecommendations will enable catalogs to work better with client tooling that optimizes for known layouts.\n- [Use of Links](best-practices.md#use-of-links) articulates practices for making catalogs that are portable (with\nrelative links through out) and ones that are published in stable locations (with absolute self links).\n- [Versioning for Catalogs](best-practices.md#versioning-for-catalogs) explains how to use STAC's structure to\nkeep a history of changes made to Items and catalogs.\n- [STAC on the Web](best-practices.md#stac-on-the-web) explains how catalogs should have html versions for \neach Item and Catalog, as well as ways to achieve that.\n\n## Collection Overview\n\nA STAC Collection includes the core fields of the Catalog entity and also provides additional metadata to describe \nthe set of Items it contains. The required fields are fairly \nminimal - it includes the 4 required Catalog fields (id, description, stac_version and links), and adds license \nand extents. But there are a number of other common fields defined in the spec, and more common fields are also \ndefined in [STAC extensions](extensions/). These serve as basic metadata, and ideally Collections also link to \nfuller metadata (ISO 19115, etc) when it is available.\n\nAs Collections contain all of Catalogs' core fields, they can be used just as flexibly. They can have both parent Catalogs and Collections\nas well as child Items, Catalogs and Collections. Items are strongly recommended to have a link to the Collection\nthey are a part of. Items can only belong to one Collection, so if an Item is in a Collection that is the child of \nanother Collection, then it must pick which one to refer to. Generally the 'closer' Collection, the more specific\none, should be the one linked to.\n\nThe Collection specification is used standalone quite easily - it is used to describe an aggregation of data, \nand doesn't require links down to sub-catalogs and Items. This is most often used when the software\ndoes operations at the layer / coverage level, letting users manipulate a whole collection of assets at once. They often\nhave an optimized internal format that doesn't make sense to expose as Items. [OpenEO](https://openeo.org/) and \n[Google Earth Engine](https://earthengine.google.com/) are two examples that only use STAC collections, and\nboth would be hardpressed to expose individual Items due to their architectures. For others implementing STAC\nCollections can also be a nice way to start and achieve some level of interoperability. \n"
  },
  {
    "path": "stac-spec/package.json",
    "content": "{\n  \"name\": \"stac-spec\",\n  \"version\": \"1.0.0\",\n  \"description\": \"STAC spec helpers to check the spec.\",\n  \"repository\": \"https://github.com/radiantearth/stac-spec\",\n  \"license\": \"Apache-2.0\",\n  \"scripts\": {\n    \"check\": \"npm run check-markdown && npm run check-examples\",\n    \"check-markdown\": \"remark . -f -r .circleci/rc.yaml\",\n    \"check-examples\": \"stac-node-validator . --lint --verbose --schemas .\",\n    \"format-examples\": \"stac-node-validator . --format --schemas .\",\n    \"publish-schemas\": \"node .circleci/publish-schemas.js\"\n  },\n  \"dependencies\": {\n    \"gh-pages\": \"^3.0.0\",\n    \"klaw-sync\": \"^6.0.0\",\n    \"remark-cli\": \"^8.0.0\",\n    \"remark-lint\": \"^7.0.0\",\n    \"remark-lint-no-html\": \"^2.0.0\",\n    \"remark-preset-lint-consistent\": \"^3.0.0\",\n    \"remark-preset-lint-markdown-style-guide\": \"^3.0.0\",\n    \"remark-preset-lint-recommended\": \"^4.0.0\",\n    \"remark-validate-links\": \"^10.0.0\",\n    \"stac-node-validator\": \"^1.1.0\"\n  }\n}\n"
  },
  {
    "path": "stac-spec/principles.md",
    "content": "This project will be governed by a set of informal core principles. These principles are not set in stone,\nand indeed they should evolve in the same manner that all specifications worked on should - proposed and\nreviewed in pull requests, approved by consensus. The goal of the principles is to help avoid\n[bikeshedding](http://bikeshed.org/) - lay down some meta-rules so we can focus on creating useful\ncore geospatial standards.\n\n- **Creation and evolution of specs in Github**, using Open Source principles\n(please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you).\nThe collaboration facilities of Github should be used to their full extent. All proposed improvements and\nchanges should come in the form of pull requests, using code review functionality to discuss changes.\n\n- **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and\nare not considering legacy options. Forward looking protocols can be considered as extensions,\nbut the default specifications should be in JSON, following best REST practices. HTTP caching and\nerror codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,\nso it should also be core. [JSON API](http://jsonapi.org/) should be used as basis of decisions where possible.\n\n- **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible,\ndefining one core concept and refraining from describing lots of options. Additional options can be made\nas separate specifications that build on the core. But the core specs should be small and easily understandble,\nwith clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces.\nImplementors should not be forced to implement lots of options just for basic compliance - they should be\nable to pick and choose which pieces are relevant to the problems they are trying to solve.\n\n- **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice\nshould be considered with a developer audience. And specifications should be accessible to developers who do not\nhave geospatial background. A developer should not need to understand 'projections' to implement a simple feature\naccess service. But we should think through the spec extensions they could use in the future when their client asks\nfor data in a different projection.\n\n- **Working code required.** Proposed changes should be accompanied by working code\n(ideally with a link to an online service running the code). A reference implementation should be available\nonline to power the interactive documentation. Fully accepted specifications should have at least 3 implementations\nthat cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model.\n\n- **Design for scale.** The design should work great with more data than can be imagined right now.\nIdeally implementations are built with large test data sets to validate that they will work.\nEverything should be compatible with content distribution network (CDN) caching.\n\n## Resources\n\n- Open Source Principles - [Producing Open Source Software](http://producingoss.org) by Karl Fogel.\n- Best Practices JSON API Design - [JSON API](http://jsonapi.org/) best practices for making API's with JSON\n- Pragmatic REST - [Web API Design: Crafting interfaces that developers love](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf)\n- Open API Initiative - [OpenAPIs.org](https://openapis.org/)\n"
  },
  {
    "path": "stac-spec/process.md",
    "content": "## STAC Development & Release Process\n\n### Development Process\n\nThe SpatioTemporal Asset Catalog specification is under active development. The goal is to get to a small, flexible stable \nrelease that can be extended in a variety of ways. The core development team aims to release early and often, which generally\nhas meant a new release between two and four months since the previous one. \n\nThe `master` branch aims to always be stable, meaning that all the pieces of the specification are consistent and well\nexplained, and all the examples are consistent with the specification. The `dev` branch is a place of active development, \nwhere a new change in one part of the spec might not yet be fully updated everywhere else. The team uses the \n[stac-spec issue tracker](https://github.com/radiantearth/stac-spec/issues) to identify and track all that will be done for \na release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and\nexamples.\n\nAny changes to the spec must be made as pull requests to the `dev` branch. Anyone is welcome and encouraged to bring ideas\nand improvements, to the issue tracker or (ideally) as pull requests. To merge a new pull request the work must be reviewed\nby at least two members of the STAC spec 'core team' (who have write access to the main repository). It also must pass the\nContinuous Integration (CI) testing, which checks all markdown and example files for proper formatting, and also validates all\nexamples against JSON schema. For more information about making pull requests see [CONTRIBUTING.md](CONTRIBUTING.md), \nand there is also information on how to [run the CI checks locally](CONTRIBUTING.md#check-files).\n\n#### Core STAC Team\n\nThe current list of people who are part of the 'core STAC team', and can approve pull requests.\n\n- [Alex Kaminsky](https://github.com/alkamin)\n- [Alexandra Kirk](https://github.com/anayeaye)\n- [Chris Holmes](http://github.com/cholmes)\n- [Emmanuel Mathot](https://github.com/emmanuelmathot)\n- [Michael Smith](https://github.com/hgs-msmith)\n- [James Banting](https://github.com/jbants)\n- [James Santucci](https://github.com/jisantuc)\n- [Josh Fix](https://github.com/joshfix)\n- [Rob Emanuele](https://github.com/lossyrob)\n- [Matthias Mohr](https://github.com/m-mohr)\n- [Matt Hanson](https://github.com/matthewhanson)\n- [Phil Varner](https://github.com/philvarner)\n\nAnyone can be nominated to the core STAC team, and that generally happens after contributing a few pull requests\nand/or helping review other PR's. Nominations are reviewed by the [PSC](#project-steering-committee), and must recieve\n3 positive votes and no negatives.\n\n### Release Process\n\nTo release a new version of the STAC spec the following list of tasks must be done. \n\n- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github \nissue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not \nneed to be completed, but the core release team should all review the issues to make sure that the critical ones for the \nrelease have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no\nopen issues against the milestone.\n- **Agreement from the Project Steering Committee**: The PSC should meet (on phone or on gitter) and decided that the release is ready.\nThis should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep\nwith a coherent whole.\n- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense\nand there are no typos, errors, etc.\n- **Update the version numbers**: There are several places in the spec that use the version number or a branch name in text\nor a link. These include the markdown files and the JSON schemas. Right now the best thing to do is just a search & replace\nfor the last version number and `https://schemas.stacspec.org/dev/` with `https://schemas.stacspec.org/<release-version>/`\n(in JSON Schemas, don't replace it here). `<release-version>` must correspond with the tag on GitHub, usually including a leading `v`.\nHopefully in the future there will be scripts to do this. \n- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements\nin the release. And anything in 'unreleased' section should move to the version of the spec to be released.\n- **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github\nrepository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state \nof the spec.\n- **Release on Github**: The final step to create the release is to add a new 'release' on \n<https://github.com/radiantearth/stac-spec/releases>. This should use a tag like the others, with a 'v' prefix and then the \nrelease number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to \nthe full milestone of everything closed in the issue tracker.\n- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel\nto post / promote it.\n\n#### Release Candidates\n\nBefore any release that has *major* changes (made as a judgement call by the core contributors) there should be a 'release \ncandidate' to ensure the wider community of implementors can try it out\nand catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec\nversion is good, so this step is essential if there are major changes. The release should proceed as normal, but called\nvX.Y.Z-rc.1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations\nshould be updated to the new specification before there is a real release. And ideally a client like STAC Browser is also \nupdated. This provides the core sanity check. If there are changes or fixes to the spec or \nschemas needed from their feedback then make fixes and do rc.2. If it is just fixes to the examples or tooling then no \nadditional RC is needed. After there is no more changes to spec or schemas then the release process should be done on master,\nwith no changes to the spec - just updating the version numbers.\n\n### Governance \n\nThe vast majority of decisions on STAC are made by the [Core STAC Team](#core-stac-team) reaching consensus in\ndiscussions in pull requests and issues. Any change to the specification must have two positive reviews and no negative\nreviews. \n\n#### Project Steering Committee\n\nFor the rare case where a decision cannot be reached by consensus, there is a Project Steerting Committee that has ultimate\ndecision making authority. This consists of individuals who are intended to represent the various communities which have a \nstake in the specification and surrounding ecosystem. An odd number is chosen to facilitate the voting process and help prevent ties.\nThis committee also handles the allocation of any funds that are raised for the project.\n\nTurnover is allowed and expected to accommodate people only able to become active on the project in intervals.\nA PSC member may step down at any time.\n\n#### Current Project Steering Committee\n\n- [Matthias Mohr](https://github.com/m-mohr) - University of Muenster, [OpenEO](https://openeo.org/) and [Radiant Earth](https://www.radiant.earth/)\n- [Matt Hanson](https://github.com/matthewhanson) - [Element 84](https://www.element84.com/)\n- [James Banting](https://github.com/jbants) - [SparkGeo](https://sparkgeo.com/)\n- [Rob Emanuele](https://github.com/lossyrob) - [Microsoft](https://microsoft.com/)\n- [Chris Holmes](https://github.com/cholmes) - [Planet](https://planet.com) and [Radiant Earth](https://www.radiant.earth/)\n\n#### PSC Membership\n\nA new PSC member can be nominated at any time. Voting for a new PSC is done by current active PSC members. PSC nominations are \ngenerally given in recognition to very significant contributions to the specification or the broader ecosystem. PSC members\nare not expected to be technical, and we hope to recognized contributions in documentation, outreach and evangelism. \n\nNominated PSC members must recieve a majority of +1 vote’s from the PSC, and no -1’s.\n\nThe initial PSC was selected by Chris Holmes, who was deemed the 'Benevolent Dictator for Life' for the bootstrapping phase.\n"
  }
]