radiantearth · philvarner · Jan 5, 2022 · Oct 7, 2021 · Dec 11, 2021 · Dec 14, 2021
diff --git a/PRINCIPLES.md b/PRINCIPLES.md
@@ -47,7 +47,7 @@ for data in a different projection.
 - **Working code required.** Proposed changes should be accompanied by working code
 (ideally with a link to an online service running the code). A reference implementation should be available
 online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations
-that cover the entire specification. Extensions have their own [Extention Maturity](extensions.md#extension-maturity) model.
+that cover the entire specification. Extensions have their own [Extention Maturity Classification](README.md#maturity-classification) model.
 
 - **Design for scale.** The design should work great with more data than can be imagined right now.
 Ideally implementations are built with large test data sets to validate that they will work.

diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@
 - [STAC API](#stac-api)
   - [About](#about)
   - [Stability Note](#stability-note)
+  - [Maturity Classification](#maturity-classification)
   - [Communication](#communication)
   - [In this repository](#in-this-repository)
   - [Contributing](#contributing)
@@ -16,7 +17,6 @@ The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standard
 A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and 
 time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
 
-
 A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), 
 [Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), 
 or a STAC API [ItemCollection](fragments/itemcollection/README.md), depending on the endpoint.
@@ -36,11 +36,34 @@ rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.5>, in additi
 ## Stability Note
 
 This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is 
-currently in a 'beta' state, with no major changes anticipated. For 1.0-beta we remain fully aligned with [OGC API - 
+currently in a 'beta' state, with no major changes anticipated. For 1.0.0-beta.5, we remain fully aligned with [OGC API - 
 Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0, and we are working to stay aligned
 as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API 
 specification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking change 
-will require the spec to go to 2.0.0. 
+will require the spec to go to 2.0.0.
+
+## Maturity Classification
+
+Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states
+in terms of stability and number of implementations. All extensions must include a 
+maturity classification, so that STAC API 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. Can generally count on an extension at this maturity level          | Mostly stable, breaking changes require a new version and minor changes are unlikely.                     |
+| 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.                                                   | Will not be updated and may be removed in an upcoming major release.                                      |
+
+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.
 
 ## Communication
 

diff --git a/collections/README.md b/collections/README.md
@@ -7,8 +7,10 @@
   - [Example](#example)
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/collections))
-- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.5/collections>
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Conformance URIs:** 
+  - <https://api.stacspec.org/v1.0.0-beta.5/collections>
+  - <https://api.stacspec.org/v1.0.0-beta.5/core>
+- **[Maturity Classification](../README.md#maturity-classification):** Candidate
 - **Dependencies**: [STAC API - Core](../core)
 
 A STAC API can return information about all STAC [Collections](../stac-spec/collection-spec/collection-spec.md) available using a link
@@ -24,37 +26,20 @@ aim to align with it. But it still seems to be in flux.*
 
 ## Link Relations
 
-The following Link relations shall exist in the Landing Page (root).
-
-| **rel**        | **href**       | **From**  | **Description**                                      |
-| -------------- | -------------- | --------- | ---------------------------------------------------- |
-| `root`         | `/`            | STAC Core | The root URI                                         |
-| `self`         | `/`            | OAFeat    | Self reference, same as root URI                     |
-| `service-desc` | `/api`         | OAFeat    | The service description in a machine-readable format |
-| `data`         | `/collections` | OAFeat    | List of Collections                                  |
-
-The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be
-OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML),
-`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1`
-(3.1 JSON).
+This conformance class also requires for the link relations in the [STAC API - Core](../core) conformance class to be implemented.
 
-A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML
-page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API
-documentation, but any format is allowed. The Link `type` field should correspond to whatever format or formats are
-supported by this endpoint, e.g., `text/html`.
+The following Link relations shall exist in the Landing Page (root).
 
-| **rel**       | **href**    | **From** | **Description**                                                                                                                    |
-| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `service-doc` | `/api.html` | OAFeat   | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |
+| **rel** | **href**       | **From** | **Description**     |
+| ------- | -------------- | -------- | ------------------- |
+| `data`  | `/collections` | OAFeat   | List of Collections |
 
-Additionally, `child` relations may exist to individual catalogs and collections.
+Additionally, `child` relations may exist to child Catalogs and Collections.
 
 | **rel** | **href** | **From**  | **Description**                                                                                          |
 | ------- | -------- | --------- | -------------------------------------------------------------------------------------------------------- |
 | `child` | various  | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
 
-`child` relations are useful for supporting browsing a STAC API as if it were a static catalog.
-
 The following Link relations shall exist in the `/collections` endpoint response.
 
 | **rel** | **href**       | **From**  | **Description** |
@@ -82,12 +67,12 @@ elsewhere. If this is done, it is recommended to include a `rel` of `canonical`
 
 ## Endpoints
 
-| Endpoint                      | Returns    | Description                                                                                                    |
-| ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
-| `/`                           | Catalog    | Landing Page and root Catalog                                                                                  |
-| `/api`                        | any        | The service description. The path for this endpoint is only recommended to be `/api`, but may be another path. |
-| `/collections`                | JSON       | Object with a list of Collections contained in the catalog and links                                           |
-| `/collections/{collectionId}` | Collection | Returns single Collection JSON                                                                                 |
+This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
+
+| Endpoint                      | Returns    | Description                                                          |
+| ----------------------------- | ---------- | -------------------------------------------------------------------- |
+| `/collections`                | JSON       | Object with a list of Collections contained in the catalog and links |
+| `/collections/{collectionId}` | Collection | Returns single Collection JSON                                       |
 
 STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting
 of an array of all STAC Collections and an array of Links.

diff --git a/core/README.md b/core/README.md
@@ -7,10 +7,11 @@
   - [Extensions](#extensions)
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/core)),
-  and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
-- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.5/core>
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Conformance URIs:**
+  - <https://api.stacspec.org/v1.0.0-beta.5/core>
+- **[Maturity Classification](../README.md#maturity-classification):** Candidate
 - **Dependencies**: None
+  and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
 
 The base of a STAC API is its landing page. This resource is the starting point to discover what behaviors 
 the API supports via the `conformsTo` values and link relations. 
@@ -80,10 +81,12 @@ Additionally, `child` relations may exist to individual catalogs and collections
 It is also valid to have `item` links from the landing page, but most STAC API services are used to 
 serve up a large number of features, so they typically
 use several layers of intermediate `child` links before getting to Item objects.  Note that the `items` (plural)
-link will be used by APIs implementing STAC API - Features to link from a Collection to the items in that collection.
+link relation is used by APIs implementing `STAC API - Features` to link from a Collection to the items in that collection.
 
 ## Endpoints
 
+This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
+
 These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml).
 
 | Endpoint | Returns                                        | Description                                                                                                                                                        |

diff --git a/extensions.md b/extensions.md
@@ -1,6 +1,6 @@
 # API Extensions
 
-STAC aims to define a small core of functionality, with richer capabilities enabled by extensions. This document
+STAC API aims to define a core of functionality, with richer capabilities enabled by extensions. This document
 lists the existing extensions, and explains the process of creating and maturing an extension. 
 
 Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged to at least 
@@ -9,30 +9,10 @@ The third-party / vendor extension section is for the sharing of extensions. As
 it is expected that others will make use of it, and then evolve to make it a 'community extension', that several providers maintain together.
 For now anyone from the community is welcome to use the appropriate parts of the stac-api-spec repository to collaborate.
 
-## Extension Maturity
+All extensions must include a [maturity classification](README.md#maturity-classification), so that STAC API
+specification users can easily get a sense of how much they can count on the extension. 
 
-Extensions are meant to evolve to maturity, and thus may be in different states
-in terms of stability and number of implementations. All extensions 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. Can generally count on an extension at this maturity level          | Mostly stable, breaking changes require a new version and minor changes are unlikely.                     |
-| 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.                                                   | Will not be updated and may be removed in an upcoming major release.                                      |
-
-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.
-
-## Extensions, Fragments and Conformance
+## Extensions, Fragments, and Conformance
 
 Each extension has its own conformance class, which is specified with a 'conformance URI' that is defined for the extension, and listed in 
 the table below. These must be listed in the `conformsTo` JSON of the landing page, as specified by [STAC API Core](core/), to let clients

diff --git a/fragments/context/README.md b/fragments/context/README.md
@@ -4,7 +4,7 @@
 - **Conformance Classes:** 
   - Item Search binding: <https://api.stacspec.org/v1.0.0-beta.5/item-search#context>
   - STAC Features binding: <https://api.stacspec.org/v1.0.0-beta.5/ogcapi-features#context>
-- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
+- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
 

diff --git a/fragments/fields/README.md b/fragments/fields/README.md
@@ -4,7 +4,7 @@
 - **Conformance Classes:** 
   - Item Search binding: <https://api.stacspec.org/v1.0.0-beta.5/item-search#fields>
   - STAC Features binding: <https://api.stacspec.org/v1.0.0-beta.5/ogcapi-features#fields>
-- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
+- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
   - [STAC Features](../../ogcapi-features)

diff --git a/fragments/filter/README.md b/fragments/filter/README.md
@@ -15,7 +15,7 @@
   - Arithmetic Expressions: <http://www.opengis.net/spec/cql2/1.0/conf/arithmetic>
   - Array Operators: <http://www.opengis.net/spec/cql2/1.0/conf/array-operators>
   - Property-Property Comparisons: <http://www.opengis.net/spec/cql2/1.0/conf/property-property>
-- **Extension [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
+- **Extension [Maturity Classification](../../README.md#maturity-classification):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
 

diff --git a/fragments/query/README.md b/fragments/query/README.md
@@ -2,7 +2,7 @@
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
 - **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.5/item-search#query>
-- **Extension [Maturity Classification](../../extensions.md#extension-maturity):** Pilot, scheduled to be Deprecated in favor of the [Filter Extension](../filter/README.md) using [CQL](http://docs.opengeospatial.org/DRAFTS/19-079.html).
+- **Extension [Maturity Classification](../../README.md#maturity-classification):** Pilot, scheduled to be Deprecated in favor of the [Filter Extension](../filter/README.md) using [CQL](http://docs.opengeospatial.org/DRAFTS/19-079.html).
 - **Dependents:**
   - [Item Search](../../item-search)