Merge remote-tracking branch 'upstream/dev' into collection-assets

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - URIs (usually found int properties like `href`, `url`) are now validated using the `iri-reference` format in JSON Schema (allows international characters in URIs)
 - Relaxed the regular expression for DOIs in the scientific extension ([#910](https://github.com/radiantearth/stac-spec/issues/910))
 - The [Stats Object](collection-spec/collection-spec.md#stats-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema.
+- Moved examples from individual directories into a single /examples folder at the root, and evolved them to be more representative.
 - Made `summaries` to be *strongly recommended* - everyone should strive to implement them, as they are very useful.
 - `proj:geometry` allows all GeoJSON geometries instead of just a polygon.
 - `label:description` and `processing:lineage` allow CommonMark for rich-text representation ([#950](https://github.com/radiantearth/stac-spec/issues/950))

README.md

@@ -45,7 +45,7 @@ the specification takes place in the [issue tracker](https://github.com/radiante
 
 ## In this Repository
 
-This repository contains the core specifications plus examples and validation schemas. Also included are a
+This repository contains the core specifications plus [examples](examples/) and validation schemas. Also included are a
 few documents that provide more context and plans for the evolution of the specification. Each spec folder contains a
 README explaining the layout of the folder, the main specification document, examples, and validating schemas. And 
 there is one more specification in the STAC 'family', which is
@@ -68,6 +68,9 @@ In the context of STAC it is most likely a collection of STAC Items that is made
 It includes things like the spatial and temporal extent of the data, the license, keywords, etc.
 It enables discovery at a higher level than individual items, providing a simple way to describe sets of data.
 
+**Examples:** The *[examples/](examples)* folder contains examples for all three specifications, linked together to form two 
+complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts.
+
 **Extensions:** The *[extensions/](extensions/)* folder is where extensions live. Extensions can extend the 
 functionality of the core spec or add fields for specific domains. Each extension has at least one *owner*. You can find extension owners in each extension's README or in the [`CODEOWNERS`](.github/CODEOWNERS) file.
 

best-practices.md

@@ -367,9 +367,17 @@ online location which makes more sense to refer to directly). This enables the f
 copied 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.
+are two types of 'self-contained catalogs'. 
+
+#### Self-contained Metadata Only
+
+These consist of just the STAC metadata (Collection, Catalog and Item files), and uses absolute href 
+links to refer to the online locations of the assets. 
+
+#### Self-contained with Assets
+
+These use 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, referenced locally.
 
 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
@@ -389,12 +397,18 @@ href's.
 We refer to a 'published catalog' as 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
+#### Absolute Published Catalog
+
+This 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 self-contained catalog as described above, except it 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
+
+#### Relative Published Catalog
+
+This is a self-contained catalog as described above, except it includes an absolute `self` link at
+the root catalog, to identify its online location. This is designed so that a self-contained catalog (of either type, with its 
+assets or just metadata) can be 'published' online
 by just adding one field (the self link) to its root catalog. All the other links should remain the same. The resulting catalog
 is no longer compliant with the self-contained catalog recommendations, but instead transforms into a 'relative published catalog'. 
 With this, a client may resolve item and sub-catalog self links by traversing parent and root links, but requires reading 

catalog-spec/README.md

@@ -20,9 +20,6 @@ specification contains an OpenAPI definition of the standard way to do this, at
 **The Specification:** The main Catalog specification is in *[catalog-spec.md](catalog-spec.md)*.
 It includes in depth explanation of the structures and fields.
 
-**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)*.
 

catalog-spec/catalog-spec.md

@@ -10,9 +10,9 @@ Catalogs are not intended to be queried. Their purpose is discovery: to be brows
 by machines to build a search index. A Catalog can be represented in JSON format. Any JSON object 
 that contains all the required fields is a valid STAC Catalog.
 
-- [Examples](examples/)
-  - See a [minimal example](examples/catalog.json), as well a [fuller example](examples/catalog-items.json)
-    includes links to several items. 
+- [Examples](../examples/)
+  - See an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid
+  catalog file, demonstrating linking to items (it is also a collection, so has additional fields)
 - [JSON Schema](json-schema/catalog.json)
 
 The [Catalog section of the Overview](../overview.md#catalog-overview) document provides background information on 

collection-spec/README.md

@@ -20,8 +20,6 @@ properties and share higher level metadata. Others called it: dataset series (ES
 **The Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*. It includes an overview and in depth explanation of the 
 structures and fields.
 
-**Examples:** For samples of how Collections can be implemented the *[examples/](examples/)* folder contains a sample collection. 
-
 **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)*.
 
@@ -30,7 +28,7 @@ structures and fields.
 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. 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.
 
-But it is expected that some more firm recommendations and even requirements will emerge, so that clients will be able to glean more meaningful information. In the meantime implementors are encouraged to do what makes sense for them, and to check out the [examples](examples/) and [other implementations](https://stacspec.org/#examples) for emerging best practices.
+Implementors are encouraged to do what makes sense for them, and to check out the [examples](../examples/) and [other implementations](https://stacindex.org/catalogs) for current best practices.
 
 ## Collection Evolution 
 

collection-spec/collection-spec.md

@@ -8,9 +8,11 @@ A STAC Collection can be represented in JSON format. Any JSON object that contai
 
 STAC Collections are meant to be compatible with *OGC API - Features* Collections, but please be aware that OAFeat Collections and STAC Collections originate from different specifications and despite the fact that we try to align them as much as possible be there may be subtle differences in the specifications.
 
-* [Examples](examples/):
-  * Sentinel 2: A basic standalone example of a [Collection](examples/sentinel2.json) without items.
-  * Landsat 8: A [Collection](examples/landsat-collection.json) with corresponding Item [Item](../item-spec/examples/landsat8-sample.json).
+* [Examples](../examples/):
+  * Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without items.
+  * Simple Example: A [Collection](../examples/collection.json) that links to 3 example items.
+  * Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight
+  various [extension](../extensions) functionality, but serves as another example.
 * [JSON Schema](json-schema/collection.json)
 
 ## Collection fields