Skip to content

Commit

Permalink
new overview section
Browse files Browse the repository at this point in the history
  • Loading branch information
cholmes committed Apr 29, 2021
1 parent 311a9a3 commit 20f7e71
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 1 deletion.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045))
- Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090))
- Recommendation to include both `root` and `parent` relation types when they point at the same file.
- Overview section linking to various foundational standards.

### Changed

Expand All @@ -22,6 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))
- Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106))
- Clarified that gsd should only be used on an asset to represent the sensor, not just different processing. ([#1105](https://github.com/radiantearth/stac-spec/pull/1105))
- Clarified that leaving a field out is not equivalent to setting it as null.

## [v1.0.0-rc.2] - 2021-03-30

Expand Down
25 changes: 24 additions & 1 deletion overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,37 @@
There are three component specifications that together make up the core SpatioTemporal Asset Catalog specification.
Each can be used alone, but they work best in concert with one another. The [STAC API specification](https://github.com/radiantearth/stac-api-spec)
builds on top of that core, but is out of scope for this overview. An [Item](item-spec/item-spec.md) represents a
single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as GeoJSON so it can be searched.
single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as [GeoJSON](https://geojson.org/) so it can be searched.
The [Catalog](catalog-spec/catalog-spec.md) specification provides structural elements, to group Items
and [Collections](collection-spec/collection-spec.md). Collections *are* catalogs, that add more required metadata and
describe a group of related Items. For more on the differences see the [section below](#catalogs-vs-collections).

A [UML diagram](https://en.wikipedia.org/wiki/Unified_Modeling_Language) of the [STAC model](STAC-UML.pdf) is also
provided to help with navigating the specification.

## Foundations

STAC is built on top of many great standards and practices. Every part of STAC is
[JSON](https://www.json.org/json-en.html), and [GeoJSON](https://geojson.org/) provides the core geometry fields
and [features](https://en.wikipedia.org/wiki/Simple_Features) definition. All fields are described in the
specifications, and the acceptable values are defined with [JSON Schema](https://json-schema.org/). The released
JSON Schemas provide the core testing definitions, and are used in an array of validation tools. We also rely
on [RFC 8288 (Web Linking)](https://tools.ietf.org/rfc/rfc8288.txt) to express relationships between resources,
and IANA [Media Types](https://en.wikipedia.org/wiki/Media_type) to describe file formats and format contents.
The [OGC API - Features](https://ogcapi.ogc.org/features/) standard is a final core building block. The STAC
Collection extends their [Feature Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_)
(and the full API is the foundation for the STAC API specification).

The STAC specifications are written to be understandable without needing a full background in these. But if you
want to get deep into STAC tool implementation and are not familiar with any of the standards mentioned above it is
recommended to read up on them. STAC development is guided by set of core philosophical tenets, like
building small reusable parts that are loosely coupled, focusing on developers, and more - see our the
[principles](principles.md) document to learn more.

*Note: Setting a field in JSON to `null` is not equivalent to a field not appearing. STAC defines `null` explicitly
for some fields, where it has a particular meaning. It should not be used otherwise - instead the field should be left
out entirely.*

## Item Overview

Fundamental to any SpatioTemporal Asset Catalog, an [Item](item-spec/item-spec.md) object represents a unit of
Expand Down

0 comments on commit 20f7e71

Please sign in to comment.