Merge pull request #706 from radiantearth/dev

Release 0.9.0-rc1 to master

.circleci/config.yml

@@ -3,7 +3,7 @@ jobs:
   build:
     working_directory: ~/stac
     docker:
-      - image: circleci/python:3.6.4
+      - image: circleci/python:3.6.9
 
     steps:
       - checkout
@@ -13,6 +13,10 @@ jobs:
           name: install
           command: |
             pip install stac-validator
+            sudo apt-get install curl software-properties-common
+            curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
+            sudo apt-get install -y nodejs
+            sudo npm install -g remark-cli remark-validate-links
       - run:
           name: validate
           command: |
@@ -25,3 +29,4 @@ jobs:
             stac_validator item-spec/examples/landsat8-sample.json
             stac_validator item-spec/examples/digitalglobe-sample.json
             stac_validator item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json
+            remark -f -u validate-links .

CHANGELOG.md

@@ -6,6 +6,67 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+## [v0.9.0-rc1] - 2020-01-06
+
+### Added
+- ItemCollection requires `stac_version` field, `stac_extensions` has also been added
+- A `description` field has been added to Item assets (also Asset definitions extension). 
+- Field `mission` to [Common Metadata fields](item-spec/common-metadata.md).
+- Extensions:
+    - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections
+    - Data Cube extension can be used in Collections, added new field `description`
+    - Added `description` and `roles` fields to the Asset in the [Asset Extension](extensions/asset/README.md)
+    - Projection Extension to describe Items with Assets that have an associated geospatial projection.
+- STAC API:
+    - Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification
+    - Run `npm run serve` or `npm run serve-ext` to quickly render development versions of the OpenAPI spec in the browser.
+
+### Changed
+- Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html)
+- Collection field `property` and the merge ability moved to a new extension 'Commons'
+- Added attribute `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`.
+- Updated API yaml to clarify bbox filter should be implemented without brackets. Example: `bbox=160.6,-55.95,-170,-25.89`
+- Collection `summaries` merge array fields now.
+- Several fields have been moved from extensions or item fields to the [Common Metadata fields](item-spec/common-metadata.md):
+    - `eo:platform` / `sar:platform` => `platform`
+    - `eo:instrument` / `sar:instrument` => `instruments`, also changed from string to array of strings
+    - `eo:constellation` / `sar:constellation` => `constellation`
+    - `dtr:start_datetime` => `start_datetime`
+    - `dtr:end_datetime` => `end_datetime`
+- Extensions:
+    - Data Cube extension: Changed allowed formats (removed PROJ string, added PROJJSON / WKT2) for reference systems
+    - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash))
+    - Changed `sar:type` to `sar:product_type` and `sar:polarization` to `sar:polarizations` in the [SAR extension](extensions/sar/README.md)
+- STAC API:
+    - The endpoint `/stac` has been merged with `/`
+    - The endpoint `/stac/search` is now called `/search`
+    - Sort Extension - added non-JSON query/form parameter format
+    - Fields extension has a simplified format for GET parameters
+    - `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context`
+    - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support
+    - Query Extension - type restrictions on query predicates are more accurate, which may require additional implementation support. 
+
+### Removed
+- `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead
+- `summaries` field from Catalogs. Use Collections instead
+- Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `roles` instead.
+- `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead.
+- Extensions:
+    - `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from the [SAR extension](extensions/sar/README.md)
+    - Removed from EO extension field `eo:epsg` in favor of `proj:epsg`
+    - `gsd` and `accuracy` from `eo:bands` in the [EO extension](extensions/eo/README.md)
+    - `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](extensions/sar/README.md)
+    - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md)
+    - Datetime Range (`dtr`) extension. Use the [Common Metadata fields](item-spec/common-metadata.md) instead.
+- STAC API:
+    - `next` from the search metadata and query parameter, added POST body and headers to the links for paging support
+
+### Fixed
+
+- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private.
+- Clarified how to fill `stac_extensions`.
+- More clarifications; typos fixed
+
 ## [v0.8.1] - 2019-11-01
 
 ### Changed
@@ -61,7 +122,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
     - moved label:overview to be a list of Overview Objects from a single Overview Object in spec markdown and json schema (matching previous example JSON).
     - Renamed fields to use plural forms (`label:property` -> `label:properties`, `label:task` -> `label:tasks`, `label:method` -> `label:methods` and `label:overview` -> `label:overviews`)
 
-
 ## [v0.7.0] - 2019-05-06
 
 ### Fixed
@@ -215,6 +275,7 @@ Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkam
 
 
 [Unreleased]: https://github.com/radiantearth/stac-spec/compare/master...dev
