Update extensions readme (#1205)

extensions/README.md

@@ -2,14 +2,13 @@
 
 - [Overview](#overview)
 - [Using Extensions](#using-extensions)
-  - [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions)
-- [Stable STAC Extensions](#stable-stac-extensions)
+  - [Extension identifiers in `stac_extensions`](#extension-identifiers-in-stac_extensions)
 - [Community Extensions](#community-extensions)
   - [Proposed extensions](#proposed-extensions)
+- [Extension Maturity](#extension-maturity)
 - [Extending STAC](#extending-stac)
   - [General Conventions](#general-conventions)
   - [Proposing new extensions](#proposing-new-extensions)
-  - [Extension Maturity](#extension-maturity)
   - [Prefixes](#prefixes)
   - [Use of arrays and objects](#use-of-arrays-and-objects)
 
@@ -18,74 +17,74 @@
 One of the most important aspects of the SpatioTemporal Asset Catalog specification is its extensibility. The core
 STAC specification defines only a minimal core, but is designed for extension. It is expected that most real-world
 implementations will use several 'extensions' to fully describe their data. This document describes how extensions
-work, and links to the 'core' extensions included in this repo, as well as to a variety of 'community' extensions.
+work.
 
-**For the complete list of available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).**
+**For a list of most available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).**
+Please note the [extension maturity](#extension-maturity) for each extension.
 
-Extensions to the core STAC specification provide additional JSON fields that can be used to better describe
+Extensions to the core STAC specification provide additional fields that can be used to better describe
 the data. Most tend to be about describing a particular domain or type of data, but some imply
 functionality.
 
 Extensions include a JSON Schema precisely describing the structure, a natural language description of the fields, and thorough examples.
 
 Anybody can create an extension for their data, and data providers often work together to share
-fields between them to create a shared community extensions. See the section below on '[Extending STAC](#extending-stac)')
-for information on how to get started. And everyone is encouraged to link to the extension in the table below, so others
-can be aware of it.
+fields between them to create a shared community extension. See the section below on '[Extending STAC](#extending-stac)')
+for information on how to get started. Everyone is encouraged to add their extensions to the 
+[STAC extensions overview page](https://stac-extensions.github.io/), so others can be aware of it.
 
-Each extension has at least one *owner*. You can find extension owners in each extension's README.
+Each extension should have at least one *owner*. You can find extension owners in each extension's README.
 
 ## Using Extensions
 
-When deciding how to model data in STAC it is highly recommended to first look at the [list of 
-extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This
-increases interoperability, as users know that the meaning of your fields is the same as in other STAC 
+When deciding how to model data in STAC it is highly recommended to first look at the
+[list of extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version.
+This increases interoperability, as users know that the meaning of your fields is the same as in other STAC 
 implementations. Many clients will also understand more mature extensions for better display and querying. 
 
-To incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions`
+To incorporate an extension in STAC the 'Identifier' of the extension must be added to the `stac_extensions`
 array of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions), 
 [Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions)
-object. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators
-can fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as 
-identifiers for specific version of the extension that the STAC object implements. The extension ID can be
-found listed as the 'identifier' in the second line of the README of any extension made with the [extension 
-template](https://github.com/stac-extensions/template), and new ones get published automatically with any release made 
-with the template.
-
-### Extension IDs in `stac_extensions`
-
-The logic for when an object should list an extension ID in its `stac_extension` array is as follows:
-
-- If the object directly implements the extension (by following the specified requirements - usually by including 
-fields, but occasionally implementing alternate behaviors), the  `stac_extensions` of that object should contain the extension ID.
-- If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that
-  Asset should contain the extension ID.
+object. This identifier is a URL to the JSON Schema that allows to validate the fields in the extension.
+These JSON Schema URLs also include the version number of the extension. The 'Identifier' can usually be
+found in the first lines of the README of any extension made with the
+[extension template](https://github.com/stac-extensions/template).
+
+### Extension identifiers in `stac_extensions`
+
+Generally, if an extension is implemented in a STAC file in a place where the extension scope applies to, 
+the extension identifier should be added to the `stac_extension` array. The scope of an extension is usually
+explained in the README of an extension. Implementing an extension by following the specified requirements usually means including 
+fields, but occasionally also means implementing alternate behaviors.
+
+There is no direct inheritance between children and parents though, so if for example an Item implements an extension,
+but the Collection doesn't reflect the usage of the extension, the extension identifier must only be added to the
+`stac_extension` array in the Item, but not to the Collection. If the Collection itself implements the extension though
+or 'summarizies' a field in Collection Summaries or Item Asset Definitions, the extension identifier should be added to the
+Collection.
+
+**Examples**
+
+- If the Catalog, Collection or Item object directly implements the extension,
+  the `stac_extensions` of that object should contain the extension Identifier.
+- If an Asset object implements an extension, the `stac_extensions` of the Item or Collection which holds that
+  Asset should contain the extension identifier.
 - If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then
-  the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field
+  the `stac_extensions` array of that Collection should list the extension identifier. For example, if a Collection `summaries` field
   contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array.
 - If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension
-  ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the
+  identifier should be included in the `stac_extensions` array for that object. For example, if a Collection implements the
   [item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition
-  which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`.
-
-## Stable STAC Extensions
-
-These extensions are considered stable and are widely used in many production implementations. As additional extensions advance
-through the [Extension Maturity](#extension-maturity) classification they, will be added here.
-
-| Extension Title                                                       |     Description                |
-|-----------------------------------------------------------------------|--------------------------------|
-| [Electro-Optical](https://github.com/stac-extensions/eo/)             | Covers electro-optical data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. |
-| [Projection](https://github.com/stac-extensions/projection/)          | Provides a way to describe Items whose assets are in a geospatial projection. |
-| [Scientific Citation](https://github.com/stac-extensions/scientific/) | Metadata that indicate from which publication data originates and how the data itself should be cited or referenced.  |
-| [View Geometry](https://github.com/stac-extensions/view/)             | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data |
+  which includes `eo:bands`, then the EO extension identifier should be listed in that Collection's `stac_extensions`.
 
 ## Community Extensions
 
-There are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the
-[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. For 
-an overview of all extensions with their [Extension Maturity](#extension-maturity) classification see the 
-[STAC extensions overview page](https://stac-extensions.github.io/).
+Everyone is welcome to contribute extensions to the STAC ecosystem. The center of activity for these is the
+[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories.
+Some of these, especially the [stable extensions](#extension-maturity), are observed by the STAC PSC.
+The community can also host STAC extensions in other places, but we encourage the community to
+at least list them in the [STAC extensions overview page](https://stac-extensions.github.io/) so that
+everyone can be aware of all extensions at any time and a high level of interoperability is possible.
 
 ### Proposed extensions
 
@@ -96,18 +95,37 @@ These are ideas that others would likely use and potentially collaborate on. Any
 ideas there, and see the section below on [proposing new extensions](#proposing-new-extensions) for the
 workflow to advance ideas into full-fledged community extensions.
 
+## Extension Maturity
+
+There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions
+listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how
+much they can count on the extension.
+
+| Maturity Classification |  Min Impl # | Description | Stability |
+| ----------------------- | ----------- | ----------- | --------- |
+| Proposal                | 0           | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
+| Pilot                   | 1           | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. |
+| Candidate               | 3           | A number of implementers are using it and are standing behind it as a solid extension. User can generally count on an extension at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. |
+| Stable                  | 6           | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
+| Deprecated              | N/A         | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |
+
+Maturity mostly comes through diverse implementations, so the minimum number of implementations
+column is the main gating function for an extension to mature. But extension authors can also
+choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
+the less breaking changes of the next level.
+
 ## Extending STAC
 
-Anyone is welcome to create an extension. There are several types of extensions, some just add additional fields,
+Anyone is welcome to extend STAC and evolve the additions into a full STAC extension with a README, JSON Schema and examples.
+There are several types of extensions, some just add additional fields,
 some change the behavior of STAC and some introduce completely new functionality. New extensions should try to align
 with existing extensions as well as possible and may even re-use fields and their definitions until they may get split
 into a new extension that combines commonly used fields across multiple extensions.
-Best practices for extension proposals are still emerging in this section.
 
 ### General Conventions
 
 Creating a new extension usually involves defining a set of logically grouped fields, and specifying what the allowed values
-for those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one 
+for those fields are. This should be done in the extension text (README) and in JSON Schema, to provide validation. While one 
 can theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects.
 
 1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object,
@@ -116,8 +134,9 @@ can theoretically add fields anywhere in JSON there are some conventions as to w
    For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in
    the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset.
 3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or
-   [Collection](../collection-spec/collection-spec.md) should be added to the root of the object.
-4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema.
+   [Collection](../collection-spec/collection-spec.md) should be added to the top-level of the object.
+4. All other objects can generally also be extended, e.g. Link Objects, Provider Objects, Band Objects, etc.
+5. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema.
 
 ### Proposing new extensions
 
@@ -126,38 +145,16 @@ Extensions can be hosted anywhere, but should use the
 as a starting point. If you'd like to add a repository to the [stac-extensions](https://github.com/stac-extensions) 
 GitHub organization, just ask on [Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby)! This is fine for 
 work-in-progress extensions. You can also host the extension repository in your own GitHub account, and optionally 
-transfer it to the stac-extensions org later.
+transfer it to the stac-extensions organization later.
 
 For new extensions that require community discussion, we recommend the following workflow:
 
 - Use the stac-extensions template to sketch out your proposed extension
 - Open an issue on this repository with the prefix "New Extension: " and describe the extension. Include a link to the extension repository.
-- Discussion can occur on that issue, or discussion can move to issues/pull requests on the extension repository directly.
+  Also post it in the Gitter chat for broader recognition.
+- Discussion should take place as issues/pull requests on the extension repository directly, but can als occur on the issue created before.
 - Once the extension has an initial release, the issue on stac-spec will be closed.
 
-### Extension Maturity
-
-There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions
-listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how
-much they can count on the extension. Extension creators are encouraged to list their extensions here, even if it is just
-an rough proposal, so others can potentially collaborate.
-
-| Maturity Classification |  Min Impl # | Description | Stability |
-| ----------------------- | ----------- | ----------- | --------- |
-| Proposal                | 0           | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
-| Pilot                   | 1           | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback |
-| Candidate               | 3           | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. |
-| Stable                  | 6           | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
-| Deprecated              | N/A         | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |
-
-Maturity mostly comes through diverse implementations, so the minimum number of implementations
-column is the main gating function for an extension to mature. But extension authors can also
-choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
-the less breaking changes of the next level.
-
-A 'mature' classification level will likely be added once there are extensions that have been
-stable for over a year and are used in twenty or more implementations.
-
 ### Prefixes
 
 A STAC Item can combine schema information from several different sources - the core STAC Item information,