Merge pull request #1018 from radiantearth/clean-up

Spec clean up

README.md

@@ -51,7 +51,7 @@ README explaining the layout of the folder, the main specification document, exa
 there is one more specification in the STAC 'family', which is
 the [STAC API specification](https://github.com/radiantearth/stac-api-spec/), now living in its own repository. It
 provides API endpoints, based on the [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) standard,
-that enable clients to search for `item`s that match their filtering criteria. The four specifications are meant to be used 
+that enable clients to search for Item objects that match their filtering criteria. The four specifications are meant to be used 
 together, but are designed so each piece is small, self-contained and reusable in other contexts.
 
 The **[Overview](overview.md)** describes the three core specifications and how they relate to one another.
@@ -64,9 +64,9 @@ The **[Catalog Specification](catalog-spec/)** specifies a structure to link var
 simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways.
 
 The **[Collection Specification](collection-spec/)** provides additional information about a spatio-temporal collection of data.
-In the context of STAC it is most likely a collection of STAC Items that is made available by a data provider.
+In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider.
 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.
+It enables discovery at a higher level than individual Item objects, 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.

catalog-spec/README.md

@@ -6,7 +6,7 @@ the sets of Items. A Catalog consists of links to other Catalogs and Items, and
 additional metadata to further describe its holdings. It is defined in full in the 
 [STAC Catalog Specification](catalog-spec.md).
 
-While STAC Catalogs mostly describe a structure of links and Items, a key related specification is the [STAC Collection Specification](../collection-spec/),
+While STAC Catalogs mostly describe a structure of links and Items, a key related specification is the [STAC Collection Specification](../collection-spec/collection-spec.md),
 which extends Catalogs with additional fields to further describe the set of Items in a Catalog. STAC Collections share the same 
 fields with Catalogs and therefore every Collection is also a valid Catalog. For more information on how the parts of STAC fit
 together see the [overview](../overview.md) document.

catalog-spec/catalog-spec.md

@@ -1,9 +1,19 @@
 # STAC Catalog Specification
 
+- [Catalog fields](#catalog-fields)
+  - [Additional Field Information](#additional-field-information)
+    - [stac_extensions](#stac_extensions)
+  - [Link Object](#link-object)
+    - [Relation types](#relation-types)
+- [Media Types](#media-types)
+  - [Media Type for STAC Catalogs](#media-type-for-stac-catalogs)
+  - [STAC Media Types](#stac-media-types)
+- [Extensions](#extensions)
+
 This document explains the structure and content of a STAC Catalog. A STAC Catalog is a 
-collection of [STAC Items](../item-spec/). These Items can be linked to directly from a Catalog,
-or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain links to Items.
-The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of 
+[Collection](../collection-spec/collection-spec.md) of [STAC Items](../item-spec/item-spec.md). These Items can be 
+linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain 
+links to Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of 
 online browsing by people.
 
 Catalogs are not intended to be queried. Their purpose is discovery: to be browsed by people and crawled
@@ -12,36 +22,36 @@ that contains all the required fields is a valid STAC Catalog.
 
 - [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)
+  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 
-the structure of catalogs as well as links to best practices. This specification lays out the requirements
+the structure of Catalogs as well as links to best practices. This specification lays out the requirements
 and fields to be compliant.
 
 This Catalog specification primarily defines a structure for information to be discoverable. Any use 
 that is publishing a set of related spatiotemporal assets is strongly recommended to also use the 
-[STAC Collection specification](../collection-spec/) to provide additional information about a set of Items 
-contained in a catalog, to give contextual information to aid in discovery. Every STAC Collection is 
+STAC Collection specification to provide additional information about the set of Items 
+contained in a Catalog, in order to give contextual information to aid in discovery. Every STAC Collection is 
 also a valid STAC Catalog.
 
 ## 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_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. |
+| 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. |
 | summaries       | Map<string, \[*]\|[Stats Object](../collection-spec/collection-spec.md#stats-object)> | A map of property summaries, either a set of values or statistics such as a range. More info in the [Collection spec](../collection-spec/collection-spec.md#summaries). |
 | links           | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
 
 ### Additional Field Information
 
 #### 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-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Point Cloud extension. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file.
+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-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Point Cloud extension. 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.
 
 ### Link Object
@@ -67,22 +77,22 @@ The following types are commonly used as `rel` types in the Link Object of a STA
 | ------- | ----------- |
 | self    | STRONGLY RECOMMENDED. *Absolute* URL to the location that the catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
 | root    | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. |
-| parent  | URL to the parent STAC Catalog or [Collection](../collection-spec/README.md). Non-root catalogs should include a link to their parent. |
-| child   | URL to a child STAC Catalog or [Collection](../collection-spec/README.md). |
-| item    | URL to a STAC [Item](../item-spec/item-spec.md). |
+| parent  | URL to the parent STAC Catalog or Collection. Non-root Catalogs should include a link to their parent. |
+| child   | URL to a child STAC Catalog or Collection. |
+| item    | URL to a STAC Item. |
 
-**Note:** A link to at least one `item` or `child` catalog is **REQUIRED**.
+**Note:** A link to at least one `item` or `child` Catalog is **REQUIRED**.
 
 There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as 
-they are more typically used in Collections, as catalogs tend to just be used to structure STAC organization, so tend to just use
+they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use
 the ones above.
 
 ## Media Types
 
 One of the best ways to help inform web clients about the content in a link is to use a common [Media 
 Type](https://en.wikipedia.org/wiki/Media_type) in the `type` field. In STAC the `type` field is used in both the 
 '[Link](#link-object)'' and '[Asset](../item-spec/item-spec.md#asset-object)' Objects. It is quite useful for STAC browsers to better determine
-what to render and display to users searching and browsing the catalog.  Media types are often referred to by the 
+what to render and display to users searching and browsing the Catalog.  Media types are often referred to by the 
 now deprecated term "MIME types". 
 
 ### Media Type for STAC Catalogs
@@ -97,9 +107,9 @@ The following table lists the Media Types to use for STAC structures.
 
 | Media Type                     | Description                                                  |
 | ------------------------------ | ------------------------------------------------------------ |
-| `application/geo+json`	     | A STAC [Item](../item-spec/README.md)                        |
+| `application/geo+json`	     | A STAC [Item](../item-spec/item-spec.md)                        |
 | `application/json`             | A STAC [Catalog](#stac-catalog-specification)                |
-| `application/json`             | A STAC [Collection](../collection-spec/README.md)            |
+| `application/json`             | A STAC [Collection](../collection-spec/collection-spec.md)            |
 
 ## Extensions
 

collection-spec/README.md

@@ -1,19 +1,23 @@
 # STAC Collections
 
-[STAC Items](../item-spec/README.md) are focused on search within a collection\*. Another topic of 
-interest is the search of collections, instead of within a collection. The [STAC Collection specification](collection-spec.md)
-is independent of STAC Items and 
-[STAC Catalogs](../catalog-spec/README.md). Items are required to provide a link back to their collection definition. Other parties 
-can also use this specification standalone, as a way to describe collections in a lightweight way. For more details on how the STAC
-specs fit together see the [overview](../overview.md) document.
-
-The STAC Collection specification is a set of JSON fields to describe a set of Items in a STAC Catalog, to help enable discovery. It builds on 
-the [Catalog Spec](../catalog-spec/README.md), using the flexible structure specified there to further define and explain logical 
-groups of Items. It shares the same fields and therefore every Collection is also a valid Catalog - the JSON structure extends
-the core Catalog definition. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. 
-
-*\* There is no standardized name for the concept we are describing here, a set of assets that are defined with the same 
-properties and share higher level metadata. Others called it: dataset series (ESA, ISO 19115), collection (CNES, NASA), dataset (JAXA), product (JAXA).*
+The STAC [Collection specification](collection-spec.md) provides JSON fields to describe a set of Items, to help enable discovery. 
+It builds on the [Catalog Specification](../catalog-spec/catalog-spec.md), using the flexible structure detailed there to 
+further define and explain logical groups of [Items](../item-spec/item-spec.md). It shares the same fields and therefore every 
+Collection is also a valid Catalog - the JSON structure extends the core Catalog definition. Collections can have both parent Catalogs 
+and Collections as well as child Items, Catalogs and Collections. 
+
+The Collection concept can be used very flexibly - it just provides additional metadata about a set of Items. But it generally
+is used to describe a set of assets that are defined with the same properties and share higher level metadata. There is no standardized 
+name for this, and others called it: dataset series (ESA, ISO 19115), collection (CNES, NASA), dataset (JAXA), product (JAXA). Or
+viewed in GIS terms, the Items are '[features](https://en.wikipedia.org/wiki/Simple_Features)' (that link to assets) and a 
+Collection is the 'layer'. STAC uses the same terms as the [OGC Features API](https://ogcapi.ogc.org/features/), and indeed
+a STAC Collection is a valid [Feature API Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4), extending
+it with additional fields.
+
+Thus the additional fields in a Collection detail the type of information a user would want to know about the set of Items it
+contains. Items are required to provide a link back to their collection definition. But the Collection is independent of STAC Items and 
+STAC Catalogs, and thus other parties can also use this specification standalone, as a way to describe collections in a lightweight way. 
+For more details on how the STAC specs fit together see the [overview](../overview.md) document. 
 
 ## In this directory
 
@@ -28,22 +32,5 @@ 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.
 
-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 
-
-The Collection specification is maturing, but it is still relatively early days. As real world
-implementations innovate in different ways, we will update the core fields to handle.
-
-The goal of the Collection spec is not to reinvent the wheel by making yet another set of fields for metadata. The hope is to 
-align with the latest efforts of the Open Geospatial Consortium, particularly their work around OGC API - Features (OAFeat) and hopefully OGC API - Catalogue. 
-Indeed the field names are chosen to fully align with OAFeat, so a OAFeat `collections/{collectionId}` endpoint can return
-a valid STAC Collection that is also a valid OAFeat Collection.
-
-Effort will also be made to align with Dublin Core and [DCAT](https://www.w3.org/TR/vocab-dcat/), though it is likely to
-start using it as a microformat in STAC Browser HTML output to start. But future iterations could align with a JSON-LD DCAT
-and/or [GeoDCAT](https://github.com/SEMICeu/GeoDCAT-AP) recommendation.
-
-The immediate goal is to just be a simple explanation of fields to describe a collection, and as the spec evolves it will look to
-continually align with other efforts. Indeed it could make sense in the future to just 'use' another spec by subsetting it 
-and explaining it. But nothing was found that exactly matched the needs of STAC to keep things very approachable to developers.
+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.