+[v0.9.0-rc1]: https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.9.0-rc1
 [v0.8.1]: https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.8.1
 [v0.8.0]: https://github.com/radiantearth/stac-spec/compare/v0.7.0...v0.8.0
 [v0.7.0]: https://github.com/radiantearth/stac-spec/compare/v0.6.2...v0.7.0

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.8.1** of the specification. The 
+**0.9.0-rc1** 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 
@@ -82,30 +82,40 @@ An important core principle of the STAC design is to embrace best practices of m
 to leverage the reliability of flat files on object stores like [AWS S3](https://aws.amazon.com/s3/) and [Google Cloud Storage](https://cloud.google.com/storage/).
 This lead to designing a static catalog at the core of the STAC spec.
 
+### Catalog Types
+
+STAC Catalogs generally fall into two different types: Static Catalogs and Dynamic Catalog APIs.
+
+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 see the chapters below. Additionally, consider the [Static and Dynamic Catalogs](best-practices.md#static-and-dynamic-catalogs)
+section of the best practices document on how you might use them best.
+
 #### Static Catalog
 
-A static catalog is an implementation of the STAC specification that does not respond dynamically to requests - it is simply
-a set of files on a web server that link to one another in a way that can be crawled. A static catalog can only really be
-crawled by search engines and active catalogs; it can not respond to queries. But it is incredibly reliable, as there are
-no moving parts, no clusters or databases to maintain. The goal of STAC is to expose as much asset metadata online as 
-possible, so the static catalog offers a very lower barrier to entry for anyone with geospatial assets to make their data 
-searchable.
+A static catalog is an implementation of the STAC specification that does not respond dynamically to requests. It is simply
+a set of files on a web server that link to one another in a way that can be crawled, often stored in an cloud storage
+service like [Amazon S3](https://aws.amazon.com/s3/) 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.
+A static catalog can only really be crawled by search engines and active catalogs; it can not respond to queries.
+But it is incredibly reliable, as there are no moving parts, no clusters or databases to maintain.
+The goal of STAC is to expose as much asset metadata online as possible, so the static catalog offers a very lower
+barrier to entry for anyone with geospatial assets to make their data searchable.
 
-#### Catalog API
+#### Dynamic Catalog API
 
-A catalog API is a RESTful API that responds to queries (like give me all imagery in Oahu gathered on January 15, 2017). 
-But its structure and responses are designed to mirror the static catalog, so the same client and crawler tools can consume
-it. It generally indexes data for efficient responses, and aims to be easy for existing API's to implement as a more standard
+A dynamic catalog API is implemented in software as a RESTful API that responds to queries (like give me all imagery in Oahu gathered on January 15, 2017). 
+Its structure and responses are usually generated dynamically and are designed to mirror the static catalog, so the same client and crawler tools can consume
+it. It generally indexes data for efficient responses, and aims to be easy for existing APIs to implement as a more standard
 interface for clients to consume. It is specified in OpenAPI 3.0. An active catalog will often be populated by a static catalog,
 or at least may have a 'backup' of its fields stored as a cached static catalog.
 
-#### Core Metadata and Extensions
+### Core Metadata and Extensions
 
 The Item specification defines the core fields that all assets must make available for searching in a catalog.
 In addition there are some basic fields for describing collections of data.
 Vendors can extend those core fields for the metadata they want to make available, and the community has started to define shared extensions.
 
-#### UML Diagram
+### UML Diagram
 
 A UML diagram of the [STAC model](STAC-UML.pdf) is provided to help with navigating the specification. 
 

api-spec/README.md

@@ -13,16 +13,18 @@ The API is a *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17
 
 **Examples:** For samples of how the STAC API can be queried, see the *[examples.md](examples.md)* file.
 
-**API Definitions:** The API is described by the OpenAPI documents in the *[openapi](openapi/)* folder.
+**API Definitions:** The API is described by the OpenAPI documents in the *[openapi](openapi/)* folder. Human-readable versions of the OpenAPI definitions can be viewed online for the last release:
+* [Only the core STAC API](https://stacspec.org/STAC-api.html) 
+* [STAC API including all extensions](https://stacspec.org/STAC-ext-api.html)
 
 ## OpenAPI definitions
 
 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.
 
 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 
+[https://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).
+[https://stacspec.org/STAC-ext-api.html](https://stacspec.org/STAC-ext-api.html).
 
 In the [openapi](openapi/) directory there are three files
 
@@ -37,10 +39,22 @@ The YAML files in the [extensions](extensions/) folder are fragments. Fragments
 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:
 
 ```
-$ npm install
-$ npm run generate-all
+npm install
+npm run generate-all
 ```
 
+You can also dynamically serve a human-readable version of your edited files at `http://127.0.0.1:8080` using the following commands:
+* Only the core STAC API:
+  ```
+  npm install
+  npm run serve
+  ```
+* The STAC API including all extensions:
+  ```
+  npm install
+  npm run serve-ext
+  ```
+
 Create your own OpenAPI document by combining 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:
 
 ```
@@ -50,21 +64,21 @@ Create your own OpenAPI document by combining the STAC definition with the exten
 Then, run the [yaml-files](https://www.npmjs.com/package/yaml-files) command line tool:
 
 ```
-$ npm -g install
-$ yaml-files myapi.merge.yaml myapi.yaml
+npm -g install
+yaml-files myapi.merge.yaml myapi.yaml
 ```
 
 The commands above require root/administrator level access to install the npm packages globally. If you do not have the required permissions or do not want to install the packages globally for any other reason check the npm documentation for your platform for instructions to install and run local packages. Unix bash users for instance may use:
 
 ```
-$ npm install
-$ $(npm bin)/yaml-files myapi.merge.yaml myapi.yaml
+npm install
+$(npm bin)/yaml-files myapi.merge.yaml myapi.yaml
 ```
 
 ## API Evolution
 
 The STAC API is still a work in progress. It currently tries to adhere to the OGC API - Features (OAFeat) specification, with some STAC specific extensions.
-The OAFeat portion of the API is provided in the *[WFS3.yaml](openapi/WFS3.yaml)* and represents the version of OAFeat that is currently being used by STAC.
+The OAFeat portion of the API is provided in the *[OAFeat.yaml](openapi/OAFeat.yaml)* and represents the version of OAFeat that is currently being used by STAC.
 It may diverge some with the *[OAFeat](https://github.com/opengeospatial/ogcapi-features)* spec at any given time, either out of date or 'ahead', with proposals to align OAFeat.
 The long term goal is for STAC's API and OAFeat to completely align, ideally all of STAC API is made from OAFeat plus its extension ecosystem, and STAC just focuses on the content.
 But until then STAC will work to bring practical implementation experience to OAFeat.