updates to make clear root can be catalog or collection

catalog-spec/catalog-spec.md

@@ -1,8 +1,7 @@
-# STAC Catalog Specification <!-- omit in toc --> 
+# STAC Catalog Specification
 
 - [Catalog fields](#catalog-fields)
   - [Additional Field Information](#additional-field-information)
-    - [stac_version](#stac_version)
     - [stac_extensions](#stac_extensions)
   - [Link Object](#link-object)
     - [Relation types](#relation-types)
@@ -11,18 +10,15 @@
   - [STAC Media Types](#stac-media-types)
 - [Extensions](#extensions)
 
-This document explains the structure and content of a STAC **Catalog** object. A STAC Catalog object 
-represents a logical group of other Catalog, 
-[Collection](../collection-spec/collection-spec.md), and [Item](../item-spec/item-spec.md) objects. 
-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 Collections and Items. The division of sub-catalogs is up to the implementor,
-but is generally done to aid the ease of online browsing by people. 
+This document explains the structure and content of a STAC Catalog. A STAC Catalog is a 
+[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.
 
-A Catalog object will typically be the entry point into a STAC catalog. Their 
-purpose is discovery: to be browsed by people or be crawled
-by clients to build a searchable index.  
-
-Any JSON object that contains all the required fields is a valid STAC Catalog object.
+Catalogs are not intended to be queried. Their purpose is discovery: to be browsed by people and crawled
+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 an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid
@@ -43,8 +39,8 @@ also a valid STAC Catalog.
 
 | 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. |
 | type            | string        | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. |
-| stac_version    | string        | **REQUIRED.** The STAC version the Catalog implements. |
 | 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.          |
@@ -54,29 +50,22 @@ also a valid STAC Catalog.
 
 ### Additional Field Information
 
-#### stac_version
-
-In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind.
-
 #### stac_extensions
 
-A list of extensions the Catalog implements.
-The list consists of URLs to JSON Schema files that can be used for validation.
-This list must only contain extensions that extend the Catalog specification itself,
-see the 'Scope' for each of the extensions.
-This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects.
+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 [core extensions](../extensions/README.md#core-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `view` for the View 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
 
 This object describes a relationship with another entity. Data providers are advised to be liberal
 with links.
 
-| Field Name | Type   | Description |
-| ---------- | ------ | ----------- |
-| href       | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |
+| Field Name | Type   | Description                                                                                                                         |
+| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| href       | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed.        |
 | rel        | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. |
-| type       | string | [Media type](#media-types) of the referenced entity. |
-| title      | string | A human readable title to be used in rendered displays of the link. |
+| type       | string | [Media type](#media-types) of the referenced entity.                               |
+| title      | string | A human readable title to be used in rendered displays of the link.                                         |
 
 For a full discussion of the situations where relative and absolute links are recommended see the
 ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
@@ -88,8 +77,8 @@ The following types are commonly used as `rel` types in the Link Object of a STA
 | Type    | Description |
 | ------- | ----------- |
 | 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. Non-root Catalogs should include a link to their parent. |
+| root    | STRONGLY RECOMMENDED. URL to the root STAC entity (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 entity (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. |
 
@@ -117,11 +106,11 @@ A STAC Catalog is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)),
 
 The following table lists the Media Types to use for STAC structures.
 
-| Media Type             | Description                                                |
-| ---------------------- | ---------------------------------------------------------- |
-| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md)                   |
-| `application/json`     | A STAC Catalog            |
-| `application/json`     | A STAC [Collection](../collection-spec/collection-spec.md) |
+| Media Type                     | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `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/collection-spec.md)            |
 
 ## Extensions
 

collection-spec/collection-spec.md

@@ -252,8 +252,8 @@ This is done where there is not a clear official option, or where STAC uses an o
 | Type    | Description                                                  |
 | ------- | ------------------------------------------------------------ |
 | self    | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection 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    | URL to the root STAC Catalog or Collection. Collections 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. Non-root Collections should include a link to their parent. |
+| root    | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. |
+| parent  | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. |
 | child   | URL to a child STAC Catalog or Collection. |
 | item    | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). |
 | license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. |

overview.md

@@ -53,10 +53,11 @@ A Catalog is a very simple construct - it just provides links to Items or to oth
 The closest analog is a folder in a file structure, it is the container for Items, but it can 
 also hold other containers (folders / catalogs). 
 
-The Collection specification shares some fields with the catalog spec but has a number of additional fields:
+The Collection entity shares most fields with the Catalog entity but has a number of additional fields:
 license, extent (spatial and temporal), providers, keywords and summaries. Every Item in a Collection links
 back to their Collection, so clients can easily find fields like the license. Thus every Item implicitly 
-shares the fields described in their parent Collection.
+shares the fields described in their parent Collection. Collection entities can be used just like Catalog 
+entities to provide structure, as they provide all the same options for linking and organizing.
 
 But what *should* go in a Collection, versus just in a Catalog?  A Collection will generally consist of
 a set of assets that are defined with the same properties and share higher level metadata. In the 
@@ -78,10 +79,10 @@ provide multiple grouping paths, serving as a sort of faceted search.
 
 The second case is used when one wants to represent diverse data in a single place. If an organization
 has an internal catalog with Landsat 8, Sentinel 2, NAIP data and several commercial imagery providers
-then they'd have a root catalog that would link to a number of different Collections. 
+then they'd have a root Catalog that would link to a number of different Collections. 
 
 So in conclusion it's best to use Collections for what you want user to find as starting point, and then
-catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually
+Catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually
 search Collection-level data, hopefully in concert with other specifications.
 
 ## Catalog Overview
@@ -91,14 +92,14 @@ points to [STAC Items](item-spec/README.md), or to other STAC catalogs. It provi
 linking structure that can be used recursively so that many Items can be included in 
 a single Catalog, organized however the implementor desires. 
 
-STAC makes no formal distinction between a "root" catalog and the "child" catalogs. A root catalog
-is simply the top-most catalog -- it has no parent. A nested catalog structure is useful (and
+STAC makes no formal distinction between a "root" Catalog and the "child" Catalogs. A root Catalog
+is simply the top-most Catalog -- it has no parent. A nested catalog structure is useful (and
 recommended) for breaking up massive numbers of catalog Items into logical groupings. For example,
 it might make sense to organize a catalog by date (year, month, day), or geography (continent,
 country, state/prov). See the [Catalog Layout](best-practices.md#catalog-layout) best practices
 section for more.
 
-A simple Catalog structure might look like this:
+A simple STAC structure might look like this:
 
 - catalog (root)
   - catalog
@@ -137,6 +138,9 @@ root catalog might be a sub-catalog of someone else's structure. The goal is for
 information and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are
 linked to across the web.
 
+*NOTE: The above examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to 
+serve as a Catalog*
+
 ### Static and Dynamic Catalogs
 
 The Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as
@@ -164,8 +168,8 @@ each Item and Catalog, as well as ways to achieve that.
 
 ## Collection Overview
 
-A STAC Collection extends the core fields of the Catalog construct to provide additional metadata to describe the set of Items it
-contains. The required fields are fairly 
+A STAC Collection includes the core fields of the Catalog entity and also provides additional metadata to describe 
+the set of Items it contains. The required fields are fairly 
 minimal - it includes the 4 required Catalog fields (id, description, stac_version and links), and adds license 
 and extents. But there are a number of other common fields defined in the spec, and more common fields are also 
 defined in [STAC extensions](extensions/). These serve as basic metadata, and ideally Collections also link to