From 20f7e716e8606248c3b6779e1b46bdd8ee9024f1 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 11:16:52 -0700 Subject: [PATCH 1/5] new overview section --- CHANGELOG.md | 2 ++ overview.md | 25 ++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ccef6db1..96b1e62f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 @@ -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 diff --git a/overview.md b/overview.md index 306daf5f..bc65df31 100644 --- a/overview.md +++ b/overview.md @@ -3,7 +3,7 @@ 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). @@ -11,6 +11,29 @@ describe a group of related Items. For more on the differences see the [section 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 From 3a3cc0992dfdfc396a9f4876c616c47456f8f52a Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 11:20:47 -0700 Subject: [PATCH 2/5] updated changelog with pr link --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96b1e62f..4bdfcd2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +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. +- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) ### Changed @@ -23,7 +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. +- Clarified that leaving a field out is not equivalent to setting it as null. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) ## [v1.0.0-rc.2] - 2021-03-30 From 17c149324bae9572b826b8353802a52e712b0c56 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:05:12 -0700 Subject: [PATCH 3/5] updates from PR review --- overview.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/overview.md b/overview.md index bc65df31..0e9952c3 100644 --- a/overview.md +++ b/overview.md @@ -21,8 +21,8 @@ JSON Schemas provide the core testing definitions, and are used in an array of v 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). +Collection extends their [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) +JSON (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 @@ -30,9 +30,8 @@ recommended to read up on them. STAC development is guided by set of core philos 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.* +*Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat +them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should not be used unless the STAC spec defines its use - instead the field should be left out entirely.* ## Item Overview From dfeaf64c639e707484fb8a85cf847729a49019fb Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:07:45 -0700 Subject: [PATCH 4/5] more fixes from PR feedback --- overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overview.md b/overview.md index 0e9952c3..34ec0291 100644 --- a/overview.md +++ b/overview.md @@ -21,8 +21,8 @@ JSON Schemas provide the core testing definitions, and are used in an array of v 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 [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) -JSON (and the full API is the foundation for the STAC API specification). +Collection extends the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) +JSON defined in OGC API - Features (and the full API definition 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 From 06aea1c5658a5e0533d05298e1fe7340903c567c Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:08:57 -0700 Subject: [PATCH 5/5] less characters in a line --- overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/overview.md b/overview.md index 34ec0291..e87d43ec 100644 --- a/overview.md +++ b/overview.md @@ -31,7 +31,8 @@ building small reusable parts that are loosely coupled, focusing on developers, [principles](principles.md) document to learn more. *Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat -them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should not be used unless the STAC spec defines its use - instead the field should be left out entirely.* +them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should +not be used unless the STAC spec defines its use - instead the field should be left out entirely.* ## Item Overview