Examples refresh

CHANGELOG.md

@@ -24,6 +24,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.
 - `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.
 

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