Merge pull request #739 from joshfix/extension-names

Updated extension documentation to clearly define title/name/prefix
radiantearth · Feb 14, 2020 · 577c844 · 577c844
2 parents 271e57c + a3d79df
commit 577c844
Show file tree

Hide file tree

Showing 18 changed files with 127 additions and 71 deletions.
diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md
@@ -93,14 +93,14 @@ guidance for good recommendations when implementing.
 
 ## Catalog fields
 
-| Element      | Type          | Description                                                  |
-| ------------ | ------------- | ------------------------------------------------------------ |
-| stac_version | string        | **REQUIRED.** The STAC version the catalog implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. |
-| stac_extensions | [string]   | A list of extensions the Catalog implements.                 |
-| id           | string        | **REQUIRED.** Identifier for the catalog.                    |
-| title        | string        | A short descriptive one-line title for the catalog.          |
-| description  | string        | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
-| links        | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
+| Element         | Type          | Description                                                  |
+| --------------- | ------------- | ------------------------------------------------------------ |
+| stac_version    | string        | **REQUIRED.** The STAC version the catalog implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. |
+| stac_extensions | [string]      | A list of extension identifiers the Catalog implements.                 |
+| id              | string        | **REQUIRED.** Identifier for the catalog.                    |
+| title           | string        | A short descriptive one-line title for the catalog.          |
+| description     | string        | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
+| links           | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
 
 **stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file.
 This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions.

diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md
@@ -23,19 +23,19 @@ Implementations are encouraged, however, as good effort will be made to not chan
 
 ## Collection fields
 
-| Element      | Type              | Description                                                  |
-| ------------ | ----------------- | ------------------------------------------------------------ |
-| stac_version | string            | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. |
-| stac_extensions | [string]       | A list of extensions the Collection implements. |
-| id           | string            | **REQUIRED.** Identifier for the collection that is unique across the provider. |
-| title        | string            | A short descriptive one-line title for the collection.       |
-| description  | string            | **REQUIRED.** Detailed multi-line description to fully explain the collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
-| keywords     | [string]          | List of keywords describing the collection.                  |
-| license      | string            | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. |
-| providers    | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. |
-| extent       | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents.    |
-| summaries    | Map<string, [*]\|[Stats Object](#stats-object)> | A map of property summaries, either a set of values or statistics such as a range. |
-| links        | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
+| Element         | Type                                            | Description                                      |
+| --------------- | ----------------------------------------------- | ------------------------------------------------ |
+| stac_version    | string                                          | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. |
+| stac_extensions | [string]                                        | A list of extension identifiers the Collection implements. |
+| id              | string                                          | **REQUIRED.** Identifier for the collection that is unique across the provider. |
+| title           | string                                          | A short descriptive one-line title for the collection.       |
+| description     | string                                          | **REQUIRED.** Detailed multi-line description to fully explain the collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
+| keywords        | [string]                                        | List of keywords describing the collection.                  |
+| license         | string                                          | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. |
+| providers       | [[Provider Object](#provider-object)]           | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. |
+| extent          | [Extent Object](#extent-object)                 | **REQUIRED.** Spatial and temporal extents.    |
+| summaries       | Map<string, [*]\|[Stats Object](#stats-object)> | A map of property summaries, either a set of values or statistics such as a range. |
+| links           | [[Link Object](#link-object)]                   | **REQUIRED.** A list of references to other documents.       |
 
 **stac_extensions**: A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `version` for the Versioning Indicators extension. This does *not* apply for API extensions. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file.
 This list must only contain extensions that extend the Collection itself, see the the 'Scope' column in the list of extensions. If an extension such as the Commons extension has influence on multiple parts of the whole catalog structure, it must be listed in all affected parts (e.g. Collection and Item for the Commons extension). If a structure such as the summaries or the Commons extension provide fields in their JSON structure, these extensions must not be listed here as they don't extend the Collection itself. For example, if a Collection includes the field `sat:platform` in the summaries, the Collection still does not list the `sat` extension in the `stac_extensions` field.

diff --git a/extensions/README.md b/extensions/README.md
@@ -26,11 +26,11 @@ 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 superceded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |
+| 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 superceded 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
@@ -45,22 +45,22 @@ stable for over a year and are used in twenty or more implementations.
 
 An extension can add new fields to STAC entities (content extension), or can add new endpoints or behavior to the API (API extension). Below is a list of content extensions, while API extensions given under [api-spec](../api-spec/) in a folder for [API extensions](../api-spec/extensions/).
 
-| Extension Name (Prefix)                                      | Scope            | Description                                                  | Maturity |
-| ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | -------- |
-| [Asset Definition](asset/README.md) (-)                      | Collection       | Provides a way to specify details about what assets may be found in Items belonging to a collection. | *Proposal* |
-| [Checksum](checksum/README.md) (`checksum`)                  | Item, Catalog, Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* |
-| [Commons](commons/README.md) (-)                             | Item, Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* |
-| [Data Cube](datacube/README.md) (`cube`)                     | Item, Collection | Data Cube related metadata, especially to describe their dimensions. | *Proposal* |
-| [EO](eo/README.md) (`eo`)                                    | Item             | 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. | *Pilot* |
-| [Label](label/README.md) (`label`)                           | Item             | Items that relate labeled AOIs with source imagery | *Proposal* |
-| [Point Cloud](pointcloud/README.md) (`pc`)                   | Item             | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* |
-| [Projection](projection/README.md) (`proj`)                  | Item             | Provides a way to describe items whose assets are in a geospatial projection. | *Proposal* |
-| [SAR](sar/README.md) (`sar`)                                 | Item             | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* |
-| [Satellite](sat/README.md) (`sat`)                           | Item             | Satellite related metadata for data collected from satellites. | *Proposal* |
-| [Scientific](scientific/README.md) (`sci`)                   | Item, Collection | Scientific metadata is considered to be data that indicate from which publication data originates and how the data itself should be cited or referenced. | *Proposal* |
-| [Single File STAC](single-file-stac/README.md) (-)           | ItemCollection   | An extension to provide a set of Collections and Items as a single file catalog. | *Proposal* |
-| [Versioning Indicators](version/README.md) (-)               | Item, Collection | Provides fields and link relation types to provide a version and indicate deprecation. | *Proposal* |
-| [View Geometry](view/README.md)                              | Item             | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data | *Proposal* |
+| Extension Title                                | Identifier       | Field Name Prefix   | Scope                     | Maturity   | Description                        |
+| ---------------------------------------------- | ---------------- | ------------------- | ------------------------- | ---------- | ---------------------------------- | 
+| [Asset Definition](asset/README.md)            | asset            | -                   | Collection                | *Proposal* | Provides a way to specify details about what assets may be found in Items belonging to a collection. |
+| [Checksum](checksum/README.md)                 | checksum         | checksum            | Item, Catalog, Collection | *Proposal* | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. |
+| [Commons](commons/README.md)                   | commons          | -                   | Item, Collection          | *Proposal* | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. |
+| [Data Cube](datacube/README.md)                | datacube         | cube                | Item, Collection          | *Proposal* | Data Cube related metadata, especially to describe their dimensions. |
+| [Electro-Optical](eo/README.md)                | eo               | eo                  | Item                      | *Pilot*    | 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. |
+| [Label](label/README.md)                       | label            | label               | Item                      | *Proposal* | Items that relate labeled AOIs with source imagery |
+| [Point Cloud](pointcloud/README.md)            | pointcloud       | pc                  | Item                      | *Proposal* | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. |
+| [Projection](projection/README.md)             | projection       | proj                | Item                      | *Proposal* | Provides a way to describe items whose assets are in a geospatial projection. |
+| [SAR](sar/README.md)                           | sar              | sar                 | Item                      | *Proposal* | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. |
+| [Satellite](sat/README.md)                     | sat              | sat                 | Item                      | *Proposal* | Satellite related metadata for data collected from satellites. |
+| [Scientific](scientific/README.md)             | scientific       | sci                 | Item, Collection          | *Proposal* | Scientific metadata is considered to be data that indicate from which publication data originates and how the data itself should be cited or referenced. |
+| [Single File STAC](single-file-stac/README.md) | single-file-stac | -                   | ItemCollection            | *Proposal* | An extension to provide a set of Collections and Items as a single file catalog. |
+| [Versioning Indicators](version/README.md)     | version          | -                   | Item, Collection          | *Proposal* | Provides fields and link relation types to provide a version and indicate deprecation. |
+| [View Geometry](view/README.md)                | view             | view                | Item                      | *Proposal* | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data |
 
 ## Third-party / vendor extensions
 
@@ -156,7 +156,7 @@ See the [EO](eo/) extension file structure as an example.
 * Specification examples should be stored in an `examples` directory. 
 * The specification schema file(s) should be stored in a `json-schema` directory. 
 
-Make sure to choose a meaningful name for the extension folder as it will be the shortcut
-that is used to reference it in the `stac_extensions` field. Also, make sure to add the
-folder name to the enum defined for the `stac_extensions` field in the
+Make sure to choose a meaningful identifier for the extension and use this value as the extension's directory name.
+The extension's identifier should be used in the `stac_extensions` field. Also, make sure to add the identifier to the 
+enum defined for the `stac_extensions` field in the
 [JSON schema of the STAC catalog specification](../catalog-spec/json-schema/catalog.json).
diff --git a/extensions/asset/README.md b/extensions/asset/README.md
@@ -1,6 +1,10 @@
 # Asset Definition Specification
 
-**Extension [Maturity Classification](../README.md#extension-maturity): Proposal**
+- **Title: Asset Definition**
+- **Identifier: asset**
+- **Field Name Prefix: -**
+- **Scope: Collection**
+- **Extension [Maturity Classification](../README.md#extension-maturity): Proposal**
 
 A Collection extension to provide details about assets that are available in member Items.