diff --git a/.circleci/config.yml b/.circleci/config.yml index f43cb0732..aa88f0ac8 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,29 +1,18 @@ version: 2 jobs: build: + working_directory: ~/stac docker: - image: circleci/python:3.6.4 - working_directory: ~/stac - steps: - checkout - run: sudo chown -R circleci:circleci /usr/local/bin - run: sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages - - restore_cache: - key: v2-python-requirements-{{ checksum "requirements.txt" }} - run: name: install command: | - git clone git@github.com:sparkgeo/stac-validator.git ~/stac-validator - cd ~/stac-validator - pip install -r requirements.txt - pip install . - - save_cache: - key: v2-python-requirements-{{ checksum "requirements.txt" }} - paths: - - "~/.cache/pip" - - "/usr/local/lib/python3.6/site-packages" + pip install stac-validator - run: name: validate command: | diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a596e8ea..3a2cca05a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## Unreleased + +None yet. + +## [v0.7.0] - 2019-05-06 + +### Fixed +- Updated language / fixed typos +- Moved static vs dynamic discussion text to catalog best practices document +- Moved hosting of interactive api docs from swaggerhub to [stacspec.org](http://stacspec.org) +- JSON Schemas are now all following the latest JSON Schema version, draft 07. + +### Changed +- No longer require an absolute self link for Items, Collections and Catalogs. +- Reorganized api-spec, added extensions folder to hold API extensions +- Change the fields parameter in the API to allow filtering on any property. +- Refinements to SAR extension, changed several fields from a single array-based field (`sar:absolute_orbit`, `sar:resolution`, `sar:pixel_spacing`, `sar:looks`) to multiple fields with exactly one value. +- Commons extension ability to 'merge' properties is now in the core specification + +### Added +- Catalog best practices document, including recommendations for catalog layouts, html, and self-contained catalogs. +- `page` parameter for STAC API +- Optional `collection` property field in Items (previously part of the Commons extension) +- It is now required to link to `/stac/search/` from `/stac/` +- Added new fields to SAR extension: `sar:incidence_angle`, `sar:relative_orbit`, `sar:observation_direction` +- Added new filter parameters `ids` and `collections` to `/stac/search/` + +### Removed +- Removed the field `sar:off_nadir` from the SAR extension +- JavaScript-based validation + ## [v0.6.2] - 2019-03-01 ### Fixed @@ -130,6 +161,7 @@ Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkam [Unreleased]: https://github.com/radiantearth/stac-spec/compare/master...dev +[v0.7.0]: https://github.com/radiantearth/stac-spec/compare/v0.6.2...v0.7.0 [v0.6.2]: https://github.com/radiantearth/stac-spec/compare/v0.6.1...v0.6.2 [v0.6.1]: https://github.com/radiantearth/stac-spec/compare/v0.6.0...v0.6.1 [v0.6.0]: https://github.com/radiantearth/stac-spec/compare/v0.5.2...v0.6.0 diff --git a/README.md b/README.md index c7659d81f..11fc0ac83 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The minimal amount is specified right now, but best practices should emerge with ## Current version and branches The [master branch](https://github.com/radiantearth/stac-spec/tree/master) is the 'stable' version of the spec. It is currently version -**0.6.2** of the specification. The +**0.7.0** of the specification. The [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development takes place, and may have inconsistent examples. Whenever dev stabilizes a release is cut and we merge dev in to master. So master should be stable at any given time. It is possible that there may be small releases in quick succession, especially if they are nice improvements that do @@ -108,7 +108,7 @@ Vendors can extend those core fields for the metadata they want to make availabl #### UML Diagram -A UML diagram of the [STAC model](STAC-060-uml.pdf) is provided to help with navigating the specification. +A UML diagram of the [STAC model](STAC-UML.pdf) is provided to help with navigating the specification. ## Contributing diff --git a/STAC-060-uml.pdf b/STAC-060-uml.pdf deleted file mode 100644 index 274ae27be..000000000 Binary files a/STAC-060-uml.pdf and /dev/null differ diff --git a/STAC-UML.drawio b/STAC-UML.drawio new file mode 100644 index 000000000..c05ecf0fc --- /dev/null +++ b/STAC-UML.drawio @@ -0,0 +1 @@ +7V1rj5s6Gv41I+0eKcjGXD92pj3blVrt0WlXu+fTiAkkQSWQJWQu/fVrE0ywzS2JTdKMp9J0cBwwfl4/fm+279DD+vUfebBZfc3CKLkzQfh6hz7emaZtIfybFLxVBcDdFyzzONwXwUPBt/hnVBWCqnQXh9GWqVhkWVLEG7ZwnqVpNC+YsiDPsxe22iJL2KdugmUkFHybB4lY+p84LFb7Us8Gh/LPUbxc0SdDUH2yDmjlqmC7CsLspVGEPt2hhzzLiv1f69eHKCF9R/tl/73fOz6tG5ZHaTHmC593//zr8bvzP3MZfpmhD58/oa//nkFYwfEcJLvqlYFh/FY1uXij/RCl4QfSnfgqzVJceL8q1gm+gvhP/GGFHMSvdb8tgrygtcM4WGdp+H0Vp/QjWteiBb/HSX2rEHd/9dgsL1bZMkuD5NOh9D5I4iW+1cckWuD3vn+O8iLGeH2oip+yosjWZaOK/O2/uATQi7/IhWHTy4+vzQ8/vtVXYdUecrXvCNKqzm6virbZLp9HPX3tVOIb5Muo6Kln2rV04FEVZesINw9/sRpSM2C4Jh1F1aiaVaMsj5KgiJ/ZtgbVEFjWt6rv/kcW47eob23TUVfd1vQAe4v9O1bfasoadyPLAYaJPODb1W/mthZCBvSB5TrVb5t9yr6Hep5CK2aLxTZi6uA/Gn12KCrHwlHjwhPGRRKnP7bCwCii14IdDXm0jX8GT2UFIkIb0uqyxfb9nf2xIcJzLENR3iLE6zgMS2FPgqcouQ/mP5Z5tkvDhyzJ8vK5aFH+1BJK7hC9tlFi1ZIDETVlt48UOiUQGMCmD6EC6EgRQIe5KULs9xXCLYA9D4ogyZYC3NuXeJ0EJQEusrSgVEVwn6/iJPwSvGU70rmY2OY/6NX9Ksvjn7h+QIWkSYT4tfHdMOc04bXJP+ab38gdK5kqZSz6gyIJuaKvwStT8UuwLaqCeZYkwWYbP9XtXuPhFqf3FW+WlbZFnv2IGs1xyp/qpRvl+58+KRSYslOsIGLZB1rV9cth4q2n11Vz0kWgW9AYUTlWLkxBLgisj/g1t3GW3hF5RXA/TTT+bGcItk+rSbSJelU0ML8V2YbcbBPM43T5pazz0TqU/Fl1CynK8HcXSTkLrzChRGQCzrMiKDrJ6R535AOZIjFNmQ/4Gh6uS+ba4Dn5IUvxuwRxiWqEJeslItI1TgS6h58oF3QWcsaJAa0nXQqQIAW4ukZZLspUR7gYyraAchEXuAc10HKBdr0LA+0IQGMLc57Hm6LkdA23VLghsC6Mty+ObKLK36EPWFvF16UJ3mPvPiUZ0bsahiHkzN9zbda9VESvcVHaqwa07OqamKzY4AMAVQUHo5VcvDUu/ojyGHcYsSfGWq59uvCgOduvzOGXcD2btRGomnamkWDZluGhww/7FBNYhtP4cS32/oMmbH0f9nsdRikWkuCtUa0akZ2Nh1yfWKC9FdTYt8FZ9VmfEP5j397J7WlfJN2/AcOAfxcGHm89N8bZWM/PCKO5tN0qN9RhsHRZzKewoj/gxYFSxsKMlydI+H4qq5nSeBezlhbxVVBr7Qs0AOnLgz8QkysEwy5BfMXz64Guge816BoaADlXx9ZjnY/OAKsjy/cZiZNE6pC9K7TdI2m74R0FtueZyDZ9C5rQYX1KEAGDfABdxyIVqTYqm+Y5V4ZzHG0fXR/A6+B52hCe6H+7XaKvWFA50/sGp+igKZle9IQxTF/10jVQ/YGWQZOWMXUh72haPjWIpJrO7ZF0bg7RuWlxjnxkyuFz2zdMz3ahVf02uVnDYbR0h3P1j6V7iDyjEWZCHjtE+PiVJHbn6ddzj2Jr5I8ha/plzis+47FQOepFz+eNa+0V0Sknc5Nnc3cqUMV4f1xEawFQHedSFueyPE55s0TXt98W5jK9QTn7kwyEdEnc1vXjXO5xUHTAOiP8cUGCp8U0KKJ7Mjy3KmRTjLnrQMsJJNYRve8Op7VJm2l1C9tZ7lirPbOiViW3UbK4LkXS93l3LJ7wpzLw3ZEaodc/bwEDmlSJl2y5Wyy/uOZpqpw1LgvoaEuc058que5WKHl1yxvV6vbqlzPELf+9qW7WwAg4VnM7L+Yk9H7xttGxZNlzGTWshuYyVaFFKHq7NM4KcHZH6izKcBYDHcS+wNSlUwbko117Gy8FtzPg7QyxbvcchY+LPBMt5wuqqpDxd1KltUNHpZ5NOI1nc6weW82cg55NOOB1B4ZpUV8mVc5sORqvxemIDmeXj9V4bWT3ZMlD2zSank3AuYikJSRwL4P69WM+8lQFoC+u8DrtvsobDjw5kl2V582QolXfM0Nq76K6LHqbW0ThwlGTqbokeigaQz+it5csDztX02jVaWCgne3dU6U6maKmXK+W0FjLxbolZX5arNvU5HmUbrUBLB3rlqz5abEWPR2bPNsQYCJN49LhbsuanxZvUZ0uTWCtyU2mySGfNbWQPS5wq3A5pCUIBXGI6NF/7Ojfj65jlLgxEXp5OIsrZlZ5JEZlNdBnAt2iwU0LtLgsQ8cvVADdor5NC7SY9qVXtypBuk1zmxZq0RPH3Ftrb5Nobw6fd+KiURo9vyBFnlzonARZDHDdLjgkuuDmWZaHMUne1La6dLwv7YZD4tze45rRlN9O+ZWAkrdRMwG0BWLqaOo09jsSVYMQc0IRr9/vNHAC7j2j8JhJoRV8dSzRMv1rC0AF1G07GU0KtSUqAHemk+xRDdIwyEP8KYY5SklgDs8RzvLQI1oU5IlC215H04qCGLahopCSztDSMKE0tG6FNKk42KI4QAFnvdVvv8Y3Ztm136sazoCB6l1vz92z1+H9DCfu2cvfCEHuRlewLS+dWrX8qpVfNCi/LqD+pHPl15Ikv45FNk5r7DnA3Naii2yvSZrFGPut7b1+ZHK5OkIe3FPdcbjEyXrRx7kCDmQRNCfgiLmtizzDbXw8bl+jScVdzB54N1uq2x1Bo4l3VJ/xmqVCtMUcgmBLn6UdkpPEoPi51abyOpRBRA0V+QaImHCgM0tOsjXtjhntSlKI7JaEAx1tVAD0pVOIbDGmoP3KSpC+dA6RI7qVb81cuRb72+4/gEepuWJKMlf49GWLRqCuyCRxRH9oqaS+C5vE6V9BPZVNMtl2ho5of/4rTcgbN4MfICAtLVZkB7V1UOzyuCBVkui5PNgwW5CujRNyZADAIOH6T3iCIf/n5HeczpNdGIUlKefiLFjiG4WVzLys4iL6hqcs8ulLHmxYEeuyYPqNieaqY5Xb2HHj2/FbohtmywRlqTIuXHGCirImvAIa2vacLBnGZITFpqc2DIbCPFXqjCtyP5YW9GGDuW2R5eLGHu9FgZWVEeN2zC/XkhFDN6rjBWC5Dd8t9srQvnhSjCsGW0q056Qn8PcDvZWTCtwvngHjilpfiXtMOmK3btu1XoN+JuiXT3RxxehDiXq02Ypnumq8z8WbZixfDm8xrrBn9yTbhY9z0tEadumw2xdX4cQoQwl7tlg8pkEYa9Dlg+5dXJMTIw4l6MHPeL3DTdKQy7bUwMWVOHHxQgn5dpc+athVwY4urcV5rQ69PexREj1rm02RZ+bS6pwnGusCzO377FLnt3PHh+eafnXOS3446qF50EO9ZW7r/rn79oyJ9g1ueUv91sNpuR1hwSZOFLszYzR89M5FJx7IaNsDN+oIA0o7U6bDEnwKUtHNp+MB6vZDoAnY9Mw0zxdJBrWQTK1wymcZ0WhMg3e8FPb0CcU7OhmtFWp184loJ86z9TpLHzXgKgBv8/ZPC3jLJjg6rCMf6Db3/rRAi5ZhMJ/v8mAu7nak0T4T7Va//qRw+6JFuM+uenwJnrFJmC61J0AB7m3+/WlxF5M1FrskeSwb9LgKksXjGmvFGnnZyLe5+KdF3hSQ//b9A74XAIZr4JaAr1nYsgntcYl2DYdAi7kWlT+dgtSwFIEoRRJsJ24ZjyWORrctE1zZPkK+6J6Bt5YJfkj+rn1BCjLB5fmGugYyK3P1SUjHHg4zLlncO3ltK+clsn01p4G69BQl2uBKoehq10D9ruOO6rPb2fPo61M51Sc7+x1pL8Tt9S6y2/1Lrbi1uZPdZ8iwJ0P9lztb2R3vcT9sKmAAwLKzQc5GH2JofHXCocxjiXrs0p7+mR6/ievx8iPJow/Y+9abVB7L1ZgU2WPrLOa+Y/eNOZa6Ta79EPRTt+mB8+pXqu/FT7bzRRfHjR/l7Es+yrljdobcQINgOqaGQIxLjWTmk0KcMpmuAx0FUUiT2zsFnapfmoCd6+vduE8mKfkCIcYomLk7zzIxVfmSc3dz4h44bFai9PVTAzCsesVQveeJK0UWLZdV5oW45GhZ5NZCQY9ri6QJ0+IntOo542wX3rKbjhhFHfbGp7tq6Cuf77gNqWdwMkyh6L5luC0uol/2IG2J3DZosgKX1bXpsDx3msUafXPvMId1epjAYRR+yJHBWOLjCcnktxmSRHzI5SwdYPe2S6xvHUGUM349+3RUCc1WqrzhM68rJlFNlT7vwzGnw7Tj4EVKlVUXXRFZHqMIMj4ck/XhOF69W6QaH87wtisD/KtOt/Q4lwrLR8g2gOU60Ke/T+NfwXFz1FNkkTME/GOPINuLaaVQ9KffulYK+9WRG9BKRRcMQ7UkmRb3Ztsag1+OblmqHdrYajynDnuLxgYwzf7tiGaYuyBgKUuWa9zye4nRwsRYf4R/n5gJb/IbrFtqHOUWv4NXtRdjp1rO1acM3TONnFXfQlfiWIdQTAC/eVIf2Aj71yf1lqWCZP8nvfHwhIs9eD2tbbsnygrM4ZeqssjqjcgaYrHdYBEP9PHlp7BIx/kQ3es92tA2LWVoi/7GIlrjztBwK4Cb5m4Nwa1ucIvGGRRw/pWTEY/T3tmg8CHXxmlYDtAArttvO+ALhfkyo50ycMAwYAO79EyVc5O4uHzEOjnkhFNpWOXX4kaBrOwYzq1Cjwe5vJJtilb2Js+e47BlSx6tkk2mkjmmuHSrjbVrm1sBbev1t7Jm6K7zja5GIROTW3a51sXkI315XUxM38gzfRyEAqjdkYNaHdSiq0UfCNGqeSPYzCjBujfyfhHd+4IHUSBJKvhUa4ugZ3HP6feL8/Udf1R+3gQqOxKdZVRlfxdrh+DA+b03dzQGRAMJehh5/FLh4yLPriNR70SClk6iPTKCbXA+W8SXIiTQRlx+kuVzk/xYboS2bbiHI3MtxB4qSkN1sqnS8Vub3+lE8VtbNTI/z2bztjkbR+WgMoVBdevpeWiS9LwZYmfOmXM+pviyXGHRqJ4Hm9V+cwH06f8= \ No newline at end of file diff --git a/STAC-UML.pdf b/STAC-UML.pdf new file mode 100644 index 000000000..17b3b6baf Binary files /dev/null and b/STAC-UML.pdf differ diff --git a/api-spec/README.md b/api-spec/README.md index 1c3315da0..101ff1519 100644 --- a/api-spec/README.md +++ b/api-spec/README.md @@ -1,100 +1,60 @@ -# STAC API Specification +# STAC API -A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns [STAC Items](../item-spec/README.md) -(GeoJSON objects with required links, time stamp and links to assets) from search queries on a RESTful endpoint, and also -offers an endpoint to return STAC Items as a compliant [STAC Catalog](../catalog-spec/README.md) for discovery. +A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns STAC [Catalogs](../catalog-spec/README.md), [Collections](../collection-spec/README.md), or [Items](../item-spec/README.md), depending on the endpoint. Catalogs and Collections are JSON, while Items are GeoJSON - Features when just a single Item, or a Feature Collection when multiple Items are returned from a search. -The core of the spec is a single endpoint: +The API is a [Web Feature Service 3.0 (WFS 3) API](https://github.com/opengeospatial/WFS_FES), in that WFS 3 defines many of the endpoints that STAC uses. A STAC API should be compatible and usable with WFS3 clients. However, WFS 3 is still under development and while STAC tries to stay in sync with WFS3 developments, there may be discrepencies prior to final versions of both specifications. -``` -/stac/search -``` - -It takes a JSON object that can filter on date and time: - -```json -{ - "bbox": [5.5, 46, 8, 47.4], - "time": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" -} -``` - -This tells the server to return all the catalog items it has that are from the second half of March, 2018 and -that intersect with this area: - -![swiss_bbox](https://user-images.githubusercontent.com/407017/38382405-b5e69344-38be-11e8-90dc-35738678356d.png) - -_Map © OpenStreetMap contributors_ - -The return format is a [GeoJSON](http://geojson.org/) `FeatureCollection` with features compliant with the -[Item spec](../item-spec/README.md) for STAC. It returns to a limit optionally requested by the client, and includes -pageable links to iterate through any results past that limit. +## In this directory -## Dynamic Catalog API +**The Specification:** The main description of the STAC API specification is in the *[api-spec.md](api-spec.md)* file. It includes an overview and in depth explanation of the REST endpoints and parameters. -The other endpoint that is included as an option in STAC API is `/stac/`, which implements the [STAC Catalog Spec](../catalog-spec/README.md). -Implementing this enables tools like -[STAC Browser](https://medium.com/@mojodna/a-stac-browser-348a60674061) to use the dynamic catalog, to enable better -discovery through people browsing and search engines crawling. +**Extensions:** API Extensions are given in the *[extensions](extensions/)* folder. YAML fragments are provided for each extension with details provided in the *[README](extensions/README.md)*. -The OpenAPI spec in this directory documents the endpoint, and refer to the STAC Catalog and [STAC Collection](../collection-spec/README.md) for more information about the full content and link structure. +**Examples:** For samples of how the STAC API can be queried, see the *[examples.md](examples.md)* file. -## API Fragments +**API Definitions:** The API is described by the OpenAPI documents in the *[openapi](openapi/)* folder. -The STAC API should be simple to implement and extensible. To support that goal, the extensions are broken out into fragments. -These fragments should allow an implementor to layer on additional functionality as needed. +## OpenAPI definitions -We have structured our OpenAPI YAML files so that that can be joined together with `import` statements to prevent copying the -extensions into every possibly combination. In the [`api-spec` folder](.) you can expect to find complete OpenAPI definitions that are -useable as-is. For developers who want to author their own extension or combine extensions into a new OpenAPI defintion file, see below. +The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is contained within several YAML files in the [openapi](openapi/) and [extensions](extensions/) directories. -### Definitions +These are built into the definitive core API specification at [STAC.yaml](STAC.yaml), which can be viewed online at +[stacspec.org/STAC-api.html](https://stacspec.org/STAC-api.html). An additional OpenAPI definition is provided at +[STAC-extensions.yaml](STAC-extensions.yaml) that includes all the optional extensions, and can be browsed online at +[stacspec.org/STAC-ext-api.html](https://stacspec.org/STAC-ext-api.html). -The [`definitions` folder](./definitions/) contains the YAML files that will import fragments and output a complete definition. These are not directly usable in OpenAPI as they have `import` directives that need to be resolved. +In the [openapi](openapi/) directory there are three files -See [yaml-files](https://www.npmjs.com/package/yaml-files) for the syntax to import YAML fragments. +- WFS3.yaml - The WFS3.yaml file is the WFS3 OpenAPI definition **as currently used by STAC** +- STAC.yaml - Contains additional endpoints and components that STAC uses, which is treated as a WFS 3 extension +- STAC.merge.yaml - A file referencing the above two used to create the final [STAC.yaml](STAC.yaml) definition -### Fragments +A basic STAC implementation implements both the WFS3 and STAC definitions. -The [`fragments` folder](./fragments/) contains valid yaml that is intended to be merged into an openapi document. It should be possible to import one or more fragments at the same time to create a new STAC+extensions definition. +The YAML files in the [extensions](extensions/) folder are fragments. Fragments are used to describe incomplete pieces of an OpenAPI document, and must be merged with a complete OpenAPI document to be usable. This way extensions can be kept separate, and implementors can combine just the extensions they want to use in order to create a custom OpenAPI document they can use. -### Building OpenAPI Definitions +Editing should be done on the files in the [openapi](openapi/) and [extensions](extensions/) directories, *not* the `STAC.yaml` and `STAC-extensions.yaml` files, as these are automatically generated. If any of the files are edited, update the OpenAPI docs to overwrite the files: -To rebuild all definitions run the included Node.js scripts. - -```bash -npm install -npm run generate-all +``` +$ npm install +$ npm run generate-all ``` -## Specification - -The definitive specification for STAC is the [OpenAPI](http://openapis.org/) 3.0 YAML document. This is available -in several forms. The most straightforward for an implementor new to STAC is the [STAC-standalone.yaml](STAC-standalone.yaml). -This gives a complete service with the main STAC endpoint. See the [online documentation](https://app.swaggerhub.com/apis/cholmesgeo/STAC-standalone/) for the API rendered interactively. - -### Filtering +Create your own OpenAPI document by combinining the STAC definition with the extensions you want by creating a `myapi.merge.yaml` file. This file should contain a line indicating the files that need to be merged: -The core STAC API includes two filters - Bounding Box and Time. All STAC Items require space and time, and thus any STAC -client can expect to be able to filter on them. Most data will include additional data that users would like to query on, -so there is a mechanism to also specify more filters. See the [Filtering](filters.md) document for additional information -on the core filters as well as how to extend them. It is anticipated that "extensions" for domains (e.g. earth observation -imagery) will require additional fields to query their common fields. +``` +!!files_merge_append ["STAC.yaml", "extensions/query.fragment.yaml"] +``` -### WFS 3.0 Integration +Then, run the [yaml-files](https://www.npmjs.com/package/yaml-files) command line tool: -At the [Fort Collins Sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) the -decision was made to align STAC with the [WFS 3 specification](https://github.com/opengeospatial/WFS_FES), as -they are quite similar in spirit and intention. It is anticipated that most STAC implementations will also implement -WFS, and indeed most additional functionality that extends STAC will be done as WFS extensions. +``` +$ npm install +$ yaml-files myapi.merge.yaml myapi.yaml +``` -This folder thus also provides an [OpenAPI fragment](STAC-fragment.yaml), as well as an [example service](https://app.swaggerhub.com/apis/cholmesgeo/STAC_WFS-example/) ([YAML](WFS3core+STAC.yaml)) -for those interested in what a server that implements both STAC and WFS would look like. Those interested in learning more -can read the [deeper discussion of WFS integration](wfs-stac.md). +## API Evolution -### `GET` requests +The STAC API is still a work in progress. It currently tries to adhere to the WFS 3 API specification, with some STAC specific extensions, but WFS3 is also evolving and not finalized. The WFS 3 portion of the API is provided in the *[WFS3.yaml](openapi/WFS3.yaml)* and represents the version of WFS 3 that is currently being used by STAC. It may diverge some with the *[WFS3](https://github.com/opengeospatial/WFS_FES)* spec at any given time, either out of date or 'ahead', with proposals to align WFS3. The long term goal is for STAC's API and WFS 3 to completely align, ideally all of STAC API is made from WFS 3 plus its extension ecosystem, and STAC just focuses on the content. But until then STAC will work to bring practical implementation experience to WFS 3. -The `POST` endpoint is required for all STAC API implementations. The fields of the JSON object can also be used -for a `GET` endpoint, which are included in the OpenAPI specifications. The `GET` requests are designed to reflect the same -fields as the `POST` fields, and are based on WFS 3 requests. It is recommended for implementations to implement both, but -only `POST` is required. +The evolution of the STAC Item spec will take place in this repository, primarily informed by the real world implementations that people create. The goal is for the core API spec to remain quite small and stable, with most all the evolution taking place in extensions. Once there is a critical mass of implementations utilizing different extensions the core API spec will lock down to a 1.0. diff --git a/extensions/transaction/WFS3core+STAC+extensions.yaml b/api-spec/STAC-extensions.yaml similarity index 75% rename from extensions/transaction/WFS3core+STAC+extensions.yaml rename to api-spec/STAC-extensions.yaml index faed77743..1bb61a6b9 100644 --- a/extensions/transaction/WFS3core+STAC+extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: - title: The SpatioTemporal Asset Catalog API + WFS3 + Transaction extension - version: 0.6.2 + title: The SpatioTemporal Asset Catalog API + version: 0.7.0 description: >- This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API specification. Any service that implements this endpoint to allow search of @@ -9,100 +9,12 @@ info: available as an OpenAPI fragment that can be integrated with other OpenAPI definitions, and is designed to slot seamlessly into a WFS 3 API definition. contact: - name: Cool Sat Corp - email: info@cool-sat.com - url: 'http://cool-sat.com/contact/' + name: STAC Specification + url: 'http://stacspec.org' license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' -servers: - - url: 'http://dev.cool-sat.com/' - description: Development server - - url: 'http://www.cool-sat.com' - description: Production server paths: - /stac: - get: - summary: Return the root catalog or collection. - description: >- - Returns the root STAC Catalog or STAC Collection that is the entry point - for users to browse with STAC Browser or for search engines to crawl. - This can either return a single STAC Collection or more commonly a STAC - catalog that usually lists sub-catalogs of STAC Collections, i.e. a - simple catalog that lists all collections available through the API. - tags: - - STAC - responses: - '200': - description: A catalog json definition. Used as an entry point for a crawler. - content: - application/json: - schema: - $ref: '#/components/schemas/catalogDefinition' - /stac/search: - get: - summary: Search STAC items by simple filtering. - description: >- - Retrieve Items matching filters. Intended as a shorthand API for simple - queries. This method is optional. - operationId: getSearchSTAC - tags: - - STAC - parameters: - - $ref: '#/components/parameters/bbox' - - $ref: '#/components/parameters/time' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - post: - summary: Search STAC items by full-featured filtering. - description: >- - retrieve items matching filters. Intended as the standard, full-featured - query API. This method is mandatory. - operationId: postSearchSTAC - tags: - - STAC - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/searchBody' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string /: get: summary: landing page of this API @@ -221,41 +133,7 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/FeatureCollection.json' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - post: - summary: add a new feature to a collection - description: create a new feature in a specific collection - operationId: postFeature - tags: - - Extensions - parameters: - - $ref: '#/components/parameters/collectionId' - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/item' - - $ref: '#/components/schemas/itemCollection' - responses: - '200': - description: Status of the create request. - content: - application/geo+json: - schema: - type: string + $ref: 'https://stacspec.org/assets/FeatureCollection.json' text/html: schema: type: string @@ -283,7 +161,7 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/Feature.json' + $ref: 'https://stacspec.org/assets/Feature.json' text/html: schema: type: string @@ -296,65 +174,55 @@ paths: text/html: schema: type: string - put: - summary: update an existing feature by Id with a complete item definition + /stac: + get: + summary: Return the root catalog or collection. description: >- - Use this method to update an existing feature. Requires the entire - GeoJSON description be submitted. - operationId: putFeature + Returns the root STAC Catalog or STAC Collection that is the entry point + for users to browse with STAC Browser or for search engines to crawl. + This can either return a single STAC Collection or more commonly a STAC + catalog that usually lists sub-catalogs of STAC Collections, i.e. a + simple catalog that lists all collections available through the API. tags: - - Extensions - parameters: - - $ref: '#/components/parameters/collectionId' - - $ref: '#/components/parameters/featureId' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/item' + - STAC responses: '200': - description: Status of the update request. - content: - text/html: - schema: - type: string - application/json: - schema: - type: string - default: - description: An error occurred. + description: A catalog JSON definition. Used as an entry point for a crawler. content: application/json: schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - patch: - summary: update an existing feature by Id with a partial item definition + $ref: '#/components/schemas/catalogDefinition' + /stac/search: + get: + summary: Search STAC items with simple filtering. description: >- - Use this method to update an existing feature. Requires a GeoJSON - fragement (containing the fields to be updated) be submitted. - operationId: patchFeature + Retrieve Items matching filters. Intended as a shorthand API for simple + queries. + + + This method is optional, but you MUST implement `POST /stac/search` if + you want to implement this method. + operationId: getSearchSTAC tags: - - Extensions + - STAC parameters: - - $ref: '#/components/parameters/collectionId' - - $ref: '#/components/parameters/featureId' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/partialItem' + - $ref: '#/components/parameters/bbox' + - $ref: '#/components/parameters/time' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/ids' + - $ref: '#/components/parameters/collections' + - $ref: '#/components/parameters/query' + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/fields' responses: '200': - description: Status of the update request. + description: A feature collection. content: - text/html: + application/geo+json: schema: - type: string - application/json: + $ref: '#/components/schemas/itemCollection' + text/html: schema: type: string default: @@ -366,23 +234,33 @@ paths: text/html: schema: type: string - delete: - summary: delete an existing feature by Id - description: Use this method to delete an existing feature. - operationId: deleteFeature + post: + summary: Search STAC items with full-featured filtering. + description: >- + retrieve items matching filters. Intended as the standard, full-featured + query API. + + + This method is mandatory to implement if `GET /stac/search` is + implemented. If this endpoint is implemented on a server, it is required + to add a link with `rel` set to `search` to the `links` array in `GET + /stac` that refers to this endpoint. + operationId: postSearchSTAC tags: - - Extensions - parameters: - - $ref: '#/components/parameters/collectionId' - - $ref: '#/components/parameters/featureId' + - STAC + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/searchBody' responses: '200': - description: Status of the update request. + description: A feature collection. content: - text/html: + application/geo+json: schema: - type: string - application/json: + $ref: '#/components/schemas/itemCollection' + text/html: schema: type: string default: @@ -396,6 +274,20 @@ paths: type: string components: parameters: + collectionId: + name: collectionId + in: path + required: true + description: Identifier (name) of a specific collection + schema: + type: string + featureId: + name: featureId + in: path + description: Local identifier of a specific feature + required: true + schema: + type: string limit: name: limit in: query @@ -418,6 +310,56 @@ components: default: 10 style: form explode: false + page: + name: page + in: query + description: | + The optional page parameter returns the specified page of results + (with each page having size=limit). + + * Minimum = 1 + * Default = 1 + required: false + schema: + type: integer + minimum: 1 + default: 1 + style: form + explode: false + ids: + name: ids + in: query + description: > + The optional ids parameter returns a FeatureCollection of all matching + ids. + + If provided all other parameters that further restrict the number of + search results (except `page` and `limit`) will be ignored. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false + collections: + name: collections + in: query + description: > + The collections search parameter is a list of of collection IDs for + Items to match. + + Only items that are included in one of these collections will be + returned, otherwise + + all collections will be searched. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false bbox: name: bbox in: query @@ -464,44 +406,272 @@ components: description: > Either a date-time or a period string that adheres to RFC3339. Examples: - * A date-time: "2018-02-12T23:20:50Z" - - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or - + * A date-time: "2018-02-12T23:20:50Z" * A period: + "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - - Only features that have a temporal property that intersects the value - of - + Only features that have a temporal property that intersects the value of `time` are selected. If a feature has multiple temporal properties, it - is - - the decision of the server whether only a single temporal property is - used to - - determine the extent or all relevant temporal properties. + is the decision of the server whether only a single temporal property is + used to determine the extent or all relevant temporal properties. required: false schema: type: string style: form explode: false - collectionId: - name: collectionId - in: path - required: true - description: Identifier (name) of a specific collection + query: + name: query + in: query + description: >- + query for properties in items. Use the JSON form of the queryFilter used + in POST. + required: false schema: type: string - featureId: - name: featureId - in: path - description: Local identifier of a specific feature - required: true + sort: + name: sort + in: query + description: Allows sorting results by the specified properties + required: false schema: - type: string + $ref: '#/components/schemas/sort' + fields: + name: fields + in: query + description: Determines the shape of the features in the response + required: false + schema: + $ref: '#/components/schemas/fields' + style: form + explode: false schemas: - exception: + root: + type: object + required: + - links + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/' + rel: self + type: application/json + title: this document + - href: 'http://data.example.org/api' + rel: service + type: application/openapi+json;version=3.0 + title: the API definition + - href: 'http://data.example.org/conformance' + rel: conformance + type: application/json + title: WFS 3.0 conformance classes implemented by this server + - href: 'http://data.example.org/collections' + rel: data + type: application/json + title: Metadata about the feature collections + req-classes: + type: object + required: + - conformsTo + properties: + conformsTo: + type: array + items: + type: string + example: + - 'http://www.opengis.net/spec/wfs-1/3.0/req/core' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/oas30' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/html' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/geojson' + content: + type: object + required: + - links + - collections + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/collections.json' + rel: self + type: application/json + title: this document + - href: 'http://data.example.org/collections.html' + rel: alternate + type: text/html + title: this document as HTML + - href: 'http://schemas.example.org/1.0/foobar.xsd' + rel: describedBy + type: application/xml + title: XML schema for Acme Corporation data + collections: + type: array + items: + $ref: '#/components/schemas/collectionInfo' + collectionInfo: + type: object + required: + - name + - links + - stac_version + - id + - description + - license + - extent + properties: + name: + description: 'identifier of the collection used, for example, in URIs' + type: string + example: buildings + title: + description: human readable title of the collection + type: string + example: Buildings + description: + description: a description of the features in the collection + type: string + example: Buildings in the city of Bonn. + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/collections/buildings/items' + rel: item + type: application/geo+json + title: Buildings + - href: 'http://example.org/concepts/building.html' + rel: describedBy + type: text/html + title: Feature catalogue for buildings + extent: + $ref: '#/components/schemas/extent' + crs: + description: >- + The coordinate reference systems in which geometries may be + retrieved. Coordinate reference systems are identified by a URI. The + first coordinate reference system is the coordinate reference system + that is used by default. This is always + "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e. WGS84 + longitude/latitude. + type: array + items: + type: string + default: + - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + stac_version: + type: string + example: 0.7.0 + id: + description: 'identifier of the collection used, for example, in URIs' + type: string + example: buildings + keywords: + title: Keywords + type: array + items: + type: string + example: + - buildings + - properties + - constructions + version: + title: Collection Version + type: string + example: 2018Q3 + license: + title: Collection License Name + type: string + example: Apache-2.0 + providers: + type: array + items: + properties: + name: + title: Organization name + type: string + example: Big Building Corp + description: + title: Provider description + type: string + example: No further processing applied. + roles: + title: Organization roles + type: array + items: + type: string + enum: + - producer + - licensor + - processor + - host + example: + - producer + - licensor + url: + title: Homepage + description: >- + Homepage on which the provider describes the dataset and + publishes contact information. + type: string + format: url + example: 'http://www.big-building.com' + extent: + type: object + properties: + crs: + description: >- + Coordinate reference system of the coordinates in the spatial extent + (property `spatial`). In the Core, only WGS84 longitude/latitude is + supported. Extensions may support additional coordinate reference + systems. + type: string + enum: + - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + spatial: + description: >- + West, south, east, north edges of the spatial extent. The minimum + and maximum values apply to the coordinate reference system WGS84 + longitude/latitude that is supported in the Core. If, for example, a + projected coordinate reference system is used, the minimum and + maximum values need to be adjusted. + type: array + minItems: 4 + maxItems: 6 + items: + type: number + example: + - -180 + - -90 + - 180 + - 90 + trs: + description: >- + Temporal reference system of the coordinates in the temporal extent + (property `temporal`). In the Core, only the Gregorian calendar is + supported. Extensions may support additional temporal reference + systems. + type: string + enum: + - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' + default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' + temporal: + description: Begin and end times of the temporal extent. + type: array + minItems: 2 + maxItems: 2 + items: + type: string + format: dateTime + example: + - '2011-11-11T12:22:11Z' + - '2012-11-24T12:32:43Z' + exception: type: object required: - code @@ -510,16 +680,13 @@ components: type: string description: type: string - links: - type: array - items: - $ref: '#/components/schemas/link' link: + title: Link + description: A generic link. type: object required: - href - rel - additionalProperties: true properties: href: type: string @@ -546,6 +713,9 @@ components: limit: type: number example: 10 + - $ref: '#/components/schemas/queryFilter' + - $ref: '#/components/schemas/sortFilter' + - $ref: '#/components/schemas/fieldsFilter' bbox: description: | Only features that have a geometry that intersects the bounding box are @@ -602,32 +772,22 @@ components: description: Only returns items that intersect with the provided polygon. properties: intersects: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' time: type: string description: > Either a date-time or a period string that adheres to RFC 3339. Examples: - - * A date-time: "2018-02-12T23:20:50Z" - - * A period: - + * A date-time: "2018-02-12T23:20:50Z" * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or - "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - Only features that have a temporal property that intersects the value of - `time` are selected. - If a feature has multiple temporal properties, it is the decision of the - server whether only a single temporal property is used to determine the - extent or all relevant temporal properties. example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' catalogDefinition: @@ -637,11 +797,10 @@ components: - id - description - links - additionalProperties: true properties: stac_version: type: string - example: 0.6.2 + example: 0.7.0 id: type: string example: naip @@ -652,7 +811,31 @@ components: type: string example: Catalog of NAIP Imagery. links: - $ref: '#/components/schemas/links' + type: array + items: + anyOf: + - $ref: '#/components/schemas/link' + - title: Link to search endpoint + description: >- + Link the search endpoint, which is **required** to be + specified if the API implements `/stac/search`. + type: object + required: + - href + - rel + properties: + href: + type: string + format: url + example: 'http://www.cool-sat.com/stac/search' + rel: + type: string + enum: + - search + type: + type: string + title: + type: string itemCollection: type: object required: @@ -685,13 +868,15 @@ components: bbox: $ref: '#/components/schemas/bbox' geometry: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' type: $ref: '#/components/schemas/itemType' properties: $ref: '#/components/schemas/itemProperties' links: - $ref: '#/components/schemas/links' + type: array + items: + $ref: '#/components/schemas/link' assets: $ref: '#/components/schemas/itemAssets' example: @@ -782,266 +967,140 @@ components: - rel: next href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk - root: + queryFilter: type: object - required: - - links + description: Allows users to query properties for specific values properties: - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/' - rel: self - type: application/json - title: this document - - href: 'http://data.example.org/api' - rel: service - type: application/openapi+json;version=3.0 - title: the API definition - - href: 'http://data.example.org/conformance' - rel: conformance - type: application/json - title: WFS 3.0 conformance classes implemented by this server - - href: 'http://data.example.org/collections' - rel: data - type: application/json - title: Metadata about the feature collections - req-classes: + query: + $ref: '#/components/schemas/query' + query: type: object - required: - - conformsTo + description: Define which properties to query and the operatations to apply + additionalProperties: + $ref: '#/components/schemas/queryProp' + example: + 'eo:cloud_cover': + lt: 50 + providers: Planet + published: + date: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' + 'pl:item_type': + startsWith: PSScene + queryProp: + description: Apply query operations to a specific property + anyOf: + - description: >- + if the object doesn't contain any of the operators, it is equivalent + to using the equals operator + - type: object + description: Match using an operator + properties: + eq: + description: >- + Find items with a property that is equal to the specified value. + For strings, a case-insensitive comparison must be performed. + neq: + description: >- + Find items that *don't* contain the specified value. For + strings, a case-insensitive comparison must be performed. + gt: + type: number + description: >- + Find items with a property value greater than the specified + value. + lt: + type: number + description: Find items with a property value less than the specified value. + gte: + type: number + description: >- + Find items with a property value greater than or equal the + specified value. + lte: + type: number + description: >- + Find items with a property value greater than or equal the + specified value. + startsWith: + type: string + description: >- + Find items with a property that begins with the specified + string. A case-insensitive comparison must be performed. + endsWith: + type: string + description: >- + Find items with a property that ends with the specified string. + A case-insensitive comparison must be performed. + contains: + type: string + description: >- + Find items with a property that contains with the specified + string. A case-insensitive comparison must be performed. + time: + $ref: '#/components/schemas/time' + sortFilter: + type: object + description: Sort the results properties: - conformsTo: - type: array - items: + sort: + $ref: '#/components/schemas/sort' + sort: + type: array + description: | + An array of objects containing a property name and sort direction. + minItems: 1 + items: + type: object + required: + - field + properties: + field: type: string - example: - - 'http://www.opengis.net/spec/wfs-1/3.0/req/core' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/oas30' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/html' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/geojson' - content: + direction: + type: string + default: asc + enum: + - asc + - desc + example: + - field: 'eo:cloud_cover' + - field: providers + direction: desc + fieldsFilter: type: object - required: - - links - - collections + description: Determines the shape of the features in the response properties: - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/collections.json' - rel: self - type: application/json - title: this document - - href: 'http://data.example.org/collections.html' - rel: alternate - type: text/html - title: this document as HTML - - href: 'http://schemas.example.org/1.0/foobar.xsd' - rel: describedBy - type: application/xml - title: XML schema for Acme Corporation data - collections: - type: array - items: - $ref: '#/components/schemas/collectionInfo' - collectionInfo: + fields: + $ref: '#/components/schemas/fields' + fields: + description: | + The include and exclude members specify an array of + property names that are either included or excluded + from the result, respectively. If both include and + exclude are specified, include takes precedence. + Values should include the full JSON path of the property. type: object - required: - - name - - links - - stac_version - - id - - description - - license - - extent properties: - name: - description: 'identifier of the collection used, for example, in URIs' - type: string - example: buildings - title: - description: human readable title of the collection - type: string - example: Buildings - description: - description: a description of the features in the collection - type: string - example: Buildings in the city of Bonn. - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/collections/buildings/items' - rel: item - type: application/geo+json - title: Buildings - - href: 'http://example.org/concepts/building.html' - rel: describedBy - type: text/html - title: Feature catalogue for buildings - extent: - $ref: '#/components/schemas/extent' - crs: - description: >- - The coordinate reference systems in which geometries may be - retrieved. Coordinate reference systems are identified by a URI. The - first coordinate reference system is the coordinate reference system - that is used by default. This is always - "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e. WGS84 - longitude/latitude. - type: array - items: - type: string - default: - - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - stac_version: - type: string - example: 0.6.2 - id: - description: 'identifier of the collection used, for example, in URIs' - type: string - example: buildings - keywords: - title: Keywords + include: type: array items: type: string - example: - - buildings - - properties - - constructions - version: - title: Collection Version - type: string - example: 1 - license: - title: Collection License Name - type: string - example: Apache-2.0 - providers: + exclude: type: array - items: - properties: - name: - title: Organization name - type: string - example: Big Building Corp - description: - title: Provider description - type: string - example: No further processing applied. - roles: - title: Organization roles - type: array - items: - type: string - enum: - - producer - - licensor - - processor - - host - example: - - producer - - licensor - url: - title: Homepage - description: >- - Homepage on which the provider describes the dataset and - publishes contact information. - type: string - format: url - example: 'http://www.big-building.com' - extent: - type: object - properties: - crs: - description: >- - Coordinate reference system of the coordinates in the spatial extent - (property `spatial`). In the Core, only WGS84 longitude/latitude is - supported. Extensions may support additional coordinate reference - systems. - type: string - enum: - - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - spatial: - description: >- - West, south, east, north edges of the spatial extent. The minimum - and maximum values apply to the coordinate reference system WGS84 - longitude/latitude that is supported in the Core. If, for example, a - projected coordinate reference system is used, the minimum and - maximum values need to be adjusted. - type: array - minItems: 4 - maxItems: 6 - items: - type: number - example: - - -180 - - -90 - - 180 - - 90 - trs: - description: >- - Temporal reference system of the coordinates in the temporal extent - (property `temporal`). In the Core, only the Gregorian calendar is - supported. Extensions may support additional temporal reference - systems. - type: string - enum: - - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' - default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' - temporal: - description: Begin and end times of the temporal extent. - type: array - minItems: 2 - maxItems: 2 items: type: string - format: dateTime - example: - - '2011-11-11T12:22:11Z' - - '2012-11-24T12:32:43Z' - partialItem: - type: object - properties: - id: - $ref: '#/components/schemas/itemId' - bbox: - $ref: '#/components/schemas/bbox' - geometry: - $ref: 'http://geojson.org/schema/Geometry.json' - type: - $ref: '#/components/schemas/itemType' - properties: - $ref: '#/components/schemas/partialItemProperties' - links: - $ref: '#/components/schemas/links' - assets: - $ref: '#/components/schemas/itemAssets' example: - assets: - analytic: - title: 1-Band Analytic - href: >- - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic-1.tif - partialItemProperties: - type: object - description: allows for partial collections of metadata fields - additionalProperties: true - properties: - datetime: - $ref: '#/components/schemas/time' + include: + - id + - 'properties.eo:cloud_cover' + exclude: + - geometry + - properties.datetime +servers: + - url: 'http://dev.cool-sat.com' + description: Development server + - url: 'http://www.cool-sat.com' + description: Production server tags: - name: STAC description: Extension to WFS3 Core to support STAC metadata model and search API - - name: Extensions - description: >- - STAC-specific operations to add, remove, and edit items within WFS3 - collections. diff --git a/api-spec/STAC-query.yaml b/api-spec/STAC-query.yaml deleted file mode 100644 index 37d8360da..000000000 --- a/api-spec/STAC-query.yaml +++ /dev/null @@ -1,636 +0,0 @@ -openapi: 3.0.1 -info: - title: The SpatioTemporal Asset Catalog API (standalone) - version: 0.6.2 - description: >- - This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API - specification. Any service that implements this endpoint to allow search of - spatiotemporal assets can be considered a STAC API. The endpoint is also - available as an OpenAPI fragment that can be integrated with other OpenAPI - definitions, and is designed to slot seamlessly into a WFS 3 API definition. - contact: - name: Cool Sat Corp - email: info@cool-sat.com - url: 'http://cool-sat.com/contact/' - license: - name: Apache License 2.0 - url: 'http://www.apache.org/licenses/LICENSE-2.0' -servers: - - url: 'http://dev.cool-sat.com/' - description: Development server - - url: 'http://www.cool-sat.com' - description: Production server -paths: - /stac: - get: - summary: Return the root catalog or collection. - description: >- - Returns the root STAC Catalog or STAC Collection that is the entry point - for users to browse with STAC Browser or for search engines to crawl. - This can either return a single STAC Collection or more commonly a STAC - catalog that usually lists sub-catalogs of STAC Collections, i.e. a - simple catalog that lists all collections available through the API. - tags: - - STAC - responses: - '200': - description: A catalog json definition. Used as an entry point for a crawler. - content: - application/json: - schema: - $ref: '#/components/schemas/catalogDefinition' - /stac/search: - get: - summary: Search STAC items by simple filtering. - description: >- - Retrieve Items matching filters. Intended as a shorthand API for simple - queries. This method is optional. - operationId: getSearchSTAC - tags: - - STAC - parameters: - - $ref: '#/components/parameters/bbox' - - $ref: '#/components/parameters/time' - - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/query' - - $ref: '#/components/parameters/sort' - - $ref: '#/components/parameters/fields' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - post: - summary: Search STAC items by full-featured filtering. - description: >- - retrieve items matching filters. Intended as the standard, full-featured - query API. This method is mandatory. - operationId: postSearchSTAC - tags: - - STAC - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/searchBody' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string -components: - parameters: - limit: - name: limit - in: query - description: | - The optional limit parameter limits the number of items that are - presented in the response document. - - Only items are counted that are on the first level of the collection in - the response document. Nested objects contained within the explicitly - requested items shall not be counted. - - * Minimum = 1 - * Maximum = 10000 - * Default = 10 - required: false - schema: - type: integer - minimum: 1 - maximum: 10000 - default: 10 - style: form - explode: false - bbox: - name: bbox - in: query - description: | - Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - - - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - required: false - schema: - type: array - minItems: 4 - maxItems: 6 - items: - type: number - style: form - explode: false - time: - name: time - in: query - description: > - Either a date-time or a period string that adheres to RFC3339. Examples: - - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - - Only features that have a temporal property that intersects the value - of `time` are selected. If a feature has multiple temporal properties, it - is the decision of the server whether only a single temporal property is - used to determine the extent or all relevant temporal properties. - required: false - schema: - type: string - style: form - explode: false - collectionId: - name: collectionId - in: path - required: true - description: Identifier (name) of a specific collection - schema: - type: string - featureId: - name: featureId - in: path - description: Local identifier of a specific feature - required: true - schema: - type: string - query: - name: query - in: query - description: >- - query for properties in items. Use the JSON form of the queryFilter used - in POST. - required: false - schema: - type: string - sort: - name: sort - in: query - description: Allows sorting results by the specified properties - required: false - schema: - $ref: '#/components/schemas/sort' - fields: - name: fields - in: query - description: Determines the shape of the features in the response - required: false - schema: - $ref: '#/components/schemas/fields' - style: form - explode: false - schemas: - exception: - type: object - required: - - code - properties: - code: - type: string - description: - type: string - links: - type: array - items: - $ref: '#/components/schemas/link' - link: - type: object - required: - - href - - rel - additionalProperties: true - properties: - href: - type: string - format: url - example: 'http://www.geoserver.example/stac/naip/child/catalog.json' - rel: - type: string - example: child - type: - type: string - example: application/json - title: - type: string - example: NAIP Child Catalog - searchBody: - description: The search criteria - type: object - allOf: - - $ref: '#/components/schemas/bboxFilter' - - $ref: '#/components/schemas/timeFilter' - - $ref: '#/components/schemas/intersectsFilter' - - type: object - properties: - limit: - type: number - example: 10 - - $ref: '#/components/schemas/queryFilter' - - $ref: '#/components/schemas/sortFilter' - - $ref: '#/components/schemas/fieldsFilter' - bbox: - description: | - Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - - - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - type: array - minItems: 4 - maxItems: 6 - items: - type: number - example: - - -110 - - 39.5 - - -105 - - 40.5 - bboxFilter: - type: object - description: Only return items that intersect the provided bounding box. - properties: - bbox: - $ref: '#/components/schemas/bbox' - timeFilter: - description: An object representing a time based filter. - type: object - properties: - time: - $ref: '#/components/schemas/time' - intersectsFilter: - type: object - description: Only returns items that intersect with the provided polygon. - properties: - intersects: - $ref: 'http://geojson.org/schema/Geometry.json' - time: - type: string - description: > - Either a date-time or a period string that adheres to RFC 3339. - Examples: - - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - - Only features that have a temporal property that intersects the value of - `time` are selected. - - - If a feature has multiple temporal properties, it is the decision of the - server whether only a single temporal property is used to determine the - extent or all relevant temporal properties. - example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' - catalogDefinition: - type: object - required: - - stac_version - - id - - description - - links - additionalProperties: true - properties: - stac_version: - type: string - example: 0.6.2 - id: - type: string - example: naip - title: - type: string - example: NAIP Imagery - description: - type: string - example: Catalog of NAIP Imagery. - links: - $ref: '#/components/schemas/links' - itemCollection: - type: object - required: - - features - - type - properties: - type: - type: string - enum: - - FeatureCollection - features: - type: array - items: - $ref: '#/components/schemas/item' - links: - $ref: '#/components/schemas/itemCollectionLinks' - item: - type: object - required: - - id - - type - - geometry - - bbox - - links - - properties - - assets - properties: - id: - $ref: '#/components/schemas/itemId' - bbox: - $ref: '#/components/schemas/bbox' - geometry: - $ref: 'http://geojson.org/schema/Geometry.json' - type: - $ref: '#/components/schemas/itemType' - properties: - $ref: '#/components/schemas/itemProperties' - links: - $ref: '#/components/schemas/links' - assets: - $ref: '#/components/schemas/itemAssets' - example: - type: Feature - id: CS3-20160503_132130_04 - bbox: - - -122.59750209 - - 37.48803556 - - -122.2880486 - - 37.613537207 - geometry: - type: Polygon - coordinates: - - - - -122.308150179 - - 37.488035566 - - - -122.597502109 - - 37.538869539 - - - -122.576687533 - - 37.613537207 - - - -122.2880486 - - 37.562818007 - - - -122.308150179 - - 37.488035566 - properties: - datetime: '2016-05-03T13:21:30.040Z' - links: - - rel: self - href: >- - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json - assets: - analytic: - title: 4-Band Analytic - href: >- - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif - thumbnail: - title: Thumbnail - href: >- - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png - type: image/png - itemId: - type: string - example: path/to/example.tif - description: 'Provider identifier, a unique ID, potentially a link to a file.' - itemType: - type: string - description: The GeoJSON type - enum: - - Feature - itemAssets: - type: object - additionalProperties: - type: object - required: - - href - properties: - href: - type: string - format: url - description: Link to the asset object - example: >- - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png - title: - type: string - description: Displayed title - example: Thumbnail - type: - type: string - description: Media type of the asset - example: image/png - itemProperties: - type: object - required: - - datetime - description: provides the core metatdata fields plus extensions - properties: - datetime: - $ref: '#/components/schemas/time' - additionalProperties: - description: Any additional properties added in via extensions. - itemCollectionLinks: - type: array - description: >- - An array of links. Can be used for pagination, e.g. by providing a link - with the `next` relation type. - items: - $ref: '#/components/schemas/link' - example: - - rel: next - href: >- - http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk - queryFilter: - type: object - description: Allows users to query properties for specific values - properties: - query: - $ref: '#/components/schemas/query' - query: - type: object - description: Define which properties to query and the operatations to apply - additionalProperties: - $ref: '#/components/schemas/queryProp' - example: - 'eo:cloud_cover': - lt: 50 - providers: Planet - published: - date: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' - 'pl:item_type': - startsWith: PSScene - queryProp: - description: Apply query operations to a specific property - anyOf: - - description: >- - if the object doesn't contain any of the operators, it is equivalent - to using the equals operator - - type: object - description: Match using an operator - properties: - eq: - description: >- - Find items with a property that is equal to the specified value. - For strings, a case-insensitive comparison must be performed. - neq: - description: >- - Find items that *don't* contain the specified value. For - strings, a case-insensitive comparison must be performed. - gt: - type: number - description: >- - Find items with a property value greater than the specified - value. - lt: - type: number - description: Find items with a property value less than the specified value. - gte: - type: number - description: >- - Find items with a property value greater than or equal the - specified value. - lte: - type: number - description: >- - Find items with a property value greater than or equal the - specified value. - startsWith: - type: string - description: >- - Find items with a property that begins with the specified - string. A case-insensitive comparison must be performed. - endsWith: - type: string - description: >- - Find items with a property that ends with the specified string. - A case-insensitive comparison must be performed. - contains: - type: string - description: >- - Find items with a property that contains with the specified - string. A case-insensitive comparison must be performed. - time: - $ref: '#/components/schemas/time' - sortFilter: - type: object - description: Sort the results - properties: - sort: - $ref: '#/components/schemas/sort' - sort: - type: array - description: | - An array of objects containing a property name and sort direction. - minItems: 1 - items: - type: object - required: - - field - properties: - field: - type: string - direction: - type: string - default: asc - enum: - - asc - - desc - example: - - field: 'eo:cloud_cover' - - field: providers - direction: desc - fieldsFilter: - type: object - description: Determines the shape of the features in the response - properties: - fields: - $ref: '#/components/schemas/fields' - fields: - description: > - The geometry member determines whether the geometry is populated or is - null. The - - include and exclude members specify an array of property names that are - either - - included or excluded from the result, respectively. If both include and - exclude - - are specified, include takes precedence. - type: object - properties: - geometry: - type: boolean - include: - type: array - items: - type: string - exclude: - type: array - items: - type: string -tags: - - name: STAC - description: Extension to WFS3 Core to support STAC metadata model and search API diff --git a/api-spec/WFS3core+STAC.yaml b/api-spec/STAC.yaml similarity index 87% rename from api-spec/WFS3core+STAC.yaml rename to api-spec/STAC.yaml index 97f83eba2..72c53a97b 100644 --- a/api-spec/WFS3core+STAC.yaml +++ b/api-spec/STAC.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: - title: The SpatioTemporal Asset Catalog API + WFS3 - version: 0.6.2 + title: The SpatioTemporal Asset Catalog API + version: 0.7.0 description: >- This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API specification. Any service that implements this endpoint to allow search of @@ -9,100 +9,12 @@ info: available as an OpenAPI fragment that can be integrated with other OpenAPI definitions, and is designed to slot seamlessly into a WFS 3 API definition. contact: - name: Cool Sat Corp - email: info@cool-sat.com - url: 'http://cool-sat.com/contact/' + name: STAC Specification + url: 'http://stacspec.org' license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' -servers: - - url: 'http://dev.cool-sat.com/' - description: Development server - - url: 'http://www.cool-sat.com' - description: Production server paths: - /stac: - get: - summary: Return the root catalog or collection. - description: >- - Returns the root STAC Catalog or STAC Collection that is the entry point - for users to browse with STAC Browser or for search engines to crawl. - This can either return a single STAC Collection or more commonly a STAC - catalog that usually lists sub-catalogs of STAC Collections, i.e. a - simple catalog that lists all collections available through the API. - tags: - - STAC - responses: - '200': - description: A catalog json definition. Used as an entry point for a crawler. - content: - application/json: - schema: - $ref: '#/components/schemas/catalogDefinition' - /stac/search: - get: - summary: Search STAC items by simple filtering. - description: >- - Retrieve Items matching filters. Intended as a shorthand API for simple - queries. This method is optional. - operationId: getSearchSTAC - tags: - - STAC - parameters: - - $ref: '#/components/parameters/bbox' - - $ref: '#/components/parameters/time' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - post: - summary: Search STAC items by full-featured filtering. - description: >- - retrieve items matching filters. Intended as the standard, full-featured - query API. This method is mandatory. - operationId: postSearchSTAC - tags: - - STAC - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/searchBody' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string /: get: summary: landing page of this API @@ -221,7 +133,7 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/FeatureCollection.json' + $ref: 'https://stacspec.org/assets/FeatureCollection.json' text/html: schema: type: string @@ -249,7 +161,102 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/Feature.json' + $ref: 'https://stacspec.org/assets/Feature.json' + text/html: + schema: + type: string + default: + description: An error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/exception' + text/html: + schema: + type: string + /stac: + get: + summary: Return the root catalog or collection. + description: >- + Returns the root STAC Catalog or STAC Collection that is the entry point + for users to browse with STAC Browser or for search engines to crawl. + This can either return a single STAC Collection or more commonly a STAC + catalog that usually lists sub-catalogs of STAC Collections, i.e. a + simple catalog that lists all collections available through the API. + tags: + - STAC + responses: + '200': + description: A catalog JSON definition. Used as an entry point for a crawler. + content: + application/json: + schema: + $ref: '#/components/schemas/catalogDefinition' + /stac/search: + get: + summary: Search STAC items with simple filtering. + description: >- + Retrieve Items matching filters. Intended as a shorthand API for simple + queries. + + + This method is optional, but you MUST implement `POST /stac/search` if + you want to implement this method. + operationId: getSearchSTAC + tags: + - STAC + parameters: + - $ref: '#/components/parameters/bbox' + - $ref: '#/components/parameters/time' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/ids' + - $ref: '#/components/parameters/collections' + responses: + '200': + description: A feature collection. + content: + application/geo+json: + schema: + $ref: '#/components/schemas/itemCollection' + text/html: + schema: + type: string + default: + description: An error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/exception' + text/html: + schema: + type: string + post: + summary: Search STAC items with full-featured filtering. + description: >- + retrieve items matching filters. Intended as the standard, full-featured + query API. + + + This method is mandatory to implement if `GET /stac/search` is + implemented. If this endpoint is implemented on a server, it is required + to add a link with `rel` set to `search` to the `links` array in `GET + /stac` that refers to this endpoint. + operationId: postSearchSTAC + tags: + - STAC + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/searchBody' + responses: + '200': + description: A feature collection. + content: + application/geo+json: + schema: + $ref: '#/components/schemas/itemCollection' text/html: schema: type: string @@ -264,6 +271,20 @@ paths: type: string components: parameters: + collectionId: + name: collectionId + in: path + required: true + description: Identifier (name) of a specific collection + schema: + type: string + featureId: + name: featureId + in: path + description: Local identifier of a specific feature + required: true + schema: + type: string limit: name: limit in: query @@ -286,6 +307,56 @@ components: default: 10 style: form explode: false + page: + name: page + in: query + description: | + The optional page parameter returns the specified page of results + (with each page having size=limit). + + * Minimum = 1 + * Default = 1 + required: false + schema: + type: integer + minimum: 1 + default: 1 + style: form + explode: false + ids: + name: ids + in: query + description: > + The optional ids parameter returns a FeatureCollection of all matching + ids. + + If provided all other parameters that further restrict the number of + search results (except `page` and `limit`) will be ignored. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false + collections: + name: collections + in: query + description: > + The collections search parameter is a list of of collection IDs for + Items to match. + + Only items that are included in one of these collections will be + returned, otherwise + + all collections will be searched. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false bbox: name: bbox in: query @@ -332,11 +403,12 @@ components: description: > Either a date-time or a period string that adheres to RFC3339. Examples: - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" + * A date-time: "2018-02-12T23:20:50Z" * A period: + "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or + "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - Only features that have a temporal property that intersects the value - of `time` are selected. If a feature has multiple temporal properties, it + Only features that have a temporal property that intersects the value of + `time` are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. required: false @@ -344,21 +416,233 @@ components: type: string style: form explode: false - collectionId: - name: collectionId - in: path - required: true - description: Identifier (name) of a specific collection - schema: - type: string - featureId: - name: featureId - in: path - description: Local identifier of a specific feature - required: true - schema: - type: string schemas: + root: + type: object + required: + - links + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/' + rel: self + type: application/json + title: this document + - href: 'http://data.example.org/api' + rel: service + type: application/openapi+json;version=3.0 + title: the API definition + - href: 'http://data.example.org/conformance' + rel: conformance + type: application/json + title: WFS 3.0 conformance classes implemented by this server + - href: 'http://data.example.org/collections' + rel: data + type: application/json + title: Metadata about the feature collections + req-classes: + type: object + required: + - conformsTo + properties: + conformsTo: + type: array + items: + type: string + example: + - 'http://www.opengis.net/spec/wfs-1/3.0/req/core' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/oas30' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/html' + - 'http://www.opengis.net/spec/wfs-1/3.0/req/geojson' + content: + type: object + required: + - links + - collections + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/collections.json' + rel: self + type: application/json + title: this document + - href: 'http://data.example.org/collections.html' + rel: alternate + type: text/html + title: this document as HTML + - href: 'http://schemas.example.org/1.0/foobar.xsd' + rel: describedBy + type: application/xml + title: XML schema for Acme Corporation data + collections: + type: array + items: + $ref: '#/components/schemas/collectionInfo' + collectionInfo: + type: object + required: + - name + - links + - stac_version + - id + - description + - license + - extent + properties: + name: + description: 'identifier of the collection used, for example, in URIs' + type: string + example: buildings + title: + description: human readable title of the collection + type: string + example: Buildings + description: + description: a description of the features in the collection + type: string + example: Buildings in the city of Bonn. + links: + type: array + items: + $ref: '#/components/schemas/link' + example: + - href: 'http://data.example.org/collections/buildings/items' + rel: item + type: application/geo+json + title: Buildings + - href: 'http://example.org/concepts/building.html' + rel: describedBy + type: text/html + title: Feature catalogue for buildings + extent: + $ref: '#/components/schemas/extent' + crs: + description: >- + The coordinate reference systems in which geometries may be + retrieved. Coordinate reference systems are identified by a URI. The + first coordinate reference system is the coordinate reference system + that is used by default. This is always + "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e. WGS84 + longitude/latitude. + type: array + items: + type: string + default: + - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + stac_version: + type: string + example: 0.7.0 + id: + description: 'identifier of the collection used, for example, in URIs' + type: string + example: buildings + keywords: + title: Keywords + type: array + items: + type: string + example: + - buildings + - properties + - constructions + version: + title: Collection Version + type: string + example: 2018Q3 + license: + title: Collection License Name + type: string + example: Apache-2.0 + providers: + type: array + items: + properties: + name: + title: Organization name + type: string + example: Big Building Corp + description: + title: Provider description + type: string + example: No further processing applied. + roles: + title: Organization roles + type: array + items: + type: string + enum: + - producer + - licensor + - processor + - host + example: + - producer + - licensor + url: + title: Homepage + description: >- + Homepage on which the provider describes the dataset and + publishes contact information. + type: string + format: url + example: 'http://www.big-building.com' + extent: + type: object + properties: + crs: + description: >- + Coordinate reference system of the coordinates in the spatial extent + (property `spatial`). In the Core, only WGS84 longitude/latitude is + supported. Extensions may support additional coordinate reference + systems. + type: string + enum: + - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' + spatial: + description: >- + West, south, east, north edges of the spatial extent. The minimum + and maximum values apply to the coordinate reference system WGS84 + longitude/latitude that is supported in the Core. If, for example, a + projected coordinate reference system is used, the minimum and + maximum values need to be adjusted. + type: array + minItems: 4 + maxItems: 6 + items: + type: number + example: + - -180 + - -90 + - 180 + - 90 + trs: + description: >- + Temporal reference system of the coordinates in the temporal extent + (property `temporal`). In the Core, only the Gregorian calendar is + supported. Extensions may support additional temporal reference + systems. + type: string + enum: + - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' + default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' + temporal: + description: Begin and end times of the temporal extent. + type: array + minItems: 2 + maxItems: 2 + items: + type: string + format: dateTime + example: + - '2011-11-11T12:22:11Z' + - '2012-11-24T12:32:43Z' exception: type: object required: @@ -368,16 +652,13 @@ components: type: string description: type: string - links: - type: array - items: - $ref: '#/components/schemas/link' link: + title: Link + description: A generic link. type: object required: - href - rel - additionalProperties: true properties: href: type: string @@ -460,15 +741,16 @@ components: description: Only returns items that intersect with the provided polygon. properties: intersects: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' time: type: string description: > Either a date-time or a period string that adheres to RFC 3339. Examples: - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" + * A date-time: "2018-02-12T23:20:50Z" * A period: + "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or + "2018-02-12T00:00:00Z/P1M6DT12H31M12S" Only features that have a temporal property that intersects the value of `time` are selected. @@ -484,11 +766,10 @@ components: - id - description - links - additionalProperties: true properties: stac_version: type: string - example: 0.6.2 + example: 0.7.0 id: type: string example: naip @@ -499,7 +780,31 @@ components: type: string example: Catalog of NAIP Imagery. links: - $ref: '#/components/schemas/links' + type: array + items: + anyOf: + - $ref: '#/components/schemas/link' + - title: Link to search endpoint + description: >- + Link the search endpoint, which is **required** to be + specified if the API implements `/stac/search`. + type: object + required: + - href + - rel + properties: + href: + type: string + format: url + example: 'http://www.cool-sat.com/stac/search' + rel: + type: string + enum: + - search + type: + type: string + title: + type: string itemCollection: type: object required: @@ -532,13 +837,15 @@ components: bbox: $ref: '#/components/schemas/bbox' geometry: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' type: $ref: '#/components/schemas/itemType' properties: $ref: '#/components/schemas/itemProperties' links: - $ref: '#/components/schemas/links' + type: array + items: + $ref: '#/components/schemas/link' assets: $ref: '#/components/schemas/itemAssets' example: @@ -629,232 +936,11 @@ components: - rel: next href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk - root: - type: object - required: - - links - properties: - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/' - rel: self - type: application/json - title: this document - - href: 'http://data.example.org/api' - rel: service - type: application/openapi+json;version=3.0 - title: the API definition - - href: 'http://data.example.org/conformance' - rel: conformance - type: application/json - title: WFS 3.0 conformance classes implemented by this server - - href: 'http://data.example.org/collections' - rel: data - type: application/json - title: Metadata about the feature collections - req-classes: - type: object - required: - - conformsTo - properties: - conformsTo: - type: array - items: - type: string - example: - - 'http://www.opengis.net/spec/wfs-1/3.0/req/core' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/oas30' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/html' - - 'http://www.opengis.net/spec/wfs-1/3.0/req/geojson' - content: - type: object - required: - - links - - collections - properties: - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/collections.json' - rel: self - type: application/json - title: this document - - href: 'http://data.example.org/collections.html' - rel: alternate - type: text/html - title: this document as HTML - - href: 'http://schemas.example.org/1.0/foobar.xsd' - rel: describedBy - type: application/xml - title: XML schema for Acme Corporation data - collections: - type: array - items: - $ref: '#/components/schemas/collectionInfo' - collectionInfo: - type: object - required: - - name - - links - - stac_version - - id - - description - - license - - extent - properties: - name: - description: 'identifier of the collection used, for example, in URIs' - type: string - example: buildings - title: - description: human readable title of the collection - type: string - example: Buildings - description: - description: a description of the features in the collection - type: string - example: Buildings in the city of Bonn. - links: - type: array - items: - $ref: '#/components/schemas/link' - example: - - href: 'http://data.example.org/collections/buildings/items' - rel: item - type: application/geo+json - title: Buildings - - href: 'http://example.org/concepts/building.html' - rel: describedBy - type: text/html - title: Feature catalogue for buildings - extent: - $ref: '#/components/schemas/extent' - crs: - description: >- - The coordinate reference systems in which geometries may be - retrieved. Coordinate reference systems are identified by a URI. The - first coordinate reference system is the coordinate reference system - that is used by default. This is always - "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e. WGS84 - longitude/latitude. - type: array - items: - type: string - default: - - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - stac_version: - type: string - example: 0.6.2 - id: - description: 'identifier of the collection used, for example, in URIs' - type: string - example: buildings - keywords: - title: Keywords - type: array - items: - type: string - example: - - buildings - - properties - - constructions - version: - title: Collection Version - type: string - example: 1 - license: - title: Collection License Name - type: string - example: Apache-2.0 - providers: - type: array - items: - properties: - name: - title: Organization name - type: string - example: Big Building Corp - description: - title: Provider description - type: string - example: No further processing applied. - roles: - title: Organization roles - type: array - items: - type: string - enum: - - producer - - licensor - - processor - - host - example: - - producer - - licensor - url: - title: Homepage - description: >- - Homepage on which the provider describes the dataset and - publishes contact information. - type: string - format: url - example: 'http://www.big-building.com' - extent: - type: object - properties: - crs: - description: >- - Coordinate reference system of the coordinates in the spatial extent - (property `spatial`). In the Core, only WGS84 longitude/latitude is - supported. Extensions may support additional coordinate reference - systems. - type: string - enum: - - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' - spatial: - description: >- - West, south, east, north edges of the spatial extent. The minimum - and maximum values apply to the coordinate reference system WGS84 - longitude/latitude that is supported in the Core. If, for example, a - projected coordinate reference system is used, the minimum and - maximum values need to be adjusted. - type: array - minItems: 4 - maxItems: 6 - items: - type: number - example: - - -180 - - -90 - - 180 - - 90 - trs: - description: >- - Temporal reference system of the coordinates in the temporal extent - (property `temporal`). In the Core, only the Gregorian calendar is - supported. Extensions may support additional temporal reference - systems. - type: string - enum: - - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' - default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian' - temporal: - description: Begin and end times of the temporal extent. - type: array - minItems: 2 - maxItems: 2 - items: - type: string - format: dateTime - example: - - '2011-11-11T12:22:11Z' - - '2012-11-24T12:32:43Z' +servers: + - url: 'http://dev.cool-sat.com' + description: Development server + - url: 'http://www.cool-sat.com' + description: Production server tags: - name: STAC description: Extension to WFS3 Core to support STAC metadata model and search API diff --git a/api-spec/api-spec.md b/api-spec/api-spec.md new file mode 100644 index 000000000..07f9fb9e0 --- /dev/null +++ b/api-spec/api-spec.md @@ -0,0 +1,52 @@ +## STAC API Specification + +The Web Feature Service is a standard API that represents collections of geospatial data. The [Web Feature Service 3.0 API](https://github.com/opengeospatial/WFS_FES), currently under development, is the latest iteration of that standard. WFS 3 defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With WFS you can return any `Feature`, which is a geometry plus any number of properties. In the STAC specification an `Item` is a `Feature`, with additional required fields for `datetime` and `assets`. WFS also defines the concept of a Collection, which contains `Feature`s. A STAC `Collection` aligns with (and extends slightly) a WFS 3 `Collection`; it contains `Item`s. + +In WFS 3 Collections are the sets of data that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)), and each describes basic information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data contained. [STAC collections](../collections-spec/README.md) contain this same information, along with other STAC specific fields and thus are compliant with both WFS Collections and STAC Collections and is returned from the `/collections/{collection_id}` endpoint. + +In WFS 3 Features are the individual records within a Collection and are provided in GeoJSON format. [STAC Items](../item-spec/README.md) are analagous to WFS 3 Features, are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. + +### WFS3 Endpoints + +The core WFS 3 endpoints are shown below, with details provided in an [OpenAPI specification document](definitions/WFS3.yaml). + +| Endpoint | Returns | Description | +| ------------ | ------------- | ---------------------- | +| / | JSON | Landing page, links to API capabilities | +| /conformance | JSON | Info about standards the API conforms to | +| /collections | Collections | List of Collections contained in the catalog | +| /collections/{collection_id} | Collection | Returns single Collection JSON | +| /collections/{collection_id}/items | Items | GeoJSON FeatureCollection of Items in Collection | +| /collections/{collection_id}/items/{item_id} | Item | Returns single Item GeoJSON | + +The `/collections/{collection_id}/items` endpoint accepts parameters for filtering the results (also called filters). Searching using POST will accept a JSON object where the top level keys specify which type of filter to apply (e.g., bbox=[...]). Those same key names can be used as query string parameters for the GET request. + +Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If an OR operation is needed, it should be specified through an extension filter. + +### Filter Parameters + +| Parameter | Type | Description | +| ------------ | ------------- | ---------------------- | +| bbox | [number] | Requested bounding box [west, south, east, north] | +| time | string | Single date, date+time, or a range ('/' seperator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) | +| intersects | GeoJSON Feature | Searches items by performing intersection between their geometry and provided GeoJSON Feature | +| page | number | The page number of results. Defaults to 1 | +| limit | number | The maximum number of results to return (page size). Defaults to 10 | +| ids | [string] | Array of Item ids to return. All other filter parameters that further restrict the number of search results (except `page` and `limit`) are ignored | +| collections | [string] | Array of Collection IDs to include in the search for items. Only Items in one of the provided Collections will be searched | + +## STAC Endpoints + +STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. Note that a STAC API does not need to implement WFS 3, in which case it would only support the endpoints given below. See the [OpenAPI specification document](definitions/STAC-standalone.yaml). + +| Endpoint | Returns | Description | +| ------------ | ------------- | ---------------------- | +| /stac | Catalog | Root catalog | +| /stac/search | Items | GeoJSON FeatureCollection of Items found | + +The `/stac` endpoint should function as a complete `Catalog` representation of all the data contained in the API and linked to in some way from root through `Collections` and `Items`. + +The `/stac/search` endpoint is similar to the `items` endpoint in WFS3 in that it accepts parameters for filtering, however it performs the filtering across all collections. The parameters accepted are the same as the Filter Parameters above, however the *[extensions](extensions/README.md)* also provide advanced querying parameters. + +If the `/stac/search` endpoint is implemented, it is **required** to add a link with the `rel` type set to `search` to the `links` array in `GET /stac` that refers to the search endpoint in the `href` property. + diff --git a/api-spec/definitions/STAC-collections.fragment.yaml b/api-spec/definitions/STAC-collections.fragment.yaml deleted file mode 100644 index a5f216fd9..000000000 --- a/api-spec/definitions/STAC-collections.fragment.yaml +++ /dev/null @@ -1,68 +0,0 @@ -components: - schemas: - collectionInfo: - type: object - required: - - stac_version - - id - - description - - license - - extent - properties: - stac_version: - type: string - example: 0.6.2 - id: - description: 'identifier of the collection used, for example, in URIs' - type: string - example: buildings - keywords: - title: Keywords - type: array - items: - type: string - example: - - buildings - - properties - - constructions - version: - title: Collection Version - type: string - example: 2018Q3 - license: - title: Collection License Name - type: string - example: Apache-2.0 - providers: - type: array - items: - properties: - name: - title: Organization name - type: string - example: Big Building Corp - description: - title: Provider description - type: string - example: "No further processing applied." - roles: - title: Organization roles - type: array - items: - type: string - enum: - - producer - - licensor - - processor - - host - example: - - producer - - licensor - url: - title: Homepage - description: >- - Homepage on which the provider describes the dataset and - publishes contact information. - type: string - format: url - example: http://www.big-building.com \ No newline at end of file diff --git a/api-spec/definitions/STAC-query.yaml b/api-spec/definitions/STAC-query.yaml deleted file mode 100644 index bd2468460..000000000 --- a/api-spec/definitions/STAC-query.yaml +++ /dev/null @@ -1 +0,0 @@ -!!files_merge_append ["STAC-standalone.yaml", "extensions/query.fragment.yaml", "extensions/sorting.fragment.yaml", "extensions/fields.fragment.yaml"] \ No newline at end of file diff --git a/api-spec/definitions/STAC-standalone.yaml b/api-spec/definitions/STAC-standalone.yaml deleted file mode 100644 index 1359912bd..000000000 --- a/api-spec/definitions/STAC-standalone.yaml +++ /dev/null @@ -1,467 +0,0 @@ -openapi: 3.0.1 -info: - title: The SpatioTemporal Asset Catalog API (standalone) - version: 0.6.2 - description: >- - This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API - specification. Any service that implements this endpoint to allow search of - spatiotemporal assets can be considered a STAC API. The endpoint is also - available as an OpenAPI fragment that can be integrated with other OpenAPI - definitions, and is designed to slot seamlessly into a WFS 3 API definition. - contact: - name: Cool Sat Corp - email: info@cool-sat.com - url: 'http://cool-sat.com/contact/' - license: - name: Apache License 2.0 - url: 'http://www.apache.org/licenses/LICENSE-2.0' -servers: - - url: 'http://dev.cool-sat.com/' - description: Development server - - url: 'http://www.cool-sat.com' - description: Production server -paths: - /stac: - get: - summary: Return the root catalog or collection. - description: >- - Returns the root STAC Catalog or STAC Collection that is the entry point for users to browse with STAC Browser or for search engines to crawl. - This can either return a single STAC Collection or more commonly a STAC catalog that usually lists sub-catalogs of STAC Collections, i.e. a simple catalog that lists all collections available through the API. - tags: - - STAC - responses: - '200': - description: A catalog JSON definition. Used as an entry point for a crawler. - content: - application/json: - schema: - $ref: '#/components/schemas/catalogDefinition' - /stac/search: - get: - summary: Search STAC items by simple filtering. - description: >- - Retrieve Items matching filters. - Intended as a shorthand API for simple queries. This method is optional. - operationId: getSearchSTAC - tags: - - STAC - parameters: - - $ref: '#/components/parameters/bbox' - - $ref: '#/components/parameters/time' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string - post: - summary: Search STAC items with full-featured filtering. - description: >- - Retrieve items matching filters. - Intended as the standard, full-featured query API. This method is mandatory. - operationId: postSearchSTAC - tags: - - STAC - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/searchBody' - responses: - '200': - description: A feature collection. - content: - application/geo+json: - schema: - $ref: '#/components/schemas/itemCollection' - text/html: - schema: - type: string - default: - description: An error occurred. - content: - application/json: - schema: - $ref: '#/components/schemas/exception' - text/html: - schema: - type: string -components: - parameters: - limit: - name: limit - in: query - description: | - The optional limit parameter limits the number of items that are - presented in the response document. - - Only items are counted that are on the first level of the collection in - the response document. Nested objects contained within the explicitly - requested items shall not be counted. - - * Minimum = 1 - * Maximum = 10000 - * Default = 10 - required: false - schema: - type: integer - minimum: 1 - maximum: 10000 - default: 10 - style: form - explode: false - bbox: - name: bbox - in: query - description: | - Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - - - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - required: false - schema: - type: array - minItems: 4 - maxItems: 6 - items: - type: number - style: form - explode: false - time: - name: time - in: query - description: > - Either a date-time or a period string that adheres to RFC3339. Examples: - - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - - Only features that have a temporal property that intersects the value - of `time` are selected. If a feature has multiple temporal properties, it - is the decision of the server whether only a single temporal property is - used to determine the extent or all relevant temporal properties. - required: false - schema: - type: string - style: form - explode: false - collectionId: - name: collectionId - in: path - required: true - description: Identifier (name) of a specific collection - schema: - type: string - featureId: - name: featureId - in: path - description: Local identifier of a specific feature - required: true - schema: - type: string - schemas: - exception: - type: object - required: - - code - properties: - code: - type: string - description: - type: string - links: - type: array - items: - $ref: '#/components/schemas/link' - link: - type: object - required: - - href - - rel - additionalProperties: true - properties: - href: - type: string - format: url - example: http://www.geoserver.example/stac/naip/child/catalog.json - rel: - type: string - example: child - type: - type: string - example: application/json - title: - type: string - example: "NAIP Child Catalog" - searchBody: - description: The search criteria - type: object - allOf: - - $ref: '#/components/schemas/bboxFilter' - - $ref: '#/components/schemas/timeFilter' - - $ref: '#/components/schemas/intersectsFilter' - - type: object - properties: - limit: - type: number - example: 10 - bbox: - description: | - Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - - - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - type: array - minItems: 4 - maxItems: 6 - items: - type: number - example: - - -110 - - 39.5 - - -105 - - 40.5 - bboxFilter: - type: object - description: Only return items that intersect the provided bounding box. - properties: - bbox: - $ref: '#/components/schemas/bbox' - timeFilter: - description: An object representing a time based filter. - type: object - properties: - time: - $ref: '#/components/schemas/time' - intersectsFilter: - type: object - description: Only returns items that intersect with the provided polygon. - properties: - intersects: - $ref: 'http://geojson.org/schema/Geometry.json' - time: - type: string - description: > - Either a date-time or a period string that adheres to RFC 3339. - Examples: - - - * A date-time: "2018-02-12T23:20:50Z" - * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S" - - Only features that have a temporal property that intersects the value of - `time` are selected. - - If a feature has multiple temporal properties, it is the decision of the - server whether only a single temporal property is used to determine the - extent or all relevant temporal properties. - example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' - catalogDefinition: - type: object - required: - - stac_version - - id - - description - - links - additionalProperties: true - properties: - stac_version: - type: string - example: 0.6.2 - id: - type: string - example: naip - title: - type: string - example: NAIP Imagery - description: - type: string - example: Catalog of NAIP Imagery. - links: - $ref: '#/components/schemas/links' - itemCollection: - type: object - required: - - features - - type - properties: - type: - type: string - enum: - - FeatureCollection - features: - type: array - items: - $ref: '#/components/schemas/item' - links: - $ref: '#/components/schemas/itemCollectionLinks' - item: - type: object - required: - - id - - type - - geometry - - bbox - - links - - properties - - assets - properties: - id: - $ref: '#/components/schemas/itemId' - bbox: - $ref: '#/components/schemas/bbox' - geometry: - $ref: 'http://geojson.org/schema/Geometry.json' - type: - $ref: '#/components/schemas/itemType' - properties: - $ref: '#/components/schemas/itemProperties' - links: - $ref: '#/components/schemas/links' - assets: - $ref: '#/components/schemas/itemAssets' - example: - type: Feature - id: CS3-20160503_132130_04 - bbox: - - -122.59750209 - - 37.48803556 - - -122.2880486 - - 37.613537207 - geometry: - type: Polygon - coordinates: - - - - -122.308150179 - - 37.488035566 - - - -122.597502109 - - 37.538869539 - - - -122.576687533 - - 37.613537207 - - - -122.2880486 - - 37.562818007 - - - -122.308150179 - - 37.488035566 - properties: - datetime: '2016-05-03T13:21:30.040Z' - links: - - rel: self - href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json - assets: - analytic: - title: 4-Band Analytic - href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif - thumbnail: - title: Thumbnail - href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png - type: image/png - itemId: - type: string - example: path/to/example.tif - description: Provider identifier, a unique ID, potentially a link to a file. - itemType: - type: string - description: The GeoJSON type - enum: - - Feature - itemAssets: - type: object - additionalProperties: - type: object - required: - - href - properties: - href: - type: string - format: url - description: Link to the asset object - example: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png - title: - type: string - description: Displayed title - example: Thumbnail - type: - type: string - description: Media type of the asset - example: image/png - itemProperties: - type: object - required: - - datetime - description: provides the core metatdata fields plus extensions - properties: - datetime: - $ref: '#/components/schemas/time' - additionalProperties: - description: Any additional properties added in via extensions. - itemCollectionLinks: - type: array - description: >- - An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type. - items: - $ref: '#/components/schemas/link' - example: - - rel: next - href: http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk -tags: - - name: STAC - description: Extension to WFS3 Core to support STAC metadata model and search API diff --git a/api-spec/definitions/WFS3core+STAC.yaml b/api-spec/definitions/WFS3core+STAC.yaml deleted file mode 100644 index fb657b8af..000000000 --- a/api-spec/definitions/WFS3core+STAC.yaml +++ /dev/null @@ -1 +0,0 @@ -!!files_merge_append ["definitions/STAC-standalone.yaml", "definitions/WFS3core.fragment.yaml", "definitions/STAC-collections.fragment.yaml"] \ No newline at end of file diff --git a/api-spec/examples.md b/api-spec/examples.md new file mode 100644 index 000000000..9d3c2e964 --- /dev/null +++ b/api-spec/examples.md @@ -0,0 +1,121 @@ +# STAC API Examples + +A STAC API supports both GET and POST requests. It is best to use POST when using the intersects query for two reasons: + +1. the size limit for a GET request is less than that of POST, so if a complex geometry is used GET may fail. +2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON parameters (such as intersect) + +## Core examples + +``` +GET /collections/{name}/items?bbox=160.6,-55.95,-170,-25.89 +``` + +Requests all the data in the collection that is in New Zealand. The filtering is made to be compatible with the STAC API, +and the two specs seek to share the general query and filtering patterns. The key difference is that a STAC search endpoint +will do cross collection search. A typical WFS will have multiple collections, and each will just offer search for its particular +collection. + +Request all the data in mycollection that is in New Zealand: + +``` +GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89 +``` + +Request 100 results in mycollection from New Zealand: + +``` +GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100 +``` + +Request results 101-200 in mycollection from New Zealand: + +``` +GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&page=2&limit=100 +``` + +Request all the data in mycollection that is in New Zealand from January 1st, 2019: + +``` +GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01 +``` + +Request all the data in mycollection from between January 1st and April 1st, 2019: + +``` +GET /collections/mycollection/items?time=2019-01-01/2019-04-01 +``` + +Request all catalog items it has that are from the second half of March, 2018 and that intersect with this area: + +``` +POST /collections/mycollection/items +``` + +Body: +```json +{ + "bbox": [5.5, 46, 8, 47.4], + "time": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" +} +``` + +![swiss_bbox](https://user-images.githubusercontent.com/407017/38382405-b5e69344-38be-11e8-90dc-35738678356d.png) + +_Map © OpenStreetMap contributors_ + + +To specify a time range, use the interval syntax. + +``` +POST /collections/mycollection/items +``` + +```json +{ + "time": "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z" +} +``` + +``` +GET /collections/mycollection/items?time=2007-03-01T13:00:00Z/2008-05-11T15:30:00Z +``` + +Intervals can also be specified using the duration syntax: + +``` +2007-03-01T13:00:00Z/P1Y2M10DT2H30M +``` + +If time is a period without a start or end date, the end date is assigned to "now": + +`P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()` + +## Extension examples + +The API Extensions allow for more sophisticated searching, such as the ability to search by geometries and searching on specific Item properties. + +Use the *[Query](extensions/query/README.md)* extension to search for any data falling within a specific geometry collected between Jan 1st and May 1st, 2019: + +``` +POST /stac/search +``` + +Body: +```json +{ + "limit": 100, + "intersects": { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [[ + [-77.08248138427734, 38.788612962793636], [-77.01896667480469, 38.788612962793636], + [-77.01896667480469, 38.835161408189364], [-77.08248138427734, 38.835161408189364], + [-77.08248138427734, 38.788612962793636] + ]] + } + }, + "time": "2019-01-01/2019-05-01" +} +``` diff --git a/api-spec/extensions/README.md b/api-spec/extensions/README.md new file mode 100644 index 000000000..c1e459940 --- /dev/null +++ b/api-spec/extensions/README.md @@ -0,0 +1,132 @@ +# API Extensions + +This folder contains extensions to the SpatioTemporal Asset Catalog API specification by providing new OpenAPI fragments. + + +Anyone is welcome to create an extension (see section 'Extending STAC'), and is encouraged to at least link to the extension from here. The third-party / vendor extension section is for the sharing of extensions. As third parties create useful extensions for their implementation it is expected that others will make use of it, and then evolve to make it a 'community extension', that several providers maintain together. For now anyone from the community is welcome to use this extensions/ folder of the stac-spec repository to collaborate. + +API Extensions given follow the same guidelines for Extension Maturity as given in the *[Content Extensions README](../../extensions/README.md)*. + +## List of community extensions + +| Extension Name | Description | Maturity | +| ------------- | ----------- | -------- | +| [Fields](fields/README.md) | Adds parameter to constrol which fields are returned in the response. | *Pilot* | +| [Query](query/README.md) | Adds parameter to search Item and Collection properties. | *Pilot* | +| [Sort](sort/README.md) | Adds Parameter to control sorting of returns results. | *Pilot* | +| [Transaction](transaction/README.md) | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections. | *Pilot* | + +## Third-party / vendor extensions + +The following extensions are provided by third parties (vendors). They tackle very specific +use-cases and may be less stable than the official extensions. Once stable and adopted by multiple +parties, extensions may be made official and incorporated in the STAC repository. + +Please contact a STAC maintainer or open a Pull Request to add your extension to this table. + +| Name | Scope | Description | Vendor | +| -------- | ----- | ----------- | ------ | +| None yet | | | | + +## Proposed extensions + +The following extensions are proposed through the +[STAC issue tracker](https://github.com/radiantearth/stac-spec/issues) and are considered to be +implemented. If you would find any of these helpful or are considering to implement a similar +extension, please get in touch through the referenced issues: + +- None yet + +## Creating new extensions + +Creating new extensions requires creating an OpenAPI fragment to define it. + +Example fragment: + +```yaml +IntersectsFilter: + type: object + description: >- + Only returns items that intersect with the provided polygon. + properties: + intersects: + $ref: "#/definitions/Polygon" +Polygon: + type: object + properties: + type: + type: string + enum: + - polygon + coordinates: + $ref: "#/definitions/Polygon2D" + required: + - type + - coordinates +Polygon2D: + type: array + minItems: 1 + items: + $ref: "#/definitions/LinearRing2D" +LinearRing2D: + type: array + minItems: 4 + items: + $ref: "#/definitions/Point2D" + example: [[-104, 35], [-103, 35], [-103, 34], [-104, 34], [-104, 35]] +Point2D: + description: A 2d geojson point + type: array + minimum: 2 + maximum: 2 + items: + type: number + format: double + example: + - -104 + - 35 +``` + +It is likely that there are schemas that should be used in common for types of filters that target different fields. We should define a common set of filter types that can be used in defining filters for different fields. + +- `NumberRange` +- `TimeRange` +- `Text` +- `ArrayIncludes` +- Etc. + +When defining a new filter fragment, you would reference these common filter types: + +```yaml +CloudCover: + type: object + description: >- + Filter items by desired cloud coverage. + properties: + cloudcover: + $ref: "#/definitions/NumberRange" +``` + +Some additional extensions that have been discussed: + +CQL support for generic queries: + +```json +{ + "CQL": "CQL Select String" +} +``` + +### Adding filters to search + +Filters should be documented as properties in the `searchBody`: + +```yaml +searchBody: + description: The search criteria + type: object + allOf: + - $ref: "#/components/schema/bboxFilter" + - $ref: "#/components/schema/TimeFilter" + - $ref: "#/components/schema/IntersectsFilter" +``` diff --git a/api-spec/extensions/STAC-extensions.merge.yaml b/api-spec/extensions/STAC-extensions.merge.yaml new file mode 100644 index 000000000..65628c2c0 --- /dev/null +++ b/api-spec/extensions/STAC-extensions.merge.yaml @@ -0,0 +1 @@ +!!files_merge_append ["STAC.yaml", "extensions/query/query.fragment.yaml", "extensions/sort/sort.fragment.yaml", "extensions/fields/fields.fragment.yaml"] diff --git a/api-spec/extensions/fields/README.md b/api-spec/extensions/fields/README.md new file mode 100644 index 000000000..2d0cc561c --- /dev/null +++ b/api-spec/extensions/fields/README.md @@ -0,0 +1,34 @@ +# Fields API Extension + +**Extension [Maturity Classification](../../../extensions/README.md#extension-maturity): Pilot** + +The STAC search endpoint, `/stac/search`, by default returns entire Items. The fields API extension adds a new parameter, `fields` that allows the user to define fields in the items returned to be returned or excluded. If both include and exclude are specified, include takes precedence. + +To return just the `id`, `geometry`, and the property `eo:cloud_cover`: +```json +{ + "fields": [ + { + "include": [ + "id", + "geometry", + "properties.eo:cloud_cover" + ] + } + ] +} +``` + +To return the whole item without the geometry: + +```json +{ + "fields": [ + { + "exclude": [ + "geometry" + ] + } + ] +} +``` diff --git a/api-spec/extensions/fields.fragment.yaml b/api-spec/extensions/fields/fields.fragment.yaml similarity index 65% rename from api-spec/extensions/fields.fragment.yaml rename to api-spec/extensions/fields/fields.fragment.yaml index 8ce3c33d6..64e087ab1 100644 --- a/api-spec/extensions/fields.fragment.yaml +++ b/api-spec/extensions/fields/fields.fragment.yaml @@ -26,14 +26,13 @@ components: $ref: '#/components/schemas/fields' fields: description: | - The geometry member determines whether the geometry is populated or is null. The - include and exclude members specify an array of property names that are either - included or excluded from the result, respectively. If both include and exclude - are specified, include takes precedence. + The include and exclude members specify an array of + property names that are either included or excluded + from the result, respectively. If both include and + exclude are specified, include takes precedence. + Values should include the full JSON path of the property. type: object properties: - geometry: - type: boolean include: type: array items: @@ -42,3 +41,11 @@ components: type: array items: type: string + example: + include: + - id + - 'properties.eo:cloud_cover' + exclude: + - geometry + - properties.datetime + diff --git a/api-spec/extensions/query/README.md b/api-spec/extensions/query/README.md new file mode 100644 index 000000000..a90857d35 --- /dev/null +++ b/api-spec/extensions/query/README.md @@ -0,0 +1,34 @@ +# Query API Extension + +**Extension [Maturity Classification](../../../extensions/README.md#extension-maturity): Pilot** + +The STAC search endpoint, `/stac/search`, by default only accepts the core filter parameters given in the *[api-spec](../../api-spec.md)*. The Query API extension adds additional filters for searching on the properties of Items. + +The syntax for the `query` filter is: + +```json +{ + "query": { + "": { + "": + } + } +} +``` + +Each property to search is an entry in the `query` filter. can be one of: eq, neq, lt, lte, gt, gte, startsWith, endsWith, contains. Multiple operators can be provided for each property which is treated as a logical AND, all conditions must be met. + +### Examples + +Find scenes with cloud cover between 0 and 10%: + +```json +{ + "query": { + "", + "direction": "" + } + ] +} +``` + +where is either "asc" (ascending) or "desc" (descending). The `sort` value is an array, so multiple sort fields can be defined which will be used to sort the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`). diff --git a/api-spec/extensions/sorting.fragment.yaml b/api-spec/extensions/sort/sort.fragment.yaml similarity index 100% rename from api-spec/extensions/sorting.fragment.yaml rename to api-spec/extensions/sort/sort.fragment.yaml diff --git a/extensions/transaction/README.md b/api-spec/extensions/transaction/README.md similarity index 59% rename from extensions/transaction/README.md rename to api-spec/extensions/transaction/README.md index 05aa6e2e2..f498786c2 100644 --- a/extensions/transaction/README.md +++ b/api-spec/extensions/transaction/README.md @@ -1,9 +1,8 @@ -# Transaction Extension Specification for WFS3 Core / STAC +# Transaction API Extension -**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** +**Extension [Maturity Classification](../../../extensions/README.md#extension-maturity): Pilot** -This folder contains an API extension to support the creation, editing, and deleting of items on a -specific WFS3 collection. +The core API doesn't support adding, editing, or removing items. The transaction API extension supports the creation, editing, and deleting of items through POST, PUT, PATCH, and DELETE requests. ## Methods @@ -12,14 +11,4 @@ specific WFS3 collection. | `POST /collections/{collectionID}/items` | Adds a new item to a collection. | | `PUT /collections/{collectionId}/items/{featureId}` | Updates an existing item by ID using a complete item description. | | `PATCH /collections/{collectionId}/items/{featureId}` | Updates an existing item by ID using a partial item description, compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386). | -| `DELETE /collections/{collectionID}/items` | Deletes an existing item by ID. | - -## Items - -As defined here, these methods operate on STAC Items and both STAC and WFS3 Collections. However, apart from the -body schema defining the STAC Item "payload", these API methods are completely generic and could be -reused as an extension for WFS3 Core. - -## Implementations - -Both Boundless and Harris servers have sample [implementations](../../implementations.md) of this transaction extension. \ No newline at end of file +| `DELETE /collections/{collectionID}/items` | Deletes an existing item by ID. | \ No newline at end of file diff --git a/extensions/transaction/transaction-fragment.yaml b/api-spec/extensions/transaction/transaction.fragment.yaml similarity index 95% rename from extensions/transaction/transaction-fragment.yaml rename to api-spec/extensions/transaction/transaction.fragment.yaml index f069239cd..fd03ef2b8 100644 --- a/extensions/transaction/transaction-fragment.yaml +++ b/api-spec/extensions/transaction/transaction.fragment.yaml @@ -146,7 +146,7 @@ components: bbox: $ref: '#/components/schemas/bbox' geometry: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' type: $ref: '#/components/schemas/itemType' properties: diff --git a/api-spec/filters.md b/api-spec/filters.md deleted file mode 100644 index 0d8363f44..000000000 --- a/api-spec/filters.md +++ /dev/null @@ -1,192 +0,0 @@ -# Filters in SpatioTemporal Asset Catalogs - -The core of the STAC API is intending to provide a minimal set of features so that there is a low bar to entry for catalog -implementations. The core concepts in STAC are Spatial and Temporal data, so those are the only filters that are in core -and are required to be supported. - -The filters are designed to be simple as possible for a client to construct. To match the default JSON responses the -encoding of filters is done by default in JSON. This allows clients to support filtering without additional tools. The -search endpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST -search the is recommended way to filter results to avoid the URL encoding issues that can happen with GET. - -Searching using POST will accept a JSON object where the top level keys are specifying which type of filter -to apply. Those same top level key names can be used as query string parameters for the GET request. Items in the collection -should match all filters to be returned when querying. This implies a logical AND operation. If -an OR operation is needed, it should be specified through an extension filter. - -For the spatial query, we are starting with the simplest form for a client to generate: a bbox. The bbox query -is a simple array of WGS84 Longitude and Latitude values. They are in this order: [west, south, east, north]. -This query will perform an intersects operation on the geometry values of the items in the catalog. Some GeoJSON -objects may provide a bbox property in addition to geometry, but it should not be used for the bbox filter since -it is an optional field in GeoJSON. - -## Examples - -### To filter by spatial extent - -`POST`: - -```json -{ - "bbox": [-180, -90, 180, 90] -} -``` - -`GET`: - -``` -?bbox=[-180,-90,180,90] -``` - -The temporal query is based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. It will compare against the datetime property of the STAC Item. - -### To find items with an exact date - -POST: - -```json -{ - "time": "2007-03-01T13:00:00Z" -} -``` - -GET: - -``` -?time=2007-03-01T13:00:00Z -``` - -### To find items within an interval - -To specify a time range, use the interval syntax. - -POST: - -```json -{ - "time": "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z" -} -``` - -GET: - -``` -?time=2007-03-01T13:00:00Z/2008-05-11T15:30:00Z -``` - -Intervals can also be specified using the duration syntax: - -``` -2007-03-01T13:00:00Z/P1Y2M10DT2H30M -``` - -If time is a period without a start or end date, the end date is assigned to "now": - -`P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()` - -## Filter Extensions - -Spatial and temporal filtering is not enough for many use cases. STAC is designed to be extensible, so we encourage additional filters to be provided as extensions. - -Filter extensions are intended to provide a place to specify additional filter types and behavior. Some filters may need to target vendor specific fields or use a more complex structure when defining the filter. For example, a geospatial intersection filter that supports a polygon as input. - -Filter extensions should be specified as an openapi fragment. This is a section of YAML that can be incorporated into the larger api definition. These fragments can then be combined into an implementation specific api definition that describes the full api. - -Example fragment: - -```yaml -IntersectsFilter: - type: object - description: >- - Only returns items that intersect with the provided polygon. - properties: - intersects: - $ref: "#/definitions/Polygon" -Polygon: - type: object - properties: - type: - type: string - enum: - - polygon - coordinates: - $ref: "#/definitions/Polygon2D" - required: - - type - - coordinates -Polygon2D: - type: array - minItems: 1 - items: - $ref: "#/definitions/LinearRing2D" -LinearRing2D: - type: array - minItems: 4 - items: - $ref: "#/definitions/Point2D" - example: [[-104, 35], [-103, 35], [-103, 34], [-104, 34], [-104, 35]] -Point2D: - description: A 2d geojson point - type: array - minimum: 2 - maximum: 2 - items: - type: number - format: double - example: - - -104 - - 35 -``` - -It is likely that there are schemas that should be used in common for types of filters that target different fields. We should define a common set of filter types that can be used in defining filters for different fields. - -- `NumberRange` -- `TimeRange` -- `Text` -- `ArrayIncludes` -- Etc. - -When defining a new filter fragment, you would reference these common filter types: - -```yaml -CloudCover: - type: object - description: >- - Filter items by desired cloud coverage. - properties: - cloudcover: - $ref: "#/definitions/NumberRange" -``` - -Some additional extensions that have been discussed: - -CQL support for generic queries: - -```json -{ - "CQL": "CQL Select String" -} -``` - -## Adding filters to search - -Filters should be documented as properties in the `searchBody`: - -```yaml -searchBody: - description: The search criteria - type: object - allOf: - - $ref: "#/components/schema/bboxFilter" - - $ref: "#/components/schema/TimeFilter" - - $ref: "#/components/schema/IntersectsFilter" -``` - -### A note on the POST semantics - -Though `POST` in a pure REST sense is just for creating new objects, the semantics of this `POST` is on a `/search/` resource, so -it can be thought of us `POST`ing to create an implicit search object that is then read right away with a `GET`. It seemed -onerous to require users to `POST` a new search object and then request it back in a `GET`. - -Note that the `items` returned in a search are not at their canonical location, and following the `self` links back to -its home location will be in the collection that can be `POST`ed to, following proper REST semantics. diff --git a/api-spec/openapi/STAC.merge.yaml b/api-spec/openapi/STAC.merge.yaml new file mode 100644 index 000000000..1bfb082d4 --- /dev/null +++ b/api-spec/openapi/STAC.merge.yaml @@ -0,0 +1 @@ +!!files_merge_append ["openapi/WFS3.yaml", "openapi/STAC.yaml"] \ No newline at end of file diff --git a/api-spec/STAC-standalone.yaml b/api-spec/openapi/STAC.yaml similarity index 73% rename from api-spec/STAC-standalone.yaml rename to api-spec/openapi/STAC.yaml index 6675ce300..c989d535f 100644 --- a/api-spec/STAC-standalone.yaml +++ b/api-spec/openapi/STAC.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: - title: The SpatioTemporal Asset Catalog API (standalone) - version: 0.6.2 + title: The SpatioTemporal Asset Catalog API + version: 0.7.0 description: >- This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API specification. Any service that implements this endpoint to allow search of @@ -9,14 +9,13 @@ info: available as an OpenAPI fragment that can be integrated with other OpenAPI definitions, and is designed to slot seamlessly into a WFS 3 API definition. contact: - name: Cool Sat Corp - email: info@cool-sat.com - url: 'http://cool-sat.com/contact/' + name: STAC Specification + url: 'http://stacspec.org' license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' servers: - - url: 'http://dev.cool-sat.com/' + - url: 'http://dev.cool-sat.com' description: Development server - url: 'http://www.cool-sat.com' description: Production server @@ -34,17 +33,20 @@ paths: - STAC responses: '200': - description: A catalog json definition. Used as an entry point for a crawler. + description: A catalog JSON definition. Used as an entry point for a crawler. content: application/json: schema: $ref: '#/components/schemas/catalogDefinition' /stac/search: get: - summary: Search STAC items by simple filtering. + summary: Search STAC items with simple filtering. description: >- Retrieve Items matching filters. Intended as a shorthand API for simple - queries. This method is optional. + queries. + + + This method is optional, but you MUST implement `POST /stac/search` if you want to implement this method. operationId: getSearchSTAC tags: - STAC @@ -52,6 +54,9 @@ paths: - $ref: '#/components/parameters/bbox' - $ref: '#/components/parameters/time' - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/ids' + - $ref: '#/components/parameters/collections' responses: '200': description: A feature collection. @@ -72,10 +77,13 @@ paths: schema: type: string post: - summary: Search STAC items by full-featured filtering. + summary: Search STAC items with full-featured filtering. description: >- retrieve items matching filters. Intended as the standard, full-featured - query API. This method is mandatory. + query API. + + + This method is mandatory to implement if `GET /stac/search` is implemented. If this endpoint is implemented on a server, it is required to add a link with `rel` set to `search` to the `links` array in `GET /stac` that refers to this endpoint. operationId: postSearchSTAC tags: - STAC @@ -127,6 +135,49 @@ components: default: 10 style: form explode: false + page: + name: page + in: query + description: | + The optional page parameter returns the specified page of results + (with each page having size=limit). + + * Minimum = 1 + * Default = 1 + required: false + schema: + type: integer + minimum: 1 + default: 1 + style: form + explode: false + ids: + name: ids + in: query + description: | + The optional ids parameter returns a FeatureCollection of all matching ids. + If provided all other parameters that further restrict the number of search results (except `page` and `limit`) will be ignored. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false + collections: + name: collections + in: query + description: | + The collections search parameter is a list of of collection IDs for Items to match. + Only items that are included in one of these collections will be returned, otherwise + all collections will be searched. + required: false + schema: + type: array + minItems: 1 + items: + type: string + explode: false bbox: name: bbox in: query @@ -209,16 +260,13 @@ components: type: string description: type: string - links: - type: array - items: - $ref: '#/components/schemas/link' link: + title: Link + description: A generic link. type: object required: - href - rel - additionalProperties: true properties: href: type: string @@ -301,7 +349,7 @@ components: description: Only returns items that intersect with the provided polygon. properties: intersects: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' time: type: string description: > @@ -325,11 +373,10 @@ components: - id - description - links - additionalProperties: true properties: stac_version: type: string - example: 0.6.2 + example: 0.7.0 id: type: string example: naip @@ -340,7 +387,95 @@ components: type: string example: Catalog of NAIP Imagery. links: - $ref: '#/components/schemas/links' + type: array + items: + anyOf: + - $ref: '#/components/schemas/link' + - title: Link to search endpoint + description: Link the search endpoint, which is **required** to be specified if the API implements `/stac/search`. + type: object + required: + - href + - rel + properties: + href: + type: string + format: url + example: 'http://www.cool-sat.com/stac/search' + rel: + type: string + enum: + - search + type: + type: string + title: + type: string + collectionInfo: + type: object + required: + - stac_version + - id + - description + - license + - extent + properties: + stac_version: + type: string + example: 0.7.0 + id: + description: 'identifier of the collection used, for example, in URIs' + type: string + example: buildings + keywords: + title: Keywords + type: array + items: + type: string + example: + - buildings + - properties + - constructions + version: + title: Collection Version + type: string + example: 2018Q3 + license: + title: Collection License Name + type: string + example: Apache-2.0 + providers: + type: array + items: + properties: + name: + title: Organization name + type: string + example: Big Building Corp + description: + title: Provider description + type: string + example: "No further processing applied." + roles: + title: Organization roles + type: array + items: + type: string + enum: + - producer + - licensor + - processor + - host + example: + - producer + - licensor + url: + title: Homepage + description: >- + Homepage on which the provider describes the dataset and + publishes contact information. + type: string + format: url + example: http://www.big-building.com itemCollection: type: object required: @@ -373,13 +508,15 @@ components: bbox: $ref: '#/components/schemas/bbox' geometry: - $ref: 'http://geojson.org/schema/Geometry.json' + $ref: 'https://stacspec.org/assets/Geometry.json' type: $ref: '#/components/schemas/itemType' properties: $ref: '#/components/schemas/itemProperties' links: - $ref: '#/components/schemas/links' + type: array + items: + $ref: '#/components/schemas/link' assets: $ref: '#/components/schemas/itemAssets' example: diff --git a/api-spec/definitions/WFS3core.fragment.yaml b/api-spec/openapi/WFS3.yaml similarity index 98% rename from api-spec/definitions/WFS3core.fragment.yaml rename to api-spec/openapi/WFS3.yaml index 1176968d7..db91dd75d 100644 --- a/api-spec/definitions/WFS3core.fragment.yaml +++ b/api-spec/openapi/WFS3.yaml @@ -1,6 +1,6 @@ openapi: 3.0.1 info: - title: The SpatioTemporal Asset Catalog API + WFS3 + title: WFS3 core API paths: /: get: @@ -120,7 +120,7 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/FeatureCollection.json' + $ref: 'https://stacspec.org/assets/FeatureCollection.json' text/html: schema: type: string @@ -148,7 +148,7 @@ paths: content: application/geo+json: schema: - $ref: 'http://geojson.org/schema/Feature.json' + $ref: 'https://stacspec.org/assets/Feature.json' text/html: schema: type: string diff --git a/api-spec/package-lock.json b/api-spec/package-lock.json index 4de793b2e..9f3a9bd3a 100644 --- a/api-spec/package-lock.json +++ b/api-spec/package-lock.json @@ -23,9 +23,9 @@ "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" }, "js-yaml": { - "version": "3.12.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.12.0.tgz", - "integrity": "sha512-PIt2cnwmPfL4hKNwqeiuz4bKfnzHTBv6HyVgjahA6mPLwPDzjDWrplJBMjHUFxku/N3FlmrbyPclad+I+4mJ3A==", + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", "requires": { "argparse": "^1.0.7", "esprima": "^4.0.0" diff --git a/api-spec/package.json b/api-spec/package.json index bf1151297..b3a0ffb47 100644 --- a/api-spec/package.json +++ b/api-spec/package.json @@ -5,10 +5,9 @@ "repository": "https://github.com/radiantearth/stac-spec", "license": "Apache-2.0", "scripts": { - "generate-standalone": "yaml-files definitions/STAC-standalone.yaml STAC-standalone.yaml", - "generate-query-ext": "yaml-files definitions/STAC-query.yaml STAC-query.yaml", - "generate-wfs": "yaml-files definitions/WFS3core+STAC.yaml WFS3core+STAC.yaml", - "generate-all": "npm run generate-standalone && npm run generate-wfs && npm run generate-query-ext" + "generate-ext": "yaml-files extensions/STAC-extensions.merge.yaml STAC-extensions.yaml", + "generate-core": "yaml-files openapi/STAC.merge.yaml STAC.yaml", + "generate-all": "npm run generate-core && npm run generate-ext" }, "dependencies": { "yaml-files": "^1.1.0" diff --git a/api-spec/wfs-stac.md b/api-spec/wfs-stac.md deleted file mode 100644 index 97259ebff..000000000 --- a/api-spec/wfs-stac.md +++ /dev/null @@ -1,87 +0,0 @@ -# WFS and STAC integration - -At the [Fort Collins Sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) the -decision was made to align STAC with the [Web Feature Service 3 specification](https://github.com/opengeospatial/WFS_FES). -This document gives more details on what that practically means and how it all works. - -## What is WFS - -WFS stands for Web Feature Service, and is the specification from the [Open Geospatial Consortium](http://opengeospatial.org) -that specifies how to search for geospatial vector data online. The specifications have traditionally been quite -heavyweight, but the new 3.0 version of WFS is actually very in line with what the SpatioTemporal Asset Catalog group has done. -It provides a RESTful interface to query geospatial data, with GeoJSON as a main return type. With WFS you can return any -"feature", which is basically any type of geospatial object that can be represented by points, lines or polygons. So one -might have a WFS of all the buildings for a city, or the locations of ships, or all the electricity lines. - -## WFS + STAC API - -The STAC API has developed as a RESTful interface to query geospatial assets, with GeoJSON as return type. While STAC -is much more about the "assets" - another piece of data that is linked to - each STAC Item fits in to the definition of -a "feature", where the geometry is basically the footprint of the asset. So the data in a catalog could easily be -represented as a WFS, with just some extensions for linking to the assets, and fixing the `datetime` field. - -So the decision was made to combine efforts. The key piece that STAC needs that WFS does not provide is the ability -to search across 'collections', so the `/stac/search` endpoint is made to be an "extension" to WFS that provides -that capability. So any WFS that is providing data that can be represented as STAC Items can choose to add the -STAC endpoint. - -In addition to the `/stac/search` endpoint, STAC APIs provide the ability to 'browse' all the [Items](../item-spec/) that -are available from a service. This is done using the `/stac/` endpoint, returning a full [STAC Catalog](../catalog-spec/). -Ideally that Catalog makes extensive use of [STAC Collections](../collection-spec/) to further describe the holdings. - -The STAC Collection spec is designed to be compatible with the WFS `/collections/{collectionId}` endpoint's response. This enables -WFS + STAC implementations to just extend the WFS collections with a bit more information to be STAC compliant Collection -definitions. - -An additional best practice is to use the WFS items available in `/collections/{collectionId}/items` as the "canonical" web -location. Then the STAC Catalogs returned from `/stac/` can either link directly to those (from the appropriate sub-catalog - -for example `/stac/landsat8/42/31/2017/` would be a catalog consisting of links to `/collections/`). Or it can return JSON -in the link structure (like `/stac/landsat8/42/31/2017/item203123.json`), and have that returned JSON use a link with `rel=canonical` that goes back to the `Item` that is in the collection. - -### WFS Structure - -A Web Feature Service is a standard API that represents collections of geospatial data. - -``` -GET /collections -``` - -Lists the collections of data on the server that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)), -and each describes basic information about the geospatial data collection, like its name and description, as well as the -spatial and temporal extents of all the data contained. The collections returned are compliant to both WFS Collections and -[STAC collections](../collections-spec/README.md). A STAC search extension would only query those collections which -have data that validates as STAC Items - with a datetime field and references to assets. But a STAC can live alongside -other WFS collections, like an organization might choose to have their building and road data in WFS collections, alongside -their STAC-compatible imagery data. - -``` -GET /collections/{name}/items?bbox=160.6,-55.95,-170,-25.89 -``` - -Requests all the data in the collection that is in New Zealand. The filtering is made to be compatible with the STAC API, -and the two specs seek to share the general query and filtering patterns. The key difference is that a STAC search endpoint -will do cross collection search. A typical WFS will have multiple collections, and each will just offer search for its particular -collection. - -### Strongly Typed STAC data - -The scenario that using a WFS with a STAC search endpoint that makes the most sense is when a data provider wants to provide more -insight in to heterogenous data that is exposed on a STAC search. For example they might have imagery data from different satellite providers -and even some drone data. These will all have different fields. A single STAC endpoint can be used to expose them all. But it can be quite -useful to let users inspect a particular data type. That area of the `/collections/{name}` hierarchy can be used to expose additional -metadata and validation schemas that give more insight in to that data, as well as a place to query just that data. - -In general it is recommended to provide as much information about different types of data as possible, so using WFS is recommended. But -the standalone option is there for those who just want to expose their data as quickly and easily as possible. Note a WFS can -provide heterogenous data from any of its collections endpoints, but the STAC API recommendation is to use one collection per -logical data type. - -### Potential Transaction Extension - -The other benefit of individual collection endpoints is that it gives a logical location for simple RESTful transactions - -``` -POST /collections/landsat/items/ -``` - -There have been a couple implementations that have done transactions, and soon will contribute an extension. diff --git a/catalog-spec/README.md b/catalog-spec/README.md index e5d8a9342..f9fdd1b05 100644 --- a/catalog-spec/README.md +++ b/catalog-spec/README.md @@ -19,18 +19,16 @@ an OpenAPI definition of the standard way to do this, at the `/stac/` endpoint. **The Specification:** The main Catalog specification is in *[catalog-spec.md](catalog-spec.md)*. It includes an overview and in depth explanation of the structures and fields. +**Best Practices:** While the main spec is designed to be quite flexible, there are a set of emerging best practices for +how to actually manage a catalog. The *[catalog-best-practices.md](catalog-best-practices.md)* document lays out a number +of these. In time some of these may evolve to be part of the core spec. + **Examples:** For samples of how Catalogs can be implemented the *[examples/](examples/)* folder contains a full sample catalog. **Schemas:** The schemas to validate the core Catalog definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[catalog.json](json-schema/catalog.json)*. -## In the API directory - -**Dynamic Catalog OpenAPI Definition:** The [api-spec](../api-spec) directory contains OpenAPI definitions of the `/stac/` -endpoint, that is the dynamic version of a Catalog. See [STAC-standalone.yaml](../api-spec/STAC-standalone.yaml), or you can -browse it online on [swaggerhub's STAC-standalone](https://app.swaggerhub.com/apis/cholmesgeo/STAC-standalone/0.6.0-beta#/STAC/get_stac) definition. - ## Schema Validation Instruction on schema validation for STAC Catalog can be found in the [validation instructions](validation/README.md). diff --git a/catalog-spec/catalog-best-practices.md b/catalog-spec/catalog-best-practices.md new file mode 100644 index 000000000..9c310b1fc --- /dev/null +++ b/catalog-spec/catalog-best-practices.md @@ -0,0 +1,208 @@ +# STAC Catalog Best Practices + +This document makes a number of recommendations for creating real world SpatioTemporal Asset [Catalogs](catalog-spec.md). None of them +are required to meet the core specification, but following these practices will make life easier for client tooling +and for users. They come about from practical experience of implementors, and introduce a bit more 'constraint' for +those who are creating new catalogs or new tools to work with STAC. + +In time some of these may evolve to become part of the core specification, but while the current goal of the core is to remain +quite flexible and simple to meet a wide variety of use cases. + +## Static and Dynamic Catalogs + +As mentioned in the main [Catalog specification](catalog-spec.md), there are two main types of catalogs - static +and dynamic. This section explains each of them in more depth and shares some best practices on each. + +#### Static Catalogs + +A main target for STAC has been object storage services like [Amazon S3](https://aws.amazon.com/s3/), +[Google Cloud Storage](https://cloud.google.com/storage/) and [Azure Storage](https://azure.microsoft.com/en-us/services/storage/), +so that users can stand up a full STAC implementation with static files. Implementations created with just files online +are referred to as 'static catalogs'. These include not just the cloud services, but any type of file server that is online. + +Static Catalogs tend to make extensive use of *sub-catalogs* to organize their Items in to sensible browsing structures, +as they can only have a single representation of their catalog, since the static nature means the structure is baked in. +While it is up to the implementor to organize the catalog, it is recommended to arrange it in a way that would make sense +for a human to browse a set of STAC Items in an intuitive matter. + +The recommendation for static catalogs is to define them using the file name `catalog.json` or `collection.json` to distinguish +the catalog from other JSON type files. In order to support multiple catalogs, the recommended practice +is to place the catalog file in namespaces "directories". For example: + +- current/catalog.json +- archive/catalog.json + +#### Dynamic Catalogs + +Dynamic STAC Catalogs are those that generate their JSON responses programmatically instead of relying on a set of +already defined files. Typically a dynamic catalog implements the full [STAC API](../stac-api/) which enables +search of the Items indexed. But the `/stac/` endpoint returns the exact same `Catalog` and `Item` structures as a +static catalog, enabling the same discovery from people browsing and search engines crawling. Dynamic API's that +just seek to expose some data can also choose to only implement a Catalog the `/stac/` endpoint that returns dynamically. +For example a Content Management Service like Drupal or an Open Data Catalog like CKAN could choose to expose its content +as linked STAC Items by implementing a dynamic catalog. + +One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same `Items` in +different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by +providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location +(or at least use a `rel` link that indicates the location of the canonical one. + +The STAC API is also made to be compatible with WFS3, which has a set structure for the canonical location of its features. +STAC Items should use the WFS3 location as their canonical location, and then in the `/stac/` browse structure would just +link to those locations. + +## Catalog Layout + +Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, items +and assets, and how to name them. The specification leaves this totally open, and you can link things as you want. We +encourage people to explore new structures. But the following are what a number of implementors ended up doing. Following +these recommendations makes for more legible catalogs. + +1. Root documents (catalogs / collections) should be at the root of a directory tree containing the static catalog. +2. Catalogs should be named `catalog.json` (cf. `index.html`). +3. Collections that are distinct from catalogs should be named `collection.json`. +4. Items should be named `.json` +5. Sub-catalogs should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent) (e.g. `.../sample/sub1/catalog.json`). +6. Items should be stored in subdirectories of their parent catalog. +This means that each item and its assets are contained in a unique subdirectory +7. Limit the number of items in a catalog or sub-catalog, grouping / partitioning as relevant to the dataset + +### Dynamic Catalog Layout + +While these recommendations were primarily written for [static catalogs](catalog-spec.md#static-catalogs), they apply +equally well to [dynamic catalogs](catalog-spec.md#dynamic-catalogs). Subdirectories of course would just be URL paths +generated dynamically, but the structure would be the same as is recommended. + +One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same Items in +different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another +by providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location +(or at least use a rel link that indicates the location of the canonical one). It is recommended that dynamic catalogs +provide multiple 'views' to allow users to navigate in a way that makes sense to them, providing multiple 'sub-catalogs' +from the root catalog that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the +canonical 'rel' link should be used to designate the primary location of the item to search engine crawlers. + +## Use of links + +The main catalog specification allows both relative and absolute links, and says that `self` links are not required, but are +strongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it +is essential to use different link types. The best practice is to use one of the below +catalog types, applying the link recommendations consistently, instead of just haphazardly applying anything the spec allows. + +### Self-contained Catalogs + +A 'self-contained catalog' is one that is designed for portability. Users may want to download a catalog from online and be +able to use it on their local computer, so all links need to be relative. Or a tool that creates catalogs may need to work +without knowing the final location that it will live at online, so it isn't possible to set absolute 'self' URL's. These use +cases should utilize a catalog that follows the listed principles: + +* **Only relative href's in `links`**: The full catalog structure of links down to sub-catalogs and items, and their +links back to their parents and roots, should be done with relative URL's. This enables the full catalog to be downloaded or +copy to another location and to still be valid. This also implies no `self` link, as that link must be absolute. + +* **Use Asset `href` links consistently**: The links to the actual assets are allowed to be either relative or absolute. There +are two types of 'self-contained catalogs'. The first is just the metadata, and use absolute href links to refer to the +online locations of the assets. The second uses relative href links for the assets, and includes them in the folder structure. +This enables offline use of a catalog, by including all the actual data. + +Self-contained catalogs tend to be used more as static catalogs, where they can be easily passed around. But often they will +be generated by a more dynamic STAC service, enabling a subset of a catalog or a portion of a search criteria to be downloaded +and used in other contexts. That catalog could be used offline, or even published in another location. + +Self-contained catalogs are not just for offline use, however - they are designed to be able to be published online and to live +on the cloud in object storage. They just aim to ease the burden of publishing, by not requiring lots of updating of links. +Adding a single `self` link at the root is recommended for online catalogs, turning it into a 'relative published catalog', as detailed below. This anchors it in an online location and enable provenance tracking. + +### Published Catalogs + +A 'published catalog' is one that lives online in a stable location, and uses `self` links to establish its location and +enable easy provenance tracking. There are two types of published catalogs: + +* **Absolute Published Catalog** is a catalog that uses absolute links for everything, both in the `links` objects and in the +`asset` hrefs. It includes `self` links for every item. Generally these are implemented by dynamic catalogs, as it is quite +easy for them to generate the proper links dynamically. But a static catalog that knows its published location could easily +implement it. +* **Relative Published Catalog** is a catalog that uses relative links for everything, but includes an absolute `self` link at +the root catalog, to identify its online location. This is designed so that a self-contained catalog can be 'published' online +by just adding one field (the self link) to its root catalog. All the other links should remain relative. With this, the +resolution of item and sub-catalog self links may be done by traversing parent and root links, but requires reading multiple +sources to achieve this. + +## STAC on the Web + +One of the primary goals of STAC is to make spatiotemporal data more accessible on the web. One would have a right to be +surprised that there is nothing about HTML in the entire specification. This is because it is difficult to specify what +should be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions +of every STAC Item is paramount. + +The main recommendation is to have an HTML page for every single STAC `Item` and `Catalog`. They should be visually pleasing, +crawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called +[STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid catalog and generate unique web +pages for each `Item` and `Catalog` (or `Collection`). While it has a default look and feel, the design can easily be +modified to match an existing web presence. And it will automatically turn any Item with a [Cloud Optimized +GeoTIFF](http://cogeo.org) asset into an interactive, zoomable web map (using [tiles.rdnt.io](http://tiles.rdnt.io/) to render +the tiles on a [leaflet](https://leafletjs.com/) map). It also attempts to encapsulate a number of best practices that enable +STAC Items to show up in search engines, though that part is still a work in progress - contributions to STAC Browser to help +are welcome! + +Implementors are welcome to generate their own web pages, and additional tools that automatically transform STAC JSON into +html sites are encouraged. In time there will likely emerge a set of best practices from an array of tools, and we may be +able to specify in the core standard how to make the right HTML pages. But for now it is useful for catalogs to focus on +making data available as JSON, and then leverage tools that can evolve at the same time to make the best HTML experience. This +enables innovation on the web generation and search engine optimization to evolve independently of the catalogs themseleves. + +#### Schema.org, JSON-LD, DCAT, microformats, etc + +There is a strong desire to align STAC with the various web standards for data. These include [schema.org](http://schema.org) +tags, [JSON-LD](https://json-ld.org/) (particularly for Google's [dataset +search](https://developers.google.com/search/docs/data-types/dataset)), [DCAT](https://www.w3.org/TR/vocab-dcat/) +and [microformats](http://microformats.org/wiki/about). STAC aims to work with with as many as possible. Thusfar it has not seemed +to make sense to include any of them directly in the core STAC standard. They are all more intended to be a part of the HTML +pages that search engines crawl, so the logical place to do the integration is by leveraging a tool that generates HTML +from STAC like [STAC Browser](https://github.com/radiantearth/stac-browser/). STAC Browser has implemented a [mapping to +schema.org](https://github.com/radiantearth/stac-spec/issues/378) fields using JSON-LD, but the exact output is still being +refined. It is on the roadmap to add in more mapping and do more testing of search engines crawling the HTML pages. + +#### Deploying STAC Browser & stac.cloud + +There are a number of STAC Browser [examples on stacspec.org](https://stacspec.org/#examples), that are all deployed on +the [stac.cloud](http://stac.cloud) domain. Anyone with a public catalog is welcome to have a STAC Browser instance hosted +for free. But the stronger recommendation is to host your catalog's STAC Browser on your own domain, and to customize its +design to look and feel like your main web presence. The goal of stac.cloud is to bootstrap live web pages for catalogs, but +not to be *the* central hub. STAC aims to be decentralized, so each catalog should have its own location and just be +part of the wider web. + + +## Static to Dynamic best practices + +Many implementors are using static catalogs to be the reliable core of their dynamic services, or layering their STAC API +on top of any static catalog that is published. These are some recommendations on how to handle this: + +#### Ingestion and links + +Implementors have found that it's best to 'ingest' a static STAC into an internal datastore (often elasticsearch, but a +traditional database could work fine too) and then generate the full STAC API responses from that internal representation. +There are instances that have the API refer directly to the static STAC Items, but this only works well if the static STAC +catalog is an 'absolute published catalog'. So the recommendation is to always use absolute links - either in the static +published catalog, or to create new absolute links for the STAC search/ endpoint +responses, with the API's location at the base url. The /stac endpoint with the catalogs could either link directly +to the static catalog, or can follow the 'dynamic catalog layout' recommendations above with a new set of URL's. + +Ideally each `Item` would use its `links` to provide a reference back to the static location. The location of the static +item should be treated as the canonical location, as the generated API is more likely to move or be temporarily down. The +spec provides the `derived_from` rel attribute, which fits well enough, but `canonical` is likely the more appropriate one +as everything but the links should be the same. + +#### Keeping static and dynamic catalogs in sync with cloud notification and queue services + +There is a set of emerging practices to use services like Amazon's Simple Queue Service (SQS) and Simple Notification Service +(SNS) to keep catalogs in sync. There is a great [blog post on the CBERS STAC implementation on AWS](https://aws.amazon.com/blogs/publicsector/keeping-a-spatiotemporal-asset-catalog-stac-up-to-date-with-sns-sqs/). The core +idea is that a static catalog should emit a notification whenever it changes. The recommendation for SNS is to use the STAC +item JSON as the message body, with some attributes such as a scene’s datetime and geographic bounding box that allows +basic geographic filtering from listeners. + +The dynamic STAC API would then listen to the notifications and update its internal datastore whenever new data comes into +the static catalog. Implementors have had success using AWS Lambda to do a full 'serverless' updating of the elasticsearch +database, but it could just as easily be a server-based process. + + + diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 02f6549d6..2d9f10a9f 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -91,54 +91,25 @@ root catalog might be a sub-catalog of someone else's structure. The goal is for information and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are linked to across the web. -### Catalog Types - -The core Items and Catalogs of a SpatioTemporal Asset Catalog are designed for ease of implementation. -With the same core JSON documents and link structures it can be implemented in a way that is just files available online, -or easily implementable with modern REST service infrastructures. These represent two different types of catalogs, the -'static catalog' and the 'dynamic catalog', which can operate a bit differently though they can be treated the same by -clients. - -But any server can implement the same JSON and link structure, creating responses -dynamically as REST calls. These are referred to as 'dynamic catalogs'. - -#### Static Catalogs - -A main target for STAC has been object storage services like [Amazon S3](https://aws.amazon.com/s3/), -[Google Cloud Storage](https://cloud.google.com/storage/) and [Azure Storage](https://azure.microsoft.com/en-us/services/storage/), -so that users can stand up a full STAC implementation with static files. Implementations created with just files online -are referred to as 'static catalogs'. These include not just the cloud services, but any type of file server that is online. +There are a number of emerging 'best practices' for how to organize and implement good catalogs. These can be found in +the [best practices document](catalog-best-practices.md), and include things like catalog layout, use of self links, +publishing catalogs, and more. This specification is designed for maximum flexbility, but the best practices provide +guidance for good recommendations when implementing. -Static Catalogs tend to make extensive use of *sub-catalogs* to organize their Items in to sensible browsing structures, -as they can only have a single representation of their catalog, as the static nature means the structure is baked in. -While it is up to the implementor to organize the catalog, it is recommended to arrange the in a way that would make sense -for a human to browse a set of STAC Items in an intuitive matter. - -Static catalogs a recommended to be defined using the file name `catalog.json` to distinguish from item other JSON -type files. In order to support multiple catalogs, the recommended practice is to place the -`catalog.json` in namespaces "directories". For example: - -- current/catalog.json -- archive/catalog.json - -#### Dynamic Catalogs +### Catalog Types -Dynamic STAC Catalogs are those that generate their JSON responses programmatically instead of relying on a set of -already defined files. Typically a dynamic catalog implements the full [STAC API](../stac-api/) which enables -search of the Items indexed. But the `/stac/` endpoint returns the exact same `Catalog` and `Item` structures as a -static catalog, enabling the same discovery from people browsing and search engines crawling. But dynamic API's that -just seek to expose some data can also choose to only implement a Catalog the `/stac/` endpoint that returns dynamically. -For example a Content Management Service like Drupal or an Open Data Catalog like CKAN could choose to expose its content -as linked STAC Items by implementing a dynamic catalog. +Though it is technically an implementation detail outside the scope of the core specification, it is worth mentioning +that implementations generally fall into two different 'types': -One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same `Items` in -different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by -providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location -(or at least use a `rel` link that indicates the location of the canonical one. +* **Static Catalogs** can be implemented as simply files online, often stored in an cloud storage service like [Amazon S3](https://aws.amazon.com/s3/). +or [Google Cloud Storage](https://cloud.google.com/storage/). +The core JSON documents and link structures are encoded in the file, and work as long as things are structured properly. +* **Dynamic Catalogs** are implemented in software, returning the JSON documents and links dynamically. This is mostly +used when data holdings are already exposed through a dynamic interface, and STAC can be an alternate facade on the +same core database or search cluster. -The STAC API is also made to be compatible with WFS3, which has a set structure for the canonical location of its features. -STAC Items should use the WFS3 location as their canonical location, and then in the `/stac/` browse structure would just -link to those locations. +The two catalog types both implement the same fields and links, and can be treated as the same by clients. For more +details on the two types and how you might use them see the [Static and Dynamic Catalogs](catalog-best-practices.md#static-and-dynamic-catalogs) section of the best practices document. ## Catalog fields @@ -160,7 +131,7 @@ might look something like this: ```json { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "NAIP", "description": "Catalog of NAIP Imagery", "links": [ @@ -178,7 +149,7 @@ A typical '_child_' sub-catalog could look similar: ```json { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "NAIP", "description": "Catalog of NAIP Imagery - 30087", "links": [ @@ -207,7 +178,9 @@ with links. A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). -Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for a discussion on that topic. +Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) + for a discussion on that topic, as well as the [use of links](catalog-best-practices.md#use-of-links) section of the + catalog best practices document. #### Relation types @@ -215,8 +188,8 @@ The following types are commonly used as `rel` types in the Link Object of a STA | Type | Description | | ------- | ----------- | -| self | **REQUIRED.** _Absolute_ URL to the catalog file itself. This is required, to represent the location that the file can be found online. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC 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. | +| self | STRONGLY RECOMMENDED. _Absolute_ URL to the location that the catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | +| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | | parent | URL to the parent STAC Catalog or [Collection](../collection-spec/README.md). Non-root catalogs should include a link to their parent. | | child | URL to a child STAC Catalog or [Collection](../collection-spec/README.md). | | item | URL to a STAC [Item](../item-spec/). | diff --git a/catalog-spec/examples/catalog.json b/catalog-spec/examples/catalog.json index b736f10d9..96a20c35b 100644 --- a/catalog-spec/examples/catalog.json +++ b/catalog-spec/examples/catalog.json @@ -1,5 +1,5 @@ { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "sample", "title": "Sample catalog", "description": "This is a very basic sample catalog.", diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 82e175603..bf769f875 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "catalog.json#", "definitions": { "link": { @@ -40,7 +40,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "0.6.2" + "const": "0.7.0" }, "id": { "title": "Identifier", diff --git a/collection-spec/README.md b/collection-spec/README.md index f13458a44..cec8d4d61 100644 --- a/collection-spec/README.md +++ b/collection-spec/README.md @@ -24,11 +24,6 @@ structures and fields. **Schemas:** The schemas to validate the STAC Collection definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[collection.json](json-schema/collection.json)*. -## In the API directory - -**Dynamic Catalog OpenAPI Definition:** The [api-spec](../api-spec) directory contains OpenAPI definitions of the WFS3 `/collections` and `/collections/{collectionId}` -endpoints in the file [WFS3core+STAC.yaml](../api-spec/WFS3core+STAC.yaml.yaml). These endpoints are the dynamic versions of a STAC and WFS3 Collection. See - ## Schema Validation Instruction on schema validation for STAC Items can be found in the [validation instructions](validation/README.md). @@ -37,8 +32,8 @@ Instruction on schema validation for STAC Items can be found in the [validation STAC Collections are defined for flexibility. They only require a handful of fields, and implementors are free to add most any JSON field or object that they want via extensions. -Many fields originating from the [STAC Item spec](../item-spec/item-spec.md) can already be -reused using the [Commons extension](../extensions/commons/README.md). +Many fields originating from the [STAC Item spec](../item-spec/item-spec.md) can be +reused with the `properties` field. This flexibility and extensibility is a design goal, so that it is quite easy to implement a collection and be able to adapt it to most any data model. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 372924469..372370db7 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -4,9 +4,13 @@ The STAC Collection Specification defines a set of common fields to describe a g STAC Collections Specification extends the [STAC Catalog Spec](../catalog-spec/README.md) with additional fields to describe the whole dataset and the included set of items. It shares the same fields and therefore every Collection is also a valid Catalog. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. +A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO or SAR extension. Rather than including these common metadata fields on every Item, they can be provided in the `properties` of the STAC Collection that the STAC Items belong to. + A STAC collection can be represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. -* [Example (Sentinel 2)](examples/sentinel2.json) +* [Examples](examples/): + * Sentinel 2: A basic standalone example of a [Item](examples/sentinel2.json) without items. + * Landsat 8: A [Collection](examples/landsat-collection.json) that holds shared data from an [Item](examples/landsat-item.json). * [JSON Schema](json-schema/collection.json) - please see the [validation instructions](../validation/README.md) ## WARNING @@ -28,6 +32,7 @@ Implementations are encouraged, however, as good effort will be made to not chan | license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) or `proprietary` if the license is not on the SPDX license list. Proprietary licensed data SHOULD add a link to the license text, see the `license` relation type. | | providers | [Provider Object] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | extent | Extent Object | **REQUIRED.** Spatial and temporal extents. | +| properties | object | Common fields across referenced items. May also be used to describe standalone collections better that don't reference any items. See the section 'Common Fields' for more information. | | links | [Link Object] | **REQUIRED.** A list of references to other documents. | **stac_version**: It is not allowed to mix STAC versions. The root catalog or the root collection respectively MUST specify the implemented STAC version. Child Catalogs and child Collections MUST NOT specify a different STAC version. @@ -97,7 +102,7 @@ The following types are commonly used as `rel` types in the Link Object of a Col | Type | Description | | ------- | ------------------------------------------------------------ | -| self | **REQUIRED.** *Absolute* URL to the collection. This is required, to represent the location that the file can be found online. 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. | +| self | STRONGLY RECOMMENDED. _Absolute_ URL to the location that the collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | URL to the root STAC [Catalog](../catalog-spec/README.md) or Collection. Collections should include a link to their root, even if it's the root and points to itself. | | parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or Collection. Non-root collections should include a link to their parent. | | child | URL to a child STAC [Catalog](../catalog-spec/) or Collection. | @@ -107,12 +112,105 @@ The following types are commonly used as `rel` types in the Link Object of a Col **Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is _not_ a requirement for collections, but _recommended_. In contrast to catalogs, it is **REQUIRED** that items linked from a Collection MUST refer back to its Collection with the `collection` relation type. -## Extensions - -Important related extensions for the STAC Collection Specification: +### Common Fields and Standalone Collections + +The `properties` field in STAC collections can be used in two ways, either to **move common fields in Items to the parent Collection** or to describe **standalone Collections** better that don't reference any items. Any field that can be used under an Items `properties` can be removed and added to the Collection `properties`. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. + +To **move common fields in Items to the parent Collection**, the collection specification allows one to more fields that are common across all linked Items to be moved out of the respective Items and into the parent STAC Collection, from which the Items then inherit. This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always have an `eo:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellites that can be pointed will have varying `eo:off_nadir` values. This allows the data provider to define the set of metadata that defines the collection. While some metadata fields are more likely to be part of the common set, such as or `eo:instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. If a metadata field is specified in the Collection properties, it will be ignored in any Item that links to that Collection. This is important because a Collection is the metadata that is common across all Item objects. If a field is variable at all, it should not be part of the common fields. + +STAC Collections which don't link to any Item are called **standalone Collections**. To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by content extensions for Items. Whenever suitable, the `properties` are used in the same way as if they were common fields across theoretical Items. This makes much sense for fields such as `eo:platform` or `eo:epsg`, which are often the same for a whole collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. The data provider is free to decide, which fields are reasoable to be used. + +#### Merging common fields into a STAC Item + +To get the complete record of an Item (both individual and commons properties), the properties from the Collection can be merged with the Item. + +An incomplete Collection: +```json +{ + "id": "landsat-8-l1", + "title": "Landsat 8 L1", + "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", + "version": "0.1.0", + "extent": {...}, + "license": "PDDL-1.0", + "properties": { + "eo:gsd": 15, + "eo:platform": "landsat-8", + "eo:instrument": "OLI_TIRS", + "eo:off_nadir": 0, + "eo:bands": [ + { + "id": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + ... + ] + }, + "links": [...] +} +``` + +An incomplete item: +```json +{ + "type": "Feature", + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "bbox": [...], + "geometry": {...}, + "properties": { + "collection": "landsat-8-l1", + "datetime": "2018-10-01T01:08:32.033Z", + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431, + "landsat:path": 107, + "landsat:row": 18 + }, + "assets": {...}, + "links": [...] +} +``` + +The merged Item then looks like this: + +```json +{ + "type": "Feature", + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "bbox": [], + "geometry": {}, + "properties": { + "collection": "landsat-8-l1", + "datetime": "2018-10-01T01:08:32.033Z", + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431, + "landsat:path": 107, + "landsat:row": 18, + "eo:gsd": 15, + "eo:platform": "landsat-8", + "eo:constellation": "landsat-8", + "eo:instrument": "OLI_TIRS", + "eo:off_nadir": 0, + "eo:bands": [ + { + "id": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + ... + ] + }, + "assets": {...}, + "links": [...] +} +``` -* [Commons extension](../extensions/commons/README.md), which primarily allows to add shared Item metadata to Collections, - but could also be used to describe Collections better that are not referring to Items by adding additional fields from Item extensions. - Please note that this extension is only in '[proposal](../extensions/README.md#extension-maturity)' stage. +## Extensions The [extensions page](../extensions/README.md) gives a full overview about relevant extensions for STAC Collections. diff --git a/extensions/commons/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json similarity index 99% rename from extensions/commons/examples/landsat-collection.json rename to collection-spec/examples/landsat-collection.json index 5cb3ced1f..0945d761b 100644 --- a/extensions/commons/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -4,7 +4,7 @@ "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", "keywords": "landsat", "version": "0.1.0", - "stac_version": "0.6.2", + "stac_version": "0.7.0", "extent": { "spatial": [ -180, diff --git a/extensions/commons/examples/landsat-item.json b/collection-spec/examples/landsat-item.json similarity index 99% rename from extensions/commons/examples/landsat-item.json rename to collection-spec/examples/landsat-item.json index 0310bf43b..20ae91965 100644 --- a/extensions/commons/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -34,8 +34,8 @@ ] ] }, + "collection": "landsat-8-l1", "properties": { - "collection": "landsat-8-l1", "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, "eo:sun_azimuth": 168.8989761, diff --git a/collection-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json index e551e2c12..66fb91b69 100644 --- a/collection-spec/examples/sentinel2.json +++ b/collection-spec/examples/sentinel2.json @@ -1,5 +1,5 @@ { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "COPERNICUS/S2", "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-1C", "description": "Sentinel-2 is a wide-swath, high-resolution, multi-spectral\nimaging mission supporting Copernicus Land Monitoring studies,\nincluding the monitoring of vegetation, soil and water cover,\nas well as observation of inland waterways and coastal areas.\n\nThe Sentinel-2 data contain 13 UINT16 spectral bands representing\nTOA reflectance scaled by 10000. See the [Sentinel-2 User Handbook](https://sentinel.esa.int/documents/247904/685211/Sentinel-2_User_Handbook)\nfor details. In addition, three QA bands are present where one\n(QA60) is a bitmask band with cloud mask information. For more\ndetails, [see the full explanation of how cloud masks are computed.](https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-2-msi/level-1c/cloud-masks)\n\nEach Sentinel-2 product (zip archive) may contain multiple\ngranules. Each granule becomes a separate Earth Engine asset.\nEE asset ids for Sentinel-2 assets have the following format:\nCOPERNICUS/S2/20151128T002653_20151128T102149_T56MNN. Here the\nfirst numeric part represents the sensing date and time, the\nsecond numeric part represents the product generation date and\ntime, and the final 6-character string is a unique granule identifier\nindicating its UTM grid reference (see [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System)).\n\nFor more details on Sentinel-2 radiometric resoltuon, [see this page](https://earth.esa.int/web/sentinel/user-guides/sentinel-2-msi/resolutions/radiometric).\n", diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 9505de5a7..36a3438d3 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "collection.json#", "title": "STAC Collection Specification", "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", @@ -17,7 +17,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "0.6.2" + "const": "0.7.0" }, "id": { "title": "Identifier", @@ -112,6 +112,9 @@ }, "additionalProperties": true }, + "properties": { + "type": "object" + }, "links": { "type": "array", "items": { diff --git a/extensions/README.md b/extensions/README.md index e8bcc1ead..b6d7cd60a 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -41,20 +41,20 @@ A 'mature' classification level will likely be added once there are extensions t stable for over a year and are used in twenty or more implementations. -## List of community extensions +## List of content extensions + +An extension can add new fields to STAC entities (content extension), or can add new endpoints or behavior to the API (API extension). Below is a list of content extensions, while API extensions given under [api-spec](../api-spec/) in a folder for [API extensions](../api-spec/extensions/). | Extension Name (Prefix) | Scope | Description | Maturity | | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | -------- | | [Checksum](checksum/README.md) (`checksum`) | Item +Catalog +Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | -| [Commons](commons/README.md) (-) | Item +Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | | [Data Cube](datacube/README.md) (`cube`) | Item | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | | [Datetime Range](datetime-range//README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | | [EO](eo/README.md) (`eo`) | Item | 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, off nadir, sun angle + elevation, gsd and more. | *Pilot* | | [Point Cloud](pointcloud/README.md) (`pc`) | Item | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* | | [SAR](sar/README.md) (`sar`) | Item | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* | | [Single Item](single-item/README.md) (`item`) | Item | Provides a way to specify several fields in individual Items that usually reside on the collection-level such as license and providers. | *Proposal* | -| [Scientific](scientific/README.md) (`sci`) | Item | Scientific metadata is considered to be data that indicate from which publication a collection originates and how the collection itself should be cited or referenced. | *Proposal* | -| [Transaction](transaction/README.md) | API | Provides an API extension to support the creation, editing, and deleting of items on a specific WFS3 collection. | *Pilot* | +| [Scientific](scientific/README.md) (`sci`) | Item | Scientific metadata is considered to be data that indicate from which publication data originates and how the data itself should be cited or referenced. | *Proposal* | ## Third-party / vendor extensions diff --git a/extensions/checksum/schema.json b/extensions/checksum/schema.json index 566b2b82c..1e9b106ee 100644 --- a/extensions/checksum/schema.json +++ b/extensions/checksum/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "schema.json#", "type": "object", "title": "Checksum Extension Specification", diff --git a/extensions/commons/README.md b/extensions/commons/README.md deleted file mode 100644 index e66984237..000000000 --- a/extensions/commons/README.md +++ /dev/null @@ -1,133 +0,0 @@ -# Commons Extension Specification - -**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** - -A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../collection-spec/README.md) that the STAC Items belong to. - -- [Examples](examples/): - - Landsat 8: An [Item](examples/landsat-item.json) that uses the Commons extension to place shared data in a [Collection](examples/landsat-collection.json). -- JSON Schema (missing, PRs welcome) - -## WARNING - -**This is still an early version of the STAC Commons Spec, expect that there may be some changes before everything is finalized.** - -Implementations are encouraged, however, as good effort will be made to not change anything too drastically. Using the specification now will ensure that needed changes can be made before everything is locked in. So now is an ideal time to implement, as your feedback will be directly incorporated. - -## Item fields - -Unlike other extensions the Commons extension does not add any fields to a STAC Item, instead it allows one to move fields out of Item and into the parent STAC Collection, from which any member Item will inherit. Any field under an Items properties can be removed and added to the Collection properties. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. - -This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always has a `eo:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `eo:off_nadir` values. The Commons extension allow the data provider to define the set of metadata that defines the colleciton. While some metadata fields are more likely to be part of the common set, such as or `eo:instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. - -If a metadata field is specified in the Collection properties, it will be ignored in any Item that links to that Collection. This is important because a Collection is the metadata that is common across all Item objects. If a field is variable at all, it should not be part of the Commons. - -A Collection may not link to any Items, it may just be a definition of a Collection, in which case the Commons extension could still be used by defining any properties that would be shared by any member Item. - -### Linking to a STAC Collection - -All Items link to a Collection (this is part of the core STAC spec) and is specified in two places. One is a field under properties called `collection` which is the `id` of a STAC Collection record. The `collection` field provides an easy way for a user to search for any Items that belong in a specified Collection. - -A STAC Item must also provide a link to the STAC Collection using the `collection` rel type: - -``` -"links": [ - ... - { "rel": "collection", "href": "link/to/collection/record.json" } -] -``` - -### Using a STAC Collection - -To get the complete record of an Item (both individual and commons properties), the properties from the Collection can be merged with the Item. - -An incomplete Collection: -```json -{ - "id": "landsat-8-l1", - "title": "Landsat 8 L1", - "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", - "version": "0.1.0", - "extent": {...}, - "license": "PDDL-1.0", - "properties": { - "eo:gsd": 15, - "eo:platform": "landsat-8", - "eo:instrument": "OLI_TIRS", - "eo:off_nadir": 0, - "eo:bands": [ - { - "id": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - ... - ] - }, - "links": [...] -} -``` - -An incomplete item: -```json -{ - "type": "Feature", - "id": "LC08_L1TP_107018_20181001_20181001_01_RT", - "bbox": [...], - "geometry": {...}, - "properties": { - "collection": "landsat-8-l1", - "datetime": "2018-10-01T01:08:32.033Z", - "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, - "landsat:path": 107, - "landsat:row": 18 - }, - "assets": {...}, - "links": [...] -} -``` - -The merged Item then looks like this: - -```json -{ - "type": "Feature", - "id": "LC08_L1TP_107018_20181001_20181001_01_RT", - "bbox": [], - "geometry": {}, - "properties": { - "collection": "landsat-8-l1", - "datetime": "2018-10-01T01:08:32.033Z", - "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, - "landsat:path": 107, - "landsat:row": 18, - "eo:gsd": 15, - "eo:platform": "landsat-8", - "eo:constellation": "landsat-8", - "eo:instrument": "OLI_TIRS", - "eo:off_nadir": 0, - "eo:bands": [ - { - "id": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - ... - ] - }, - "assets": {...}, - "links": [...] -} -``` - -## Implementations - -[sat-api](https://github.com/sat-utils/sat-api/) has pioneered this functionality. You can see it in action at [https://sat-api.developmentseed.org/stac](https://sat-api.developmentseed.org/stac). \ No newline at end of file diff --git a/extensions/datacube/example.json b/extensions/datacube/example.json index 5b5bf7ffa..604b0f1b8 100644 --- a/extensions/datacube/example.json +++ b/extensions/datacube/example.json @@ -1,5 +1,5 @@ { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "datacube", "description": "Multi-dimensional data cube in a STAC collection.", "links": [ diff --git a/extensions/datacube/schema.json b/extensions/datacube/schema.json index c3dbacca3..4de893563 100644 --- a/extensions/datacube/schema.json +++ b/extensions/datacube/schema.json @@ -1,5 +1,6 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "schema.json#", "title": "Data Cube Extension", "type": "object", "description": "STAC Data Cube Extension", diff --git a/extensions/datetime-range/schema.json b/extensions/datetime-range/schema.json index c229540d3..1e700e8dc 100644 --- a/extensions/datetime-range/schema.json +++ b/extensions/datetime-range/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "schema.json#", "type": "object", "title": "STAC Datetime Range Extension Spec", diff --git a/extensions/eo/README.md b/extensions/eo/README.md index 9492f1069..fd73e8966 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -14,8 +14,9 @@ natural focus, and encourage other sensors to make their own extensions. Once th these fields will evolve to higher level extensions. In the meantime other implementations are welcome to reuse the names and definitions here. -It is not necessary, but recommended to use the [Commons extension](../commons/README.md) -(see chapter "Placing common fields in Collections"). +A lot of EO data will have common metadata across many Items. It is not necessary, but recommended +to place common fields in [STAC Collections](../../collection-spec/collection-spec.md#common-fields-and-standalone-collections). +The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. - [Example (Landsat 8)](example-landsat8.json) - [JSON Schema](schema.json) @@ -194,13 +195,8 @@ Planet example: A number of implementations listed on [STAC Implementations page](../../implementations.md) are making use of the core EO properties, including the SpaceNet, CBERS, sat-api and Planet implementations. This is not marked as more mature because -the eo:bands portion is still being fleshed out, with changes coming in 0.6.0. +the eo:bands portion is still being fleshed out. ## Extensions -The [extensions page](../README.md) gives an overview about related extensions. - -### Placing common fields in Collections -A lot of EO data will have common metadata across many Items. It is not necessary, but recommended -to use the [Commons extension](../commons/README.md) in combination with [STAC Collections](../../collection-spec/README.md). -The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. +The [extensions page](../README.md) gives an overview about related extensions. \ No newline at end of file diff --git a/extensions/eo/example-landsat8.json b/extensions/eo/example-landsat8.json index 6d751715e..4e310c587 100644 --- a/extensions/eo/example-landsat8.json +++ b/extensions/eo/example-landsat8.json @@ -236,6 +236,7 @@ "type": "image/jpeg" }, "index": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/index.html", "type": "text/html", "title": "HTML index page" } diff --git a/extensions/eo/schema.json b/extensions/eo/schema.json index c7c4200e2..ccd56bebd 100644 --- a/extensions/eo/schema.json +++ b/extensions/eo/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "stac-eo-extension.json#", "title": "EO Extension", "type": "object", diff --git a/extensions/sar/README.md b/extensions/sar/README.md index cb640bd25..2461f1cf4 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -5,7 +5,9 @@ This document explains the fields of the STAC Synthetic-Aperture Radar (SAR) Extension to a STAC Item. SAR data is considered to be data that represents a snapshot of the earth for a single date and time taken by a synthetic-aperture radar system such as Sentinel-1, RADARSAT or EnviSAT. -It is not necessary, but recommended to use the [Commons extension](../commons/README.md) (see chapter "Placing common fields in Collections"). +A lot of SAR data will have common metadata across many Items. It is not necessary, but recommended +to place common fields in [STAC Collections](../../collection-spec/collection-spec.md). +The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. - [Examples](examples/) (for example [Sentinel-1](examples/sentinel1.json) and [Envisat](examples/envisat.json)) - [JSON Schema](schema.json) @@ -14,32 +16,37 @@ It is not necessary, but recommended to use the [Commons extension](../commons/R **Note:** In the following specification *range* values are meant to be measured perpendicular to the flight path and *azimuth* values are meant to be measured parallel to the flight path. -| Field Name | Type | Description | -| --------------------- | ------------------ | ------------------------------------------------------------ | -| sar:platform | string | **REQUIRED.** Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., landsat-8, sentinel-2A), whereas for drones this would be a unique name for the drone. | -| sar:constellation | string | Name of the constellation that the platform belongs to. See below for details. | -| sar:instrument | string | **REQUIRED.** Name of the sensor used, although for Items which contain data from multiple sensors this could also name multiple sensors. | -| sar:instrument_mode | string | **REQUIRED.** The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, `WV` for "Wave mode" of Sentinel-1 and Envisat ASAR satellites. | -| sar:frequency_band | string | **REQUIRED.** The common name for the frequency band to make it easier to search for bands across instruments. See section "Common Frequency Band Names" for a list of accepted names. | -| sar:center_wavelength | number | The center wavelength of the instrument, in centimeters (cm). | -| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | -| sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combinations specified as array. See below for more details. | -| sar:bands | [Band Object] | This is a list of the available bands where each item is a Band Object. See section "Band Object" for details. | -| sar:pass_direction | string\|null | **REQUIRED.** Direction of the orbit, either `ascending`, `descending` or `null` if not relevant. | -| sar:type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | -| sar:resolution | [number] | The maximum ability to distinguish two adjacent targets, in meters (m). The first element of the array is the range resolution, the second element is the azimuth resolution. | -| sar:pixel_spacing | [number] | The distance between adjacent pixels, in meters (m). The first element of the array is the range pixel spacing, the second element is the azimuth pixel spacing. Strongly RECOMMENDED to be specified for products of type `GRD`. | -| sar:looks | [number] | The number of groups of signal samples (looks). The first element of the array must be the number of range looks, the second element must be the number of azimuth looks, the optional third element is the equivalent number of looks (ENL). | -| sar:absolute_orbit | [number\|[number]] | A list of absolute orbit numbers. See below for details. | -| sar:off_nadir | [number\|[number]] | Viewing angle(s). Measured in degrees (0-90). See below for details. | - - -**sar:absolute_orbit** lists absolute orbit numbers. Usually corresponds to the orbit count within the orbit cycle (e.g. ALOS, ERS-1/2, JERS-1, and RADARSAT-1, Sentinel-1). For UAVSAR it is the [Flight ID](http://uavsar.jpl.nasa.gov/cgi-bin/data.pl). A range can be specified as two element array in the array, e.g. `[25101, [25131, 25140]]` would be 25101 and 25131 to 25140. +| Field Name | Type | Description | +| ------------------------- | ------------- | ------------------------------------------------------------ | +| sar:platform | string | **REQUIRED.** Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., sentinel-1A). | +| sar:constellation | string | Name of the constellation that the platform belongs to. See below for details. | +| sar:instrument | string | **REQUIRED.** Name of the sensor used, although for Items which contain data from multiple sensors this could also name multiple sensors. | +| sar:instrument_mode | string | **REQUIRED.** The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, `WV` for "Wave mode" of Sentinel-1 and Envisat ASAR satellites. | +| sar:frequency_band | string | **REQUIRED.** The common name for the frequency band to make it easier to search for bands across instruments. See section "Common Frequency Band Names" for a list of accepted names. | +| sar:center_wavelength | number | The center wavelength of the instrument, in centimeters (cm). | +| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | +| sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. See below for more details. | +| sar:bands | [Band Object] | This is a list of the available bands where each item is a Band Object. See section "Band Object" for details. | +| sar:pass_direction | string\|null | **REQUIRED.** Direction of the orbit, either `ascending`, `descending` or `null` if not relevant. | +| sar:type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | +| sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | +| sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | +| sar:pixel_spacing_range | number | The range azimuth, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | +| sar:pixel_spacing_azimuth | number | The azimuth pixel spacing, which is the distance between adjacent pixels parallel to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | +| sar:looks_range | number | Number of range looks, which is the number of groups of signal samples (looks) perpendicular to the flight path. | +| sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. | +| sar:looks_equivalent_number | number | The equivalent number of looks (ENL). | +| sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. +| sar:absolute_orbit | integer | An absolute orbit number associated with the acquisition. See below for details. | +| sar:relative_orbit | integer | A relative orbit number associated with the acquisition. See below for details. | +| sar:incidence_angle | number | The center incidence angle is the angle defined by the incident radar beam at the scene center and the vertical (normal) to the intercepting surface. Measured in degrees (0-90). | + +**sar:absolute_orbit** usually corresponds to the number of orbits elapsed since satellite launch (e.g. ALOS, ERS-1/2, JERS-1, RADARSAT-1 and Sentinel-1). For airborne SAR such as UAVSAR it can be the [Flight ID](http://uavsar.jpl.nasa.gov/cgi-bin/data.pl) or a similar concept. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead. + +**sar:relative_orbit** is a count of orbits from 1 to the number of orbits contained in a repeat cycle, where relative orbit 1 starts from a defined reference for a given satellite. This property is usually not set for airborne SAR such as UAVSAR. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead. **sar:constellation** is the name of the group of satellites that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. Examples are the Sentinel-1 [constellation](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-1/Satellite_constellation), which has S1A, S1B, S1C and S1D and RADARSAT, which has RADARSAT-1 and RADARSAT-2. This field allows users to search for Sentinel-1 data, for example, without needing to specify which specific platform the data came from. -**sar:off_nadir** is the angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). A range can be specified as two element array in the array, e.g. `[20.1, [24.5, 30]]` would be 20.1 and 24.5 to 30. - **sar:polarization** specifies a single polarization or a polarization combination. For single polarized radars one of `HH`, `VV`, `HV` or `VH` must be set. Fully polarimetric radars add all four polarizations to the array. Dual polarized radars and alternating polarization add the corresponding polarizations to the array, for instance for `HH+HV` add both `HH` and `HV`. ### Common Frequency Band Names @@ -87,9 +94,4 @@ Asset definitions that contain band data should reference the band index. Each a The [extensions page](../README.md) gives an overview about related extensions, for example: -* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. - -### Placing common fields in Collections -A lot of SAR data will have common metadata across many Items. It is not necessary, but recommended -to use the [Commons extension](../commons/README.md) in combination with [STAC Collections](../../collection-spec/README.md). -The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. \ No newline at end of file +* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. \ No newline at end of file diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index a3fca2d79..131bdcc3d 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -23,14 +23,17 @@ "sar:instrument": "ASAR", "sar:instrument_mode": "GM", "sar:polarization": ["HH"], - "sar:resolution": [1000,1000], - "sar:pixel_spacing": [500,500], - "sar:looks": [3,4], + "sar:resolution_range": 1000, + "sar:resolution_azimuth": 1000, + "sar:pixel_spacing_range": 500, + "sar:pixel_spacing_azimuth": 500, + "sar:looks_range": 3, + "sar:looks_azimuth": 4, "sar:frequency_band": "C", "sar:center_wavelength": 5.623568898893265, "sar:center_frequency": 5.331, "sar:pass_direction": "descending", - "sar:absolute_orbit": [37747], + "sar:absolute_orbit": 37747, "sar:type": "GM1_1P", "sar:bands": [ { diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 7582e1492..8d14acbe5 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -23,14 +23,19 @@ "sar:instrument": "C-SAR", "sar:instrument_mode": "EW", "sar:polarization": ["HH"], - "sar:resolution": [50,50], - "sar:pixel_spacing": [25,25], - "sar:looks": [3,1,2.7], + "sar:resolution_range": 50, + "sar:resolution_azimuth": 50, + "sar:pixel_spacing_range": 25, + "sar:pixel_spacing_azimuth": 25, + "sar:looks_range": 3, + "sar:looks_azimuth": 1, + "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", "sar:center_wavelength": 5.546576466235, "sar:center_frequency": 5.405, "sar:pass_direction": "ascending", - "sar:absolute_orbit": [24430], + "sar:absolute_orbit": 24430, + "sar:relative_orbit": 33, "sar:type": "GRD", "sar:bands": [ { diff --git a/extensions/sar/schema.json b/extensions/sar/schema.json index 5eba2a0b9..61472a426 100644 --- a/extensions/sar/schema.json +++ b/extensions/sar/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "schema.json#", "title": "SAR Extension", "type": "object", @@ -81,7 +81,7 @@ "title": "Name of the band", "type": "string" }, - "common_name": { + "description": { "title": "Description of the band", "type": "string" }, @@ -140,74 +140,63 @@ "SLC" ] }, - "sar:resolution": { - "title": "Resolution (m)", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } + "sar:resolution_range": { + "title": "Resolution range (m)", + "type": "number", + "minimum": 0 }, - "sar:pixel_spacing": { - "title": "Pixel spacing (m)", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } + "sar:resolution_azimuth": { + "title": "Resolution azimuth (m)", + "type": "number", + "minimum": 0 }, - "sar:looks": { - "title": "Groups of signal samples (looks)", - "type": "array", - "minItems": 2, - "maxItems": 3, - "items": { - "type": "number", - "minimum": 0 - } + "sar:pixel_spacing_range": { + "title": "Pixel spacing range (m)", + "type": "number", + "minimum": 0 + }, + "sar:pixel_spacing_azimuth": { + "title": "Pixel spacing azimuth (m)", + "type": "number", + "minimum": 0 + }, + "sar:looks_range": { + "title": "Looks range", + "type": "integer", + "minimum": 0 + }, + "sar:looks_azimuth": { + "title": "Looks azimuth", + "type": "integer", + "minimum": 0 + }, + "sar:looks_equivalent_number": { + "title": "Equivalent number of looks (ENL)", + "type": "number", + "minimum": 0 + }, + "sar:observation_direction": { + "title": "Antenna pointing direction", + "type": "string", + "enum": [ + "left", + "right" + ] }, "sar:absolute_orbit": { "title": "Absolute orbit numbers", - "type": "array", - "minItems": 1, - "items": { - "type": [ - "number", - "array" - ], - "minimum": 0, - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } - } + "type": "integer", + "minimum": 0 }, - "sar:off_nadir": { - "title": "Viewing angles", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": [ - "number", - "array" - ], - "minimum": 0, - "maximum": 90, - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0, - "maximum": 90 - } - } + "sar:relative_orbit": { + "type": "integer", + "minimum": 1 + }, + "sar:incidence_angle": { + "title": "Center incidence angle", + "type": "number", + "minimum": 0, + "maximum": 90 } } } diff --git a/extensions/scientific/README.md b/extensions/scientific/README.md index 7b471db5c..3508eb66f 100644 --- a/extensions/scientific/README.md +++ b/extensions/scientific/README.md @@ -11,8 +11,7 @@ can be registered at registration agencies affiliated with the [International DOI Foundation](https://www.doi.org/). As these scientific information are often closely bound to the collection level and therefore are shared across all items, -it is recommended to use the [Commons extension](../commons/README.md) to add the fields to a corresponding -[STAC Collection](../../collection-spec/README.md). +it is recommended to add the fields to a corresponding [STAC Collection](../../collection-spec/README.md). - [Example (Collection)](example-merraclim.json) - [JSON Schema](schema.json) diff --git a/extensions/scientific/example-merraclim.json b/extensions/scientific/example-merraclim.json index 5bffc2e74..88facb375 100644 --- a/extensions/scientific/example-merraclim.json +++ b/extensions/scientific/example-merraclim.json @@ -1,5 +1,5 @@ { - "stac_version": "0.6.2", + "stac_version": "0.7.0", "id": "MERRAclim", "description": "MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling.", "keywords": [ diff --git a/extensions/scientific/schema.json b/extensions/scientific/schema.json index 9637298bc..46927b32d 100644 --- a/extensions/scientific/schema.json +++ b/extensions/scientific/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "schema.json#", "type": "object", "title": "STAC Scientific Extension Spec", diff --git a/extensions/single-item/schema.json b/extensions/single-item/schema.json index 71d979b7f..dd3ad3e84 100644 --- a/extensions/single-item/schema.json +++ b/extensions/single-item/schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "schema.json#", "type": "object", "title": "Single Item Extension", diff --git a/extensions/transaction/WFS3core+STAC+transaction-merge.yaml b/extensions/transaction/WFS3core+STAC+transaction-merge.yaml deleted file mode 100644 index 2045b48e4..000000000 --- a/extensions/transaction/WFS3core+STAC+transaction-merge.yaml +++ /dev/null @@ -1 +0,0 @@ -!!files_merge_append ["../../api-spec/definitions/STAC-standalone.yaml", "../../api-spec/definitions/WFS3core.fragment.yaml", "../../api-spec/definitions/STAC-collections.fragment.yaml", "transaction-fragment.yaml"] \ No newline at end of file diff --git a/extensions/transaction/package-lock.json b/extensions/transaction/package-lock.json deleted file mode 100644 index d8fe5473b..000000000 --- a/extensions/transaction/package-lock.json +++ /dev/null @@ -1,73 +0,0 @@ -{ - "name": "transaction-extension", - "version": "1.0.0", - "lockfileVersion": 1, - "requires": true, - "dependencies": { - "argparse": { - "version": "1.0.10", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", - "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", - "requires": { - "sprintf-js": "~1.0.2" - } - }, - "cliclopts": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/cliclopts/-/cliclopts-1.1.1.tgz", - "integrity": "sha1-aUMcfLWvcjd0sNORG0w3USQxkQ8=" - }, - "esprima": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" - }, - "js-yaml": { - "version": "3.12.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.12.0.tgz", - "integrity": "sha512-PIt2cnwmPfL4hKNwqeiuz4bKfnzHTBv6HyVgjahA6mPLwPDzjDWrplJBMjHUFxku/N3FlmrbyPclad+I+4mJ3A==", - "requires": { - "argparse": "^1.0.7", - "esprima": "^4.0.0" - } - }, - "lodash.isarray": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/lodash.isarray/-/lodash.isarray-4.0.0.tgz", - "integrity": "sha1-KspJayjEym1yZxUxNZDALm6jRAM=" - }, - "lodash.merge": { - "version": "4.6.1", - "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.1.tgz", - "integrity": "sha512-AOYza4+Hf5z1/0Hztxpm2/xiPZgi/cjMqdnKTUWTBSKchJlxXXuUSxCCl8rJlf4g6yww/j6mA8nC8Hw/EZWxKQ==" - }, - "lodash.mergewith": { - "version": "4.6.1", - "resolved": "https://registry.npmjs.org/lodash.mergewith/-/lodash.mergewith-4.6.1.tgz", - "integrity": "sha512-eWw5r+PYICtEBgrBE5hhlT6aAa75f411bgDz/ZL2KZqYV03USvucsxcHUIlGTDTECs1eunpI7HOV7U+WLDvNdQ==" - }, - "minimist": { - "version": "1.2.0", - "resolved": "http://registry.npmjs.org/minimist/-/minimist-1.2.0.tgz", - "integrity": "sha1-o1AIsg9BOD7sH7kU9M1d95omQoQ=" - }, - "sprintf-js": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", - "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=" - }, - "yaml-files": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/yaml-files/-/yaml-files-1.1.0.tgz", - "integrity": "sha512-xH7LB14u8QWt7pfc3C+OTH3vI8YdcwdD+RZ6BiO5X9BqsAOsY8Q5KhPun7q9SkEBbMLZW5ET7sHvhE4oj5gleA==", - "requires": { - "cliclopts": "^1.1.1", - "js-yaml": "^3.6.1", - "lodash.isarray": "^4.0.0", - "lodash.merge": "^4.6.0", - "lodash.mergewith": "^4.6.1", - "minimist": "^1.2.0" - } - } - } -} diff --git a/extensions/transaction/package.json b/extensions/transaction/package.json deleted file mode 100644 index 056def92e..000000000 --- a/extensions/transaction/package.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "transaction-extension", - "version": "1.0.0", - "description": "Generate STAC openapi defintions from fragments.", - "repository": "https://github.com/radiantearth/stac-spec", - "license": "Apache-2.0", - "scripts": { - "generate": "yaml-files WFS3core+STAC+transaction-merge.yaml WFS3core+STAC+extensions.yaml" - }, - "dependencies": { - "yaml-files": "^1.1.0" - } -} \ No newline at end of file diff --git a/how-to-help.md b/how-to-help.md index 8df533ff4..319c2da14 100644 --- a/how-to-help.md +++ b/how-to-help.md @@ -1,6 +1,6 @@ ## Introduction -The SpatioTemproal Asset Catalog is a specification to help interoperability, but the key to achieve that goal is a community +The SpatioTemporal Asset Catalog is a specification to help interoperability, but the key to achieve that goal is a community of like-minded collaborators who are building software and exposing data in a standard way. The specification is really the result of that collaboration, and the aim is to provide a flexible base that others can extend and innovate on top of. If others in the community create similar functionality with their geospatial access API's then the community will hopefully diff --git a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json index 6b1537a2c..f20efedbc 100755 --- a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json +++ b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json @@ -46,6 +46,7 @@ "cbers:path": 177, "cbers:row": 106 }, + "collection": "CBERS_4_MUX", "links": [ { "rel": "self", diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 198283405..f963690dd 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -80,6 +80,7 @@ "dg:product": "WORLDVIEW02_LV1B", "datetime": "2015-11-09T18:04:46.000Z" }, + "collection": "dg_worldview02", "links": [ { "rel": "self", diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json index 5d19273f6..17eb45472 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -28,6 +28,7 @@ "cs:sat_id": "CS3", "cs:product_level": "LV1B" }, + "collection": "CS3", "links": [ {"rel": "self", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json"}, {"rel": "thumbnail", "href":"thumbnail.png"}, diff --git a/item-spec/examples/sample.json b/item-spec/examples/sample.json index c4451540f..62b5b8dfe 100644 --- a/item-spec/examples/sample.json +++ b/item-spec/examples/sample.json @@ -17,6 +17,7 @@ "properties": { "datetime": "2016-05-03T13:21:30.040Z" }, + "collection": "CS3", "links": [ { "rel": "self", diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index 5ce8e0fe2..1e32e460d 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -1,6 +1,7 @@ { "type": "Feature", "id": "S2A_OPER_MSI_L2A_TL_SGS__20180524T190423_A015250_T26SKD_N02.08", + "collection": "sentinel-s2-l2a", "links": [ { "rel": "self", diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 49b823738..d8cb73214 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -6,8 +6,8 @@ a few required fields that identify the time range and assets of the item. An It granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial 'assets' - satellite imagery, derived data, DEM's, etc. -The same Item definition is used in both '[catalogs](../catalog-spec/README.md)' and -the '[/stac/search](../api-spec/README.md)' endpoint. Catalogs are simply sets of items that are linked online, +The same Item definition is used in both [STAC catalogs](../catalog-spec/README.md) and +the [`/stac/search`](../api-spec/README.md) endpoint. Catalogs are simply sets of items that are linked online, generally served by simple web servers and used for crawling data. The search endpoint enables dynamic queries, for example selecting all Items in Hawaii on June 3, 2015, but the results they return are FeatureCollections of items. @@ -36,15 +36,16 @@ incorporated. This object describes a STAC Item. The fields `id`, `type`, `bbox`, `geometry` and `properties` are inherited from GeoJSON. -| Field Name | Type | Description | -| ---------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | string | **REQUIRED.** Provider identifier. As most geospatial assets are already defined by some identification scheme by the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. | -| type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | +| Field Name | Type | Description | +| ---------- | -------------------------------------------------------------------------- | ----------- | +| id | string | **REQUIRED.** Provider identifier. As most geospatial assets are already defined by some identification scheme by the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. | +| type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | | geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) | **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). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Specified in Longitude/Latitude based on EPSG:4326. | -| bbox | [number] | **REQUIRED.** Bounding Box of the asset represented by this item. Specified in Longitude/Latitude based on EPSG:4326 - first two numbers are longitude and latitude of lower left corner, followed by longitude and latitude of upper right corner. This field enables more naive clients to easily index and search geospatially. Most software can easily generate them for footprints. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. | -| properties | Properties Object | **REQUIRED.** A dictionary of additional metadata for the item. | -| links | [Link Object] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is required. | -| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. Some pre-defined keys are listed in the chapter 'Asset types'. | +| bbox | [number] | **REQUIRED.** Bounding Box of the asset represented by this item. Specified in Longitude/Latitude based on EPSG:4326 - first two numbers are longitude and latitude of lower left corner, followed by longitude and latitude of upper right corner. This field enables more naive clients to easily index and search geospatially. Most software can easily generate them for footprints. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. | +| properties | Properties Object | **REQUIRED.** A dictionary of additional metadata for the item. | +| links | [Link Object] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is required. | +| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. Some pre-defined keys are listed in the chapter 'Asset types'. | +| collection | string | The `id` of the STAC Collection this Item references to (see `collection` relation type below). This field is *required* if such a relation type is present. This field provides an easy way for a user to search for any Items that belong in a specified Collection. | **assets** should include the main asset, as well as any 'sidecar' files that are related and help a client make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.), @@ -77,27 +78,34 @@ datetime fields. This object describes a relationship with another entity. Data providers are advised to be liberal with the links section, to describe things like the catalog an item is in, related items, parent or -child items (modeled in different ways, like an 'acquisition' or derived data). The `self` link is -required as an absolute URL, to represent the location that the Item can be found online. It is -allowed to add additional fields such as a `title` and `type`. +child items (modeled in different ways, like an 'acquisition' or derived data). +It is allowed to add additional fields such as a `title` and `type`. | Field Name | Type | Description | | ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | | type | string | Media type of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | +#### Relative vs Absolute links + +Currently, the JSON schema for links does not require them to be formatted as URIs, to allow +implementors to provide relative links. In general, Catalog APIs should aim to provide absolute links +whenever possible. Static Catalogs are potentially more portable if they incorporate only +relative links, so that every link doesn't need to be rewritten when the data is copied. Additional +recommendations for particular ```rel``` types are given in the ```rel``` type description. + #### Relation types The following types are commonly used as `rel` types in the Link Object of an Item: | Type | Description | | ------------ | ------------------------------------------------------------ | -| self | **REQUIRED.** _Absolute_ URL to the item file itself. This is required, to represent the location that the file can be found online. 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. | +| self | STRONGLY RECOMMENDED. _Absolute_ URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | URL to the root STAC [Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | | parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | -| collection | STRONGLY RECOMMENDED. URL to a [Collection](../collection-spec/README.md), which may use the [Commons extension](../extensions/commons/README.md) and holds common fields of this and other Items (see chapter '[Collections](#Collections)' for more explanations). | +| collection | STRONGLY RECOMMENDED. URL to a [Collection](../collection-spec/README.md), which may hold [common fields](../collection-spec/collection-spec.md#common-fields-and-standalone-collections) of this and other Items (see chapter '[Collections](#Collections)' for more explanations). _Absolute_ URLs should be used whenever possible. | | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). @@ -106,20 +114,21 @@ A more complete list of possible 'rel' types can be seen at the [IANA page of Li that comes along for that. But the derived_from field is seen as a way to encourage fuller specs and at least start a linking structure that can be used as a jumping off point for more experiments in provenance tracking* -#### Relative vs Absolute links +#### Collections -Currently the JSON schema for links does not require a URI formatting, to give the option for -implementors to provide relative links. In general, Catalog API's should aim for absolute links -whenever possible. But Static Catalogs are potentially more portable if they can be implemented with -relative links, so that every link doesn't need to be rewritten when the data is copied. The `self` -link is required to be absolute. +Items are *strongly recommended* to provide a link to a STAC Collection definition. It is important as Collections provide additional information about a set of items, for example the license, provider and other information +giving context on the overall set of data that an individual Item is a part of. -#### Collections +If Items are part of a STAC Collection, the [STAC Collection spec *requires* Items to link back to the Collection](collection-spec/collection-spec.md#relation-types). +Linking back must happen in two places: -Items are *strongly recommended* to provide a link to a STAC Collection definition. It is important as Collections -provide additional information about a set of items, for example the license, provider and other information (see section 'Extensions') -giving context on the overall set of data that an individual Item is a part of. If Items are part of a STAC Collection, -the [STAC Collection spec *requires* Items to link back to the Collection](collection-spec/collection-spec.md#relation-types). +1. The field `collection` in an Item must be filled (see section 'Item fields'). It is the `id` of a STAC Collection. +2. An Item must also provide a link to the STAC Collection using the `collection` relation type (see section 'Relation types'): + ``` + "links": [ + { "rel": "collection", "href": "link/to/collection/record.json" } + ] + ``` ### Asset Object @@ -178,10 +187,6 @@ media type. There are emerging best practices, which in time will evolve in to specification extensions for particular domains or uses. -Optionally, common information shared across items can be split up into STAC Collections using the -[Commons extension](../extensions/commons/README.md). Please note that this extension is only in -'[proposal](../extensions/README.md#extension-maturity)' stage. - The [extensions page](../extensions/README.md) gives an overview about relevant extensions for STAC Items. ## Recommendations @@ -193,3 +198,11 @@ The core is space and time, but there are often other metadata attributes that a providers can fill it with tens or even hundreds of fields of metadata that is not recommended. If providers have lots of metadata then that should be linked to in the Asset Object or in a Link Object, or even a new Asset Object could be added that is potentially easier to parse. There is a lot of metadata that is only of relevance to advanced processing algorithms, and while that is important it should not be in the core STAC items. + +### HTML versions of Items + +It is recommended to have a complementary HTML version of each `Item` available for easy human consumption and search +engine crawlability. The exact nature of the HTML is not part of the specification, but it is recommended to use common +ecosystem tools like [STAC Browser](https://github.com/radiantearth/stac-browser) to generate it. More information on creating +HTML versions of STAC can be found in the [STAC on the Web section](../catalog-spec/catalog-best-practices.md#stac-on-the-web) +of the catalog best practices document. diff --git a/item-spec/json-schema/geojson.json b/item-spec/json-schema/geojson.json index 29ee55fae..ed60ba1d3 100644 --- a/item-spec/json-schema/geojson.json +++ b/item-spec/json-schema/geojson.json @@ -1,6 +1,6 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", - "id": "geojson.json#", + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "geojson.json#", "title": "GeoJSON Object", "type": "object", "description": diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 9a36f87d2..c85de58de 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "item.json#", "title": "STAC Item", "type": "object", @@ -69,6 +69,11 @@ "format": "date-time" } } + }, + "collection": { + "title": "Collection ID", + "description": "The ID of the STAC Collection this Item references to.", + "type": "string" } } } diff --git a/process.md b/process.md index 48c7f5075..536523bff 100644 --- a/process.md +++ b/process.md @@ -42,17 +42,14 @@ can not happen automatically. and there are no typos, errors, etc. * **Update the version numbers**: There are several places in the spec that use the version number in text or a link. These include the readme, and the openapi specs. Right now the best thing to do is just a search & replace. Hopefully in the future -there will be scripts or continuous integration to do this. -* **Swaggerhub release of OpenAPI Specs**: The spec uses [Swaggerhub](http://swaggerhub.com) to display more easily browsable -versions of the API specifications of the [standalone](https://app.swaggerhub.com/apis/cholmesgeo/STAC-standalone) and -[wfs3 integrated](https://app.swaggerhub.com/apis/cholmesgeo/STAC_WFS-example/) versions. These should be updated to the -lastest specs. *Note: currently on Chris Holmes can do this. This should change, ideally to not use swaggerhub and to just -have a continuous integration task that builds a browsable site*. +there will be scripts or continuous integration to do this. * **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements in the release. And anything in 'unreleased' section should move to the version of the spec to be released. * **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github repository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state of the spec. +* **Check Online API Docs**: Check to make sure the online API docs reflect the release at https://stacspec.org/STAC-api.html +and https://stacspec.org/STAC-ext-api.html (this step may go away once we are confident this works well) * **Release on Github**: The final step to create the release is to add a new 'release' on https://github.com/radiantearth/stac-spec/releases. This should use a tag like the others, with a 'v' prefix and then the release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to @@ -62,7 +59,8 @@ to post / promote it. #### Release Candidates -Before any major release there should be a 'release candidate' to ensure the wider community of implementors can try it out +Before any release that has *major* changes (made as a judgement call by the core contributors) there should be a 'release +candidate' to ensure the wider community of implementors can try it out and catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec version is good, so this step is essential if there are major changes. The release should proceed as normal, but called vX.Y.Z-RC1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations diff --git a/roadmap.md b/roadmap.md deleted file mode 100644 index 7684e316d..000000000 --- a/roadmap.md +++ /dev/null @@ -1,165 +0,0 @@ - -# STAC Roadmap - -This document lays out a rough prioritization for the evolution of the STAC specification and related extensions. -A small number initial priorities will likely be reflected in the core specs, but in the spirit of making small -spec pieces that are loosely coupled many will likely become extensions. Effort will also be made to break out -smaller reusable pieces. - -Soon the top priority items in this document will be migrated to the [issue tracker](https://github.com/radiantearth/stac-spec/issues) -and scheduled against 'releases'. Also included here are some more future design discussions. Nothing listed her is set in stone, and -the overall priority will likely shift as real world implementations come along and need additional functionality. The main -way the items on this roadmap will evolve and become part of the spec will be starting as software implementations with -spec changes discusses on a pull request, merging once there is community consensus. See also the -[how to help](how-to-help.md) document for the implementation plan that complements this roadmap. - -## Roadmap - -### Asset definitions - -Currently the 'Asset' items in the array only require a link to the asset, and contain an optional 'title' and media 'type'. -There is likely quite a bit more that can be standardized in a useful way - at the very least some optional fields to help providers -describe more of what they're doing. Another idea is to require a link to a 'product definition' that an asset must -implement, which would provide the needed fields. This would increase the burden on the client, to follow or cache -the definitions, but would also decrease the repetition of the same fields over and over again. There is additional -discussion on this topic in the [static catalog recommendations](catalog-spec/static-recommendations.md#asset-definition). -Part of this is also tracked in [Issue 23](https://github.com/radiantearth/stac-spec/issues/23) - -### Querying and Filtering - -The [STAC API](api-spec/) does not yet have a robust filtering mechanism, it just returns items. This was punted on -at the [boulder sprint](http://github.com/radiantearth/boulder-sprint), but is an essential feature. Ideally this is -in line with [WFS 3.0](https://github.com/opengeospatial/WFS_FES), but they have also not defined more robust querying. -Another idea is to use [ECQL](http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html) - but it could -probably benefit from being pulled out to a standard instead of just in the GeoTools documentation, and it is pretty -complicated to fully implement (though a subset could be good). Another source of inspiration is -[Backand queries](http://backand-docs.readthedocs.io/en/latest/apidocs/nosql_query_language/index.html). -[Issue #31](https://github.com/radiantearth/stac-spec/issues/31). - -### Catalog Definition - -The JSON that defines a 'Catalog' is not really specified right now. There needs to be thought on the required -and optional fields. And some decisions on the philosophy of what type of metadata should live in a Catalog -resource, as well as fleshing out more linked catalogs vs root catalogs, and things like inheritance of metadata. But -it is potentially a good place to put data that applies to all the Items in the catalog, things like in depth -contact information and license data. The individual items could then just reference the catalog they come -from instead of repeating each field. - -### Domain and Vendor extensions - -Ideally there is a way for domains (like Earth Observation / satellite imagery) or specific vendors to publish -more meta information about the additional fields they use. The STAC mechanisms should enable a full Item with -all the extra fields included to be self-describing, so clients could understand more than just the core fields. -This likely would involve ways of defining additional schemas, and ways to share those schemas and validate a -response against several schemas. This could be some additional mechanics in Catalog API (likely optional, to -not make a basic implementation too complicated), and also ways for static catalogs to link to schemas. It is -likely worth exploring things like linked data, http://schema.org and JSON-LD to see if they can be used to -leverage web best practices to share core schema definitions across different STAC implementations. - -The schema definition mechanism part of this is defined in [Issue 30](https://github.com/radiantearth/stac-spec/issues/30). - -### EO Extension - -The top priority for many of the initial STAC implementors is to share more fields between data than just -date and time. At the [boulder sprint](http://github.com/radiantearth/boulder-sprint) the metadata group -initially came up with around 20 fields to standardize. Most all of them were quite useful to satellite -imagery (and less useful for other data, which is why they didn't make the final cut for STAC core). It -is a goal to make that list an 'extension' for the domain, so that different vendors can share a single cloud -cover definition. Right now one might have parameters for maxCloudCover and minCloudCover ranging from 0 to 100, -another may have a 'cloud_cover' parameter that takes a value range from 0 to 1. - -Ideally the main fields that users utilize to search for imagery would have shared definitions that would be -used across all satellite imagery providers. After this core extension is established it would be great to -create more extensions for other data types, as well as downstream imagery products (mosaics, band mathed, -land cover, etc) - -### Additional rel Link definitions - -While there is liberal use of the 'rel' attribute on the STAC Item 'Links' there is little consensus definition. -It makes sense to extend the core definitions, but it would be good to standardize on at least some of the core -uses, as well as best practices. - -### Provenance & Duplication tracking - -It would likely be useful to leverage rel links to describe relationships like when an NDVI derived data product -in one catalog comes from another data that is referenced in another catalog. It might be able to use a 'rel'='source' -type link back to it. Similarly one can imagine STAC catalogs that are just duplications of other catalogs on -different clouds - indeed Landsat8 data is on USGS, Amazon and Google. It would be great if STAC could represent -that each of those is 'the same', and link to the others, so that algorithms could make a choice on which to use -based on their location. - -### Extension mechanisms - -There should be clearly documented ways to extend the core STAC specification for new interesting functionality, as -well as clearly documenting how to extend the core fields for domains and vendors in valid ways. -Many of these should likely have their own specification and even their own end point, but it could be useful for -a STAC catalog to at least report the other endpoints that are available for the data that is represented. - -### HTML - -To embrace the principles of the web in general, and the [Spatial Data on the Web Best Practices](https://w3c.github.io/sdw/bp/) -in particular, there should be a human-readable HTML web pages for all STAC `Items`. The core design was -to use links generously, which should easily populate a good HTML page. And a nice page would utilize the -thumbnail and potentially even a [cloud optimized geotiff](http://cogeo.org) asset with a dynamic tile -server to render a zoomable map on every STAC Item webpage. This may just be a set of best practices -instead of hard requirements, though it is likely worth specifying a few core things that each HTML -page should have, and recommendations on how to format links and implement microformats. [Issue #32](https://github.com/radiantearth/stac-spec/issues/32) - -### Align with microformats / linked data - -Following on from HTML versions of STAC we aim to align with the best practices of the 'linked data' community. -This will take more research on what exactly we should do. But likely candidates include defining [JSON-LD](https://json-ld.org/) -versions of the spec, leveraging http://schema.org or defining a similar canonical location for geospatial schemas, -and defining microformats to go in the html versions. - -### Additional extensions - -This item will hopefully continously happen, as real world implementations come online. But we should evolve the -schemas people define to become best practices and defined extensions. We may also need some 'type' -definitions to help clients more easily recognize known schemas. Candidates for additional extensions include -derived data (like NDVI), including even specific types of derived data that might add more information, mosiacs, -DEMs / DSMs, LiDAR, SAR, hyperspectral imagery, and many more. - -### Granular components - -It is likely worthwhile once things are more mature to pull out some small pieces from the core that could -be reused. Things like the queries on the Catalog API (which could be reused for like a stats API or -a subscription API), the 'filter' language used in the query, or the 'paging' mechanism to navigate through -GeoJSON results in a Catalog API. Effort should be made to pull those out and let others reuse them. - -### WFS 3.0 alignment. - -Since much of a STAC is very similar to general feature querying, and much of the approach (RESTful, JSON, -OpenAPI definition, etc) is also in line, we should try to align STAC (at least the Catalog API part) so -that it *is* a WFS 3.0. This will likely involve giving feedback to the [WFS 3.0](https://github.com/opengeospatial/WFS_FES) -group, utilizing their github. - -## Potential Extensions - -This section will list potential extensions that aren't really core, but would be cool additional services providing -value around the core. Many are things that one or two providers has needed to implement for their customers, and some -would be good to standardize and encourage. - -TODO: Figure out if this should break out into its own document. - -TODO: Port over most of the ideas from the extension [workstream](https://github.com/radiantearth/boulder-sprint/blob/master/workstreams/extensions/extensions-overview.md#questions-to-discuss) and [notes](https://github.com/radiantearth/boulder-sprint/blob/master/workstreams/extensions/extensions-notes.md) from the boulder sprint. - - - -#### Assets / Activation - -Some API's include an 'activation' mechanism so they don't have to store every data product, but can produce them on the fly -and cache them. A 'core' might just include data products that are already activated, to simplify the process some. But more -advanced API's likely need some mechanism to advertise that they 'could' make a certain data product, that it's available to -the user, but it will take more than a couple seconds to get a response. - -#### Saved Searches - -Another feature that some services offer is the ability to 'save' a given search, and then revisit it or get notifications of -it. That may make sense as its own little specification. - -#### Caching / Updating - -Just a quick selective dump on one of the extension topics. The main geo catalog paradigm that has never really worked seems to be that you'd send out requests to a number of different catalogs and then try to parse responses from all of them. It seems time to flip that model around, where there are catalogs that also crawl and cache other catalogs. Indeed the simplest catalog profile could not even offer up 'search' - it'd work as crawlable links and flat files hosted on a cloud storage bucket. - -But a more advanced catalog should offer up a way for other catalogs to subscribe to updates they care about and get notifications. An agriculture company might pull satellite imagery from 5 catalogs, but they only pull the corn belt in the US, where they do their analytics. So they could just have a 'caching catalog', that knows the canonical record is somewhere else (and refers to it). But it stays up to date, and is able to offer sub-second responses to searches on the cached catalogs. And indeed ideally ranks the searches across all the 5 catalogs. diff --git a/validation/README.md b/validation/README.md index 6713f726b..ce7f6856d 100644 --- a/validation/README.md +++ b/validation/README.md @@ -1,18 +1,27 @@ # STAC Schema Validation +Any JSON Schema validation tool can be used, just run the JSON data to test +against the various STAC schema, and be sure to include any remote schema +like the geojson.json schema in the testing. -Any JSON Schema validation tool can be used, just run the JSON data to test against the various STAC schema, and be sure to include any remote schema like the geojson.json schema in the testing. - -This directory includes installation instructions for a Python validator and a JavaScript validator. The python validator is more complete and the recommnded tool for validation. The Javascript validator has been deprecated and will be removed in the next release. +This directory includes installation instructions for a Python validator and +a JavaScript validator. The python validator is more complete and the +recommnded tool for validation. The Javascript validator has been deprecated +and will be removed in the next release. ## Python Validator -Install the validator from the [stac-validator](https://github.com/sparkgeo/stac-validator) repository and follow the instructions. -The validator can be run as a command line tool and will report on nested catalogs as well as single items. There is no need to specifically identify +Install the validator from the +[stac-validator](https://github.com/sparkgeo/stac-validator) repository and +follow the instructions. -``` -stac_validator.py --help +The validator can be run as a command line tool and will report on nested +catalogs as well as single items. There is no need to specifically identify +individual catalogs or items. + +### Usage +``` Description: Validate a STAC item or catalog against the STAC specification. Usage: @@ -26,10 +35,12 @@ Options: -h, --help Show this screen. --verbose Verbose output. [default: False] --timer Reports time to validate the STAC (seconds) +``` +E.g. -stac_validator.py https://earth-stac.s3.amazonaws.com/eo/landsat-8-l1/catalog.json -v latest - +```bash +$ stac_validator.py https://earth-stac.s3.amazonaws.com/eo/landsat-8-l1/catalog.json -v latest { "catalogs": { "valid": 1, @@ -44,57 +55,4 @@ stac_validator.py https://earth-stac.s3.amazonaws.com/eo/landsat-8-l1/catalog.js "invalid": 0 } } -``` - -## JavaScript Validator -### Initialization - -In this directory run: - -```bash -npm install -``` - -This installs node.js validation modules, in a node_modules directory created in this directory. - -### Validation - -In the following chapter there are commands to run a validation of any STAC against the JSON Schema. - -**Warning:** Not all validation is fully complete. For items, the validator does not yet check for `self` -links. The `href` checking is probably too loose right now, it just checks for a string, see the -'relative vs absolute links' section in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for reasons why. - -### Catalogs - -To run the validation for a catalog file: - -```bash -npm run validate_catalog -- -d ../catalog-spec/examples/catalog.json -``` - -### Collections - -To run the validation for a collection file: - -```bash -npm run validate_collection -- -d ../collection-spec/examples/sentinel2.json -``` - -### Extensions - -To run the validation for an extension: - -```bash -npm run validate_extension -- -s ../extensions/scientific/schema.json -d ../extensions/scientific/example-merraclim.json -``` - -This example runs the validation for the scientific extension, please change the `-s` (schema file) and `-d` (data file) accordingly. - -### Items - -To run the validation for an item file: - -```bash -npm run validate_item -- -d ../item-spec/examples/sample.json -``` +``` \ No newline at end of file diff --git a/validation/package-lock.json b/validation/package-lock.json deleted file mode 100644 index 88a5b2091..000000000 --- a/validation/package-lock.json +++ /dev/null @@ -1,299 +0,0 @@ -{ - "name": "STAC_validation", - "version": "0.6.2", - "lockfileVersion": 1, - "requires": true, - "dependencies": { - "@types/commander": { - "version": "2.12.2", - "resolved": "https://registry.npmjs.org/@types/commander/-/commander-2.12.2.tgz", - "integrity": "sha512-0QEFiR8ljcHp9bAbWxecjVRuAMr16ivPiGOw6KFQBVrVd0RQIcM3xKdRisH2EDWgVWujiYtHwhSkSUoAAGzH7Q==", - "requires": { - "commander": "*" - } - }, - "@types/semver": { - "version": "5.5.0", - "resolved": "https://registry.npmjs.org/@types/semver/-/semver-5.5.0.tgz", - "integrity": "sha512-41qEJgBH/TWgo5NFSvBCJ1qkoi3Q6ONSF2avrHq1LVEZfYpdHmj0y9SuTK+u9ZhG1sYQKBL1AWXKyLWP4RaUoQ==" - }, - "abbrev": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", - "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" - }, - "ajv": { - "version": "5.5.2", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-5.5.2.tgz", - "integrity": "sha1-c7Xuyj+rZT49P5Qis0GtQiBdyWU=", - "requires": { - "co": "^4.6.0", - "fast-deep-equal": "^1.0.0", - "fast-json-stable-stringify": "^2.0.0", - "json-schema-traverse": "^0.3.0" - } - }, - "ajv-cli": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/ajv-cli/-/ajv-cli-2.1.0.tgz", - "integrity": "sha1-JvlC3fSx0U08Y5yyjbgH8CyjeHw=", - "requires": { - "ajv": "^5.0.0", - "ajv-pack": "^0.3.0", - "fast-json-patch": "^0.5.6", - "glob": "^7.0.3", - "json-schema-migrate": "^0.2.0", - "minimist": "^1.2.0" - } - }, - "ajv-pack": { - "version": "0.3.1", - "resolved": "https://registry.npmjs.org/ajv-pack/-/ajv-pack-0.3.1.tgz", - "integrity": "sha1-tyxNQhnjko5ihC10Le2Tv1B5ZWA=", - "requires": { - "js-beautify": "^1.6.4", - "require-from-string": "^1.2.0" - } - }, - "balanced-match": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", - "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" - }, - "brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "requires": { - "balanced-match": "^1.0.0", - "concat-map": "0.0.1" - } - }, - "co": { - "version": "4.6.0", - "resolved": "https://registry.npmjs.org/co/-/co-4.6.0.tgz", - "integrity": "sha1-bqa989hTrlTMuOR7+gvz+QMfsYQ=" - }, - "commander": { - "version": "2.17.1", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.17.1.tgz", - "integrity": "sha512-wPMUt6FnH2yzG95SA6mzjQOEKUU3aLaDEmzs1ti+1E9h+CsrZghRlqEM/EJ4KscsQVG8uNN4uVreUeT8+drlgg==" - }, - "concat-map": { - "version": "0.0.1", - "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", - "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" - }, - "config-chain": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/config-chain/-/config-chain-1.1.11.tgz", - "integrity": "sha1-q6CXR9++TD5w52am5BWG4YWfxvI=", - "requires": { - "ini": "^1.3.4", - "proto-list": "~1.2.1" - } - }, - "editorconfig": { - "version": "0.15.0", - "resolved": "https://registry.npmjs.org/editorconfig/-/editorconfig-0.15.0.tgz", - "integrity": "sha512-j7JBoj/bpNzvoTQylfRZSc85MlLNKWQiq5y6gwKhmqD2h1eZ+tH4AXbkhEJD468gjDna/XMx2YtSkCxBRX9OGg==", - "requires": { - "@types/commander": "^2.11.0", - "@types/semver": "^5.4.0", - "commander": "^2.11.0", - "lru-cache": "^4.1.1", - "semver": "^5.4.1", - "sigmund": "^1.0.1" - } - }, - "fast-deep-equal": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-1.1.0.tgz", - "integrity": "sha1-wFNHeBfIa1HaqFPIHgWbcz0CNhQ=" - }, - "fast-json-patch": { - "version": "0.5.7", - "resolved": "http://registry.npmjs.org/fast-json-patch/-/fast-json-patch-0.5.7.tgz", - "integrity": "sha1-taj0nSWWJFlu+YuHLz/aiVtNhmU=" - }, - "fast-json-stable-stringify": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.0.0.tgz", - "integrity": "sha1-1RQsDK7msRifh9OnYREGT4bIu/I=" - }, - "fs.realpath": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", - "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" - }, - "glob": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.3.tgz", - "integrity": "sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ==", - "requires": { - "fs.realpath": "^1.0.0", - "inflight": "^1.0.4", - "inherits": "2", - "minimatch": "^3.0.4", - "once": "^1.3.0", - "path-is-absolute": "^1.0.0" - } - }, - "inflight": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", - "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=", - "requires": { - "once": "^1.3.0", - "wrappy": "1" - } - }, - "inherits": { - "version": "2.0.3", - "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.3.tgz", - "integrity": "sha1-Yzwsg+PaQqUC9SRmAiSA9CCCYd4=" - }, - "ini": { - "version": "1.3.5", - "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.5.tgz", - "integrity": "sha512-RZY5huIKCMRWDUqZlEi72f/lmXKMvuszcMBduliQ3nnWbx9X/ZBQO7DijMEYS9EhHBb2qacRUMtC7svLwe0lcw==" - }, - "js-beautify": { - "version": "1.8.1", - "resolved": "https://registry.npmjs.org/js-beautify/-/js-beautify-1.8.1.tgz", - "integrity": "sha512-e6Ij+fcwlnhxwfEWH148AV240ocW6z6LTZtWc9V7QEOUMu7pe2EINYbO1sM4GPHFwTVWMUWBCXGgsJGRpaQPLQ==", - "requires": { - "config-chain": "~1.1.5", - "editorconfig": "^0.15.0", - "mkdirp": "~0.5.0", - "nopt": "~4.0.1" - } - }, - "json-schema-migrate": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/json-schema-migrate/-/json-schema-migrate-0.2.0.tgz", - "integrity": "sha1-ukelsAcvxyOWRg4b1gtE1SF4u8Y=", - "requires": { - "ajv": "^5.0.0" - } - }, - "json-schema-traverse": { - "version": "0.3.1", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.3.1.tgz", - "integrity": "sha1-NJptRMU6Ud6JtAgFxdXlm0F9M0A=" - }, - "lru-cache": { - "version": "4.1.3", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-4.1.3.tgz", - "integrity": "sha512-fFEhvcgzuIoJVUF8fYr5KR0YqxD238zgObTps31YdADwPPAp82a4M8TrckkWyx7ekNlf9aBcVn81cFwwXngrJA==", - "requires": { - "pseudomap": "^1.0.2", - "yallist": "^2.1.2" - } - }, - "minimatch": { - "version": "3.0.4", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", - "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", - "requires": { - "brace-expansion": "^1.1.7" - } - }, - "minimist": { - "version": "1.2.0", - "resolved": "http://registry.npmjs.org/minimist/-/minimist-1.2.0.tgz", - "integrity": "sha1-o1AIsg9BOD7sH7kU9M1d95omQoQ=" - }, - "mkdirp": { - "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", - "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", - "requires": { - "minimist": "0.0.8" - }, - "dependencies": { - "minimist": { - "version": "0.0.8", - "resolved": "http://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz", - "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=" - } - } - }, - "nopt": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/nopt/-/nopt-4.0.1.tgz", - "integrity": "sha1-0NRoWv1UFRk8jHUFYC0NF81kR00=", - "requires": { - "abbrev": "1", - "osenv": "^0.1.4" - } - }, - "once": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", - "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=", - "requires": { - "wrappy": "1" - } - }, - "os-homedir": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/os-homedir/-/os-homedir-1.0.2.tgz", - "integrity": "sha1-/7xJiDNuDoM94MFox+8VISGqf7M=" - }, - "os-tmpdir": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz", - "integrity": "sha1-u+Z0BseaqFxc/sdm/lc0VV36EnQ=" - }, - "osenv": { - "version": "0.1.5", - "resolved": "https://registry.npmjs.org/osenv/-/osenv-0.1.5.tgz", - "integrity": "sha512-0CWcCECdMVc2Rw3U5w9ZjqX6ga6ubk1xDVKxtBQPK7wis/0F2r9T6k4ydGYhecl7YUBxBVxhL5oisPsNxAPe2g==", - "requires": { - "os-homedir": "^1.0.0", - "os-tmpdir": "^1.0.0" - } - }, - "path-is-absolute": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", - "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=" - }, - "proto-list": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/proto-list/-/proto-list-1.2.4.tgz", - "integrity": "sha1-IS1b/hMYMGpCD2QCuOJv85ZHqEk=" - }, - "pseudomap": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/pseudomap/-/pseudomap-1.0.2.tgz", - "integrity": "sha1-8FKijacOYYkX7wqKw0wa5aaChrM=" - }, - "require-from-string": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-1.2.1.tgz", - "integrity": "sha1-UpyczvJzgK3+yaL5ZbZJu+5jZBg=" - }, - "semver": { - "version": "5.5.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.5.1.tgz", - "integrity": "sha512-PqpAxfrEhlSUWge8dwIp4tZnQ25DIOthpiaHNIthsjEFQD6EvqUKUDM7L8O2rShkFccYo1VjJR0coWfNkCubRw==" - }, - "sigmund": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/sigmund/-/sigmund-1.0.1.tgz", - "integrity": "sha1-P/IfGYytIXX587eBhT/ZTQ0ZtZA=" - }, - "wrappy": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", - "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=" - }, - "yallist": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/yallist/-/yallist-2.1.2.tgz", - "integrity": "sha1-HBH5IY8HYImkfdUS+TxmmaaoHVI=" - } - } -} diff --git a/validation/package.json b/validation/package.json deleted file mode 100644 index f094a775a..000000000 --- a/validation/package.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "name": "stac_validation", - "description": "Package to validate STAC items, catalogs and collections.", - "version": "0.6.2", - "author": "STAC Team", - "license": "Apache-2.0", - "repository": "https://github.com/radiantearth/stac-spec", - "dependencies": { - "ajv-cli": "^2.1.0" - }, - "scripts": { - "validate_item": "node_modules/.bin/ajv validate -s ../item-spec/json-schema/item.json -r ../item-spec/json-schema/geojson.json --verbose", - "validate_extension": "node_modules/.bin/ajv validate --verbose", - "validate_catalog": "node_modules/.bin/ajv validate -s ../catalog-spec/json-schema/catalog.json -r ../item-spec/json-schema/geojson.json --verbose", - "validate_collection": "node_modules/.bin/ajv validate -s ../collection-spec/json-schema/collection.json --verbose" - } -}