Skip to content

Commit

Permalink
Merge branch 'dev' into issue-575
Browse files Browse the repository at this point in the history
  • Loading branch information
@davidraleigh
davidraleigh authored Dec 10, 2019
2 parents c5e8774 + c88571d commit 57422ce
Show file tree
Hide file tree
Showing 55 changed files with 2,018 additions and 1,309 deletions.
68 changes: 41 additions & 27 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,41 +5,55 @@ 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
- [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema.

### Added
- Added a version extension to the API specification
- ItemCollection requires `stac_version` field, `stac_extensions` has also been added
- A `description` field has been added to Item assets (also Asset definitions extension).
- Extensions:
- [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections
- Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`
- 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)
- STAC API:
- Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification

### Added
- Added [Version Extension](extensions/version/README.md) to version and deprecate STAC Items and Collections.
### 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`.
- Collection `summaries` merge array fields now.

- Extensions:
- [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema
- Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / 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

### Removed
- Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support
- Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead.
- Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension.

### Changed
- The STAC API endpoint `/stac` has been merged with `/`
- The STAC API endpoint `/stac/search` is now called `/search`
- Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html).
- [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)).
- Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support
- API `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context`
- Added attribute `role` to Asset, to be used similarly to Link `rel`
- CollectionItem field `stac_version` is now required and field `stac_extensions` is defined in schema.
- Sort Extension - added non-JSON query/form parameter format
- Fields extension has a simplified format for GET parameters
- Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead
- Removed `summaries` field from Catalogs. Use Collections instead
- Extensions:
- Removed `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 `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](extensions/sar/README.md)
- Removed `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md)
- Removed `dtr` extension prefix from example and schema in [datetime-range extension](extensions/datetime-range/README.md)
- 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.
- STAC API:
- Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support

### Fixed

n/a

### Added

n/a

### Added
- Added Instrument extension which adds fields: `platform`, `instruments`, `constellation`, and `mission`.
- 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

Expand Down
34 changes: 22 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
106 changes: 53 additions & 53 deletions api-spec/STAC-extensions.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -735,7 +735,47 @@ components:
providers:
$ref: '#/components/schemas/providers'
summaries:
$ref: '#/components/schemas/summaries'
description: >-
Summaries are either a unique set of all available values *or*
statistics. Statistics by default only specify the range (minimum
and maximum values), but can optionally be accompanied by additional
statistical values. The range can specify the potential range of
values, but it is recommended to be as precise as possible. The set
of values must contain at least one element and it is strongly
recommended to list all values. It is recommended to list as many
properties as reasonable so that consumers get a full overview of
the Collection. Properties that are covered by the Collection
specification (e.g. `providers` and `license`) may not be repeated
in the summaries.
type: object
additionalProperties:
oneOf:
- type: array
title: Set of values
items:
description: A value of any type.
- type: object
title: Statistics
description: >-
By default, only ranges with a minimum and a maximum value can
be specified. Ranges can be specified for ordinal values only,
which means they need to have a rank order. Therefore, ranges
can only be specified for numbers and some special types of
strings. Examples: grades (A to F), dates or times.
Implementors are free to add other derived statistical values
to the object, for example `mean` or `stddev`.
required:
- min
- max
properties:
min:
anyOf:
- type: string
- type: number
max:
anyOf:
- type: string
- type: number
example:
stac_version: 0.8.1
stac_extensions: []
Expand Down Expand Up @@ -786,10 +826,10 @@ components:
- sentinel-2
instruments:
- msi
'eo:off_nadir':
'sat:off_nadir_angle':
min: 0
max: 100
'eo:sun_elevation':
'sat:sun_elevation_angle':
min: 6.78
max: 89.9
'eo:bands':
Expand Down Expand Up @@ -1164,8 +1204,6 @@ components:
$ref: '#/components/schemas/stac_extensions'
id:
type: string
summaries:
$ref: '#/components/schemas/summaries'
linestringGeoJSON:
type: object
required:
Expand Down Expand Up @@ -1593,47 +1631,6 @@ components:
format: uri
- title: Reference to a core extension
type: string
summaries:
description: >-
Summaries are either a unique set of all available values *or*
statistics. Statistics by default only specify the range (minimum and
maximum values), but can optionally be accompanied by additional
statistical values. The range can specify the potential range of values,
but it is recommended to be as precise as possible. The set of values
must contain at least one element and it is strongly recommended to list
all values. It is recommended to list as many properties as reasonable
so that consumers get a full overview of the Collection. Properties that
are covered by the Collection specification (e.g. `providers` and
`license`) may not be repeated in the summaries.
type: object
additionalProperties:
oneOf:
- type: array
title: Set of values
items:
description: A value of any type.
- type: object
title: Statistics
description: >-
By default, only ranges with a minimum and a maximum value can be
specified. Ranges can be specified for ordinal values only, which
means they need to have a rank order. Therefore, ranges can only
be specified for numbers and some special types of strings.
Examples: grades (A to F), dates or times. Implementors are free
to add other derived statistical values to the object, for example
`mean` or `stddev`.
required:
- min
- max
properties:
min:
anyOf:
- type: string
- type: number
max:
anyOf:
- type: string
- type: number
itemCollection:
description: >-
A GeoJSON FeatureCollection augmented with foreign members that contain
Expand Down Expand Up @@ -1742,14 +1739,14 @@ components:
- producer
- licensor
url: 'https://cool-sat.com/'
'eo:sun_azimuth': 168.7
'sat:sun_azimuth_angle': 168.7
'eo:cloud_cover': 0.12
'eo:off_nadir': 1.4
'sat:off_nadir_angle': 1.4
platform: coolsat2
instruments:
- cool_sensor_v1
'eo:bands': []
'eo:sun_elevation': 33.4
'sat:sun_elevation_angle': 33.4
'eo:gsd': 0.512
collection: CS3
links:
Expand Down Expand Up @@ -1800,10 +1797,13 @@ components:
type: string
description: Media type of the asset
example: image/png
role:
type: string
description: Purpose of the asset
example: thumbnail
roles:
type: array
items:
type: string
description: Purposes of the asset
example:
- thumbnail
itemProperties:
type: object
required:
Expand Down
Loading

0 comments on commit 57422ce

Please sign in to comment.