From 3b59ad0c993ab8a636232ec92ca13f6fbb0e5803 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 4 Feb 2021 22:11:32 -0800 Subject: [PATCH 01/28] added type parameter to collection & catalog, plus best practice` --- best-practices.md | 34 +++++++++++++++++++++++++++++- catalog-spec/catalog-spec.md | 3 ++- collection-spec/collection-spec.md | 29 +++++++++++++------------ 3 files changed, 50 insertions(+), 16 deletions(-) diff --git a/best-practices.md b/best-practices.md index 5bb1f59a3..2bea3912b 100644 --- a/best-practices.md +++ b/best-practices.md @@ -40,7 +40,8 @@ - [Static to Dynamic best practices](#static-to-dynamic-best-practices) - [Ingestion and links](#ingestion-and-links) - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services) - + - [How to Differentiate STAC Files](#how-to-differentiate-stac-files) + This document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them are required to meet the core specification, but following these practices will make life easier for client tooling and for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for @@ -623,3 +624,34 @@ basic geographic filtering from listeners. The dynamic STAC API would then listen to the notifications and update its internal datastore whenever new data comes into the static catalog. Implementors have had success using AWS Lambda to do a full 'serverless' updating of the elasticsearch database, but it could just as easily be a server-based process. + +## How to Differentiate STAC Files + +Any tool that crawls a STAC implementation or encounters a STAC file in the wild needs a clear way to determine if it is an Item, +Collection, Catalog or [ItemCollection](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1/fragments/itemcollection) +(part of the [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1). As of 1.0.0 this is done primarily with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. + +```shell +if type is defined + if type is 'Feature' and stac_version is defined // stac_version in items is only available since 0.8, check for (stac_version or assets) to support pre-0.8 data + => Item + else if type is 'FeatureCollection' and stac_version is defined + => ItemCollection + else if type is `Collection` + => Collection + else if type is `Catalog` + => Catalog + else + => Invalid (GeoJSON) +else + => Invalid (JSON) +``` + +When actually crawling a STAC implementation one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types +) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or +`root` then it must be a Catalog or a Collection, and thus can be treated as a Catalog (as a Collection is a Catalog), and then the +`type` field can be used to distinguish if it is a Collection. + +In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. +See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works +for older STAC versions (to 0.8.0, older than that should not be needed). diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 48a740631..8ed23df5d 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -39,7 +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. | +| 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, or `Collection` if it additional meets the [collection](../collection-spec/collection-spec.md) requirements and should be treated by clients as such. | | 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. | diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 4f964ffb1..7db208a5e 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -10,21 +10,22 @@ STAC Collections are compatible with the [Collection](http://docs.opengeospatial specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but it is extended with additional fields. * [Examples](../examples/): - * Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. - * Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. - * Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight + * Sentinel 2: A basic standalone example of a [Collection](../examples/Collection-only/Collection.json) without Items. + * Simple Example: A [Collection](../examples/Collection.json) that links to 3 example Items. + * Extension Collection: An additional [Collection](../examples/extensions-Collection/Collection.json), which is used to highlight various [extension](../extensions) functionality, but serves as another example. -* [JSON Schema](json-schema/collection.json) +* [JSON Schema](json-schema/Collection.json) ## 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 extension identifiers the Collection implements. | +| type | string | **REQUIRED.** Must be set to `Collection` to be a valid Collection. | +| 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. | +| 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. | @@ -43,7 +44,7 @@ it is a fairly unique name, or their name combined with the domain they operate #### 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 [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 `version` for the Versioning Indicators extension. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file. +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 [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 `version` for the Versioning Indicators extension. 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 has influence on multiple parts of the whole STAC structure, it must be listed in all affected parts (e.g. Collection and Item for the `datacube` extension). If a structure such as the summaries 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. #### license @@ -86,9 +87,9 @@ There are a few guidelines for using the asset construct at the Collection level * To list what assets are available in Items see the [Item Assets Definition Extension](../extensions/item-assets/README.md). Collection-level assets can be useful in some scenarios, for example: -1. Exposing additional data that applies collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes. +1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes. 2. Individual Items can't properly be distinguished for some data structures, e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files. -3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)". +3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/Collection-spec/Collection-spec.md#standalone-Collections)". Oftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use Items as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another @@ -123,7 +124,7 @@ The object describes the temporal extents of the Collection. | Element | Type | Description | | -------- | ------------------ | --------------------------------------------------------------------- | -| interval | \[\[string\|null]] | **REQUIRED.** Potential *temporal extents* covered by the collection. | +| interval | \[\[string\|null]] | **REQUIRED.** Potential *temporal extents* covered by the Collection. | **interval**: Each outer array element can be a separate temporal extent, but it is recommended to only use multiple temporal extents if a union of them would then include a large uncovered time span (e.g. only having data for the years 2000, 2010 and 2020). @@ -133,7 +134,7 @@ Open date ranges are supported by setting either the start or the end time to `n ### Provider Object -The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the collection and therefore influences the data offered by this collection. May also include information about the final storage provider hosting the data. +The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the Collection and therefore influences the data offered by this Collection. May also include information about the final storage provider hosting the data. | Field Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------ | @@ -172,17 +173,17 @@ 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. | +| 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. | | 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). | +| 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. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. -**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). +**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`Collection` relation type](../item-spec/item-spec.md#relation-types). ### Asset Object From 96a7bc8e8ae4fd0c0e2ead7e89e0cf8dd3d61e2b Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 4 Feb 2021 22:18:55 -0800 Subject: [PATCH 02/28] added type info to changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b9fc49985..d4681ceae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Recommendation to enable CORS - A 'visual' option as an asset role. - Added a best practice recommendation to keep collections at consistent levels. +- Catalog and Collection now require a `type` parameter, to be set to `Catalog` or `Collection` for clients to more easily distinguish them easily. ### Changed From 3dec7093601bc039f2e44777fde5ed64b1366ce3 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:11:26 -0700 Subject: [PATCH 03/28] fix capitalization i broke in rebase --- catalog-spec/catalog-spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 8ed23df5d..08bf6d59a 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -22,7 +22,7 @@ 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 @@ -39,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, or `Collection` if it additional meets the [collection](../collection-spec/collection-spec.md) requirements and should be treated by clients as such. | +| 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, or `Collection` if it additional meets the [collection](../collection-spec/collection-spec.md) requirements and should be treated by clients as such. | | 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. | @@ -76,7 +76,7 @@ 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. | +| 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. | | child | URL to a child STAC Catalog or Collection. | From 44d087967173c4f57a4078d200e32640c6cb0d8e Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:13:48 -0700 Subject: [PATCH 04/28] fix other capitalization i broke in rebase --- collection-spec/collection-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 7db208a5e..8743658e8 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -10,8 +10,8 @@ STAC Collections are compatible with the [Collection](http://docs.opengeospatial specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but it is extended with additional fields. * [Examples](../examples/): - * Sentinel 2: A basic standalone example of a [Collection](../examples/Collection-only/Collection.json) without Items. - * Simple Example: A [Collection](../examples/Collection.json) that links to 3 example Items. + * Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. + * Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. * Extension Collection: An additional [Collection](../examples/extensions-Collection/Collection.json), which is used to highlight various [extension](../extensions) functionality, but serves as another example. * [JSON Schema](json-schema/Collection.json) @@ -89,7 +89,7 @@ There are a few guidelines for using the asset construct at the Collection level Collection-level assets can be useful in some scenarios, for example: 1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes. 2. Individual Items can't properly be distinguished for some data structures, e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files. -3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/Collection-spec/Collection-spec.md#standalone-Collections)". +3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)". Oftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use Items as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another From bd490c4fea1abe13f6ba097f5c247e56327370e9 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:23:25 -0700 Subject: [PATCH 05/28] update schemata, remove extension language --- catalog-spec/json-schema/catalog-core.json | 130 ++++++++++++++++++ catalog-spec/json-schema/catalog.json | 112 +-------------- collection-spec/collection-spec.md | 10 +- collection-spec/json-schema/collection.json | 7 +- examples/collection-only/collection.json | 1 + examples/collection.json | 1 + .../extensions-collection/collection.json | 1 + 7 files changed, 150 insertions(+), 112 deletions(-) create mode 100644 catalog-spec/json-schema/catalog-core.json diff --git a/catalog-spec/json-schema/catalog-core.json b/catalog-spec/json-schema/catalog-core.json new file mode 100644 index 000000000..fb131456c --- /dev/null +++ b/catalog-spec/json-schema/catalog-core.json @@ -0,0 +1,130 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://schemas.stacspec.org/v1.0.0-beta.2/catalog-spec/json-schema/catalog.json#", + "title": "Core STAC Catalog Fields Specification", + "description": "This object represents the fields shared by Catalogs and Collections", + "allOf": [ + { + "$ref": "#/definitions/catalogCore" + } + ], + "definitions": { + "catalogCore": { + "title": "Catalog Core Fields", + "type": "object", + "required": [ + "stac_version", + "id", + "description", + "links", + ], + "properties": { + "stac_version": { + "title": "STAC version", + "type": "string", + "const": "1.0.0-beta.2" + }, + "stac_extensions": { + "title": "STAC extensions", + "type": "array", + "uniqueItems": true, + "items": { + "anyOf": [ + { + "title": "Reference to a JSON Schema", + "type": "string", + "format": "iri" + }, + { + "title": "Reference to a core extension", + "type": "string" + } + ] + } + }, + "id": { + "title": "Identifier", + "type": "string" + }, + "title": { + "title": "Title", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string" + }, + "links": { + "title": "Links", + "type": "array", + "items": { + "$ref": "#/definitions/link" + } + }, + "summaries": { + "$ref": "#/definitions/summaries" + } + } + }, + "link": { + "type": "object", + "required": [ + "rel", + "href" + ], + "properties": { + "href": { + "title": "Link reference", + "type": "string", + "format": "iri-reference" + }, + "rel": { + "title": "Link relation type", + "type": "string" + }, + "type": { + "title": "Link type", + "type": "string" + }, + "title": { + "title": "Link title", + "type": "string" + } + } + }, + "summaries": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Stats", + "type": "object", + "required": [ + "minimum", + "maximum" + ], + "properties": { + "minimum": { + "title": "Minimum value", + "type": ["number", "string"] + }, + "maximum": { + "title": "Maximum value", + "type": ["number", "string"] + } + } + }, + { + "title": "Set of values", + "type": "array", + "minItems": 1, + "items": { + "description": "Any data type could occur." + } + } + ] + } + } + } + } + \ No newline at end of file diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 839ece2a1..301236e97 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -4,6 +4,9 @@ "title": "STAC Catalog Specification", "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.", "allOf": [ + { + "$ref": "./catalog-core.json" + }, { "$ref": "#/definitions/catalog" } @@ -13,117 +16,14 @@ "title": "Catalog", "type": "object", "required": [ - "stac_version", - "id", - "description", - "links" - ], - "properties": { - "stac_version": { - "title": "STAC version", - "type": "string", - "const": "1.0.0-beta.2" - }, - "stac_extensions": { - "title": "STAC extensions", - "type": "array", - "uniqueItems": true, - "items": { - "anyOf": [ - { - "title": "Reference to a JSON Schema", - "type": "string", - "format": "iri" - }, - { - "title": "Reference to a core extension", - "type": "string" - } - ] - } - }, - "id": { - "title": "Identifier", - "type": "string" - }, - "title": { - "title": "Title", - "type": "string" - }, - "description": { - "title": "Description", - "type": "string" - }, - "links": { - "title": "Links", - "type": "array", - "items": { - "$ref": "#/definitions/link" - } - }, - "summaries": { - "$ref": "#/definitions/summaries" - } - } - }, - "link": { - "type": "object", - "required": [ - "rel", - "href" + "type" ], "properties": { - "href": { - "title": "Link reference", - "type": "string", - "format": "iri-reference" - }, - "rel": { - "title": "Link relation type", - "type": "string" - }, "type": { - "title": "Link type", - "type": "string" - }, - "title": { - "title": "Link title", - "type": "string" + "title": "Type of STAC entityt", + "const": "Catalog" } } - }, - "summaries": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "title": "Stats", - "type": "object", - "required": [ - "minimum", - "maximum" - ], - "properties": { - "minimum": { - "title": "Minimum value", - "type": ["number", "string"] - }, - "maximum": { - "title": "Maximum value", - "type": ["number", "string"] - } - } - }, - { - "title": "Set of values", - "type": "array", - "minItems": 1, - "items": { - "description": "Any data type could occur." - } - } - ] - } } } } diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 8743658e8..5f452bdb8 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -1,20 +1,20 @@ # STAC Collection Specification The STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata. The -Collection Specification extends the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) with additional fields to -describe the whole dataset and the included set of Items. It shares the same fields and therefore every Collection is also a valid Catalog. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. +Collection Specification shares some fields with the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) with additional fields to +describe the whole dataset and the included set of Items. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. A STAC Collection is represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. STAC Collections are compatible with the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4) JSON -specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but it is extended with additional fields. +specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they are extended with additional fields. * [Examples](../examples/): * Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. * Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. - * Extension Collection: An additional [Collection](../examples/extensions-Collection/Collection.json), which is used to highlight + * Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight various [extension](../extensions) functionality, but serves as another example. -* [JSON Schema](json-schema/Collection.json) +* [JSON Schema](json-schema/collection.json) ## Collection fields diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index e62334352..85ca3dbc9 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -5,7 +5,7 @@ "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", "allOf": [ { - "$ref": "../../catalog-spec/json-schema/catalog.json" + "$ref": "../../catalog-spec/json-schema/catalog-core.json" }, { "$ref": "#/definitions/collection" @@ -17,10 +17,15 @@ "description": "These are the fields specific to a STAC Collection. All other fields are inherited from STAC Catalog.", "type": "object", "required": [ + "type", "license", "extent" ], "properties": { + "type": { + "title": "Type of STAC entity", + "const": "Collection" + }, "stac_extensions": { "title": "STAC extensions", "type": "array", diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 4be7b0a51..e0b905c64 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -1,4 +1,5 @@ { + "type": "Collection", "stac_version": "1.0.0-beta.2", "stac_extensions": [], "id": "sentinel-2", diff --git a/examples/collection.json b/examples/collection.json index 55890afab..45356b103 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,5 +1,6 @@ { "id": "simple-collection", + "type": "Collection", "stac_version": "1.0.0-beta.2", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", diff --git a/examples/extensions-collection/collection.json b/examples/extensions-collection/collection.json index 83c8d1319..825ec3db6 100644 --- a/examples/extensions-collection/collection.json +++ b/examples/extensions-collection/collection.json @@ -1,5 +1,6 @@ { "id": "extensions-collection", + "type": "Collection", "stac_version": "1.0.0-beta.2", "description": "A heterogenous collection containing deeper examples of various extensions", "links": [ From 355c947de2627b36c5adea9317eba635c56ec757 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:32:38 -0700 Subject: [PATCH 06/28] add type to example collections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit we sure don't have a lot of example catalogs 🤔 --- examples/catalog.json | 1 + extensions/datacube/examples/example-collection.json | 1 + extensions/file/examples/collection.json | 1 + extensions/item-assets/examples/example-landsat8.json | 1 + extensions/processing/examples/sentinel2-collection.json | 1 + extensions/scientific/examples/collection.json | 1 + extensions/version/examples/collection.json | 1 + 7 files changed, 7 insertions(+) diff --git a/examples/catalog.json b/examples/catalog.json index 9e407deb1..086a734e0 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -1,5 +1,6 @@ { "id": "examples", + "type": "Catalog", "stac_version": "1.0.0-beta.2", "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.", "links": [ diff --git a/extensions/datacube/examples/example-collection.json b/extensions/datacube/examples/example-collection.json index d90d49a3e..54c3039e8 100644 --- a/extensions/datacube/examples/example-collection.json +++ b/extensions/datacube/examples/example-collection.json @@ -1,5 +1,6 @@ { "stac_version": "1.0.0-beta.2", + "type": "Collection", "stac_extensions": [ "datacube" ], diff --git a/extensions/file/examples/collection.json b/extensions/file/examples/collection.json index 082596efd..47bb28da6 100644 --- a/extensions/file/examples/collection.json +++ b/extensions/file/examples/collection.json @@ -1,5 +1,6 @@ { "stac_version": "1.0.0-beta.2", + "type": "Collection", "stac_extensions": [ "file" ], diff --git a/extensions/item-assets/examples/example-landsat8.json b/extensions/item-assets/examples/example-landsat8.json index aec486d7f..6d2401e12 100644 --- a/extensions/item-assets/examples/example-landsat8.json +++ b/extensions/item-assets/examples/example-landsat8.json @@ -1,5 +1,6 @@ { "id": "landsat-8-l1", + "type": "Collection", "title": "Landsat 8 L1", "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", "keywords": [ diff --git a/extensions/processing/examples/sentinel2-collection.json b/extensions/processing/examples/sentinel2-collection.json index 5d044cad9..848050389 100644 --- a/extensions/processing/examples/sentinel2-collection.json +++ b/extensions/processing/examples/sentinel2-collection.json @@ -1,5 +1,6 @@ { "stac_version": "1.0.0-beta.2", + "type": "Collection", "stac_extensions": [ "processing" ], diff --git a/extensions/scientific/examples/collection.json b/extensions/scientific/examples/collection.json index 4cbc450e7..21aeb5755 100644 --- a/extensions/scientific/examples/collection.json +++ b/extensions/scientific/examples/collection.json @@ -1,5 +1,6 @@ { "stac_version": "1.0.0-beta.2", + "type": "Collection", "stac_extensions": [ "scientific" ], diff --git a/extensions/version/examples/collection.json b/extensions/version/examples/collection.json index 1a2c8d0d0..8adc4e587 100644 --- a/extensions/version/examples/collection.json +++ b/extensions/version/examples/collection.json @@ -1,5 +1,6 @@ { "stac_version": "1.0.0-beta.2", + "type": "Collection", "stac_extensions": [ "version" ], From 3bdca944d22b828c64248618d8334c0ad5607781 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:35:52 -0700 Subject: [PATCH 07/28] remove single-file-stac references --- catalog-spec/catalog-spec.md | 2 +- extensions/README.md | 1 - extensions/single-file-stac/README.md | 27 -- .../examples/example-search.json | 452 ------------------ .../single-file-stac/json-schema/schema.json | 49 -- 5 files changed, 1 insertion(+), 530 deletions(-) delete mode 100644 extensions/single-file-stac/README.md delete mode 100644 extensions/single-file-stac/examples/example-search.json delete mode 100644 extensions/single-file-stac/json-schema/schema.json diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 08bf6d59a..7e741f67e 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -52,7 +52,7 @@ also a valid STAC Catalog. #### 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 `pointcloud` 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 diff --git a/extensions/README.md b/extensions/README.md index 80acf2299..122213563 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -68,7 +68,6 @@ These extensions add new fields or semantics to STAC objects. | [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 Citation](scientific/README.md) | scientific | sci | Item, Collection | *Proposal* | Metadata 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 | - | Catalog | *Proposal* | An extension to provide a set of Collections and Items within a single file STAC. | | [Tiled Assets](tiled-assets/README.md) | tiled-assets | tiles | Item, Catalog, Collection | *Proposal* | Allows to specify numerous assets using asset templates via tile matrices and dimensions. | | [Timestamps](timestamps/README.md) | timestamps | - | Item | *Proposal* | Allows to specify numerous timestamps for assets and metadata. | | [Versioning Indicators](version/README.md) | version | - | Item, Collection | *Proposal* | Provides fields and link relation types to provide a version and indicate deprecation. | diff --git a/extensions/single-file-stac/README.md b/extensions/single-file-stac/README.md deleted file mode 100644 index 796acb529..000000000 --- a/extensions/single-file-stac/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# Single File STAC Specification - -- **Title: Single File STAC** -- **Identifier: single-file-stac** -- **Field Name Prefix: -** -- **Scope: Catalog** -- **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -- **Owner**: @matthewhanson - -An extension to provide a set of Collections and Items within a single file catalog. The single file is a STAC catalog that contains everything that would normally be in a linked set of STAC files. This format is useful to save a portion of a catalog, or when creating a small catalog from derived data that should remain portable. It is most useful for saving the results of a search from a STAC API, as the Items, Collections, and optionally the search parameters are all saved within the single file. Hierarchical links have no meaning in a single file STAC, and so, if present, should be removed when creating a single file catalog. - -- [Example](examples/example-search.json) -- [JSON Schema](json-schema/schema.json) - -## Catalog fields - -A Single File STAC is a complete [Catalog Object](../../catalog-spec/catalog-spec.md) presented as a [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) contained in a single file. - -| Field Name | Type | Description | -| ------------------ | ------ | ------------------------------------------------------------ | -| type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `FeatureCollection`. | -| collections | \[[Collection](../../collection-spec/collection-spec.md#collection-fields)] | An array of STAC Collections that are used by any of the Items in the catalog. | -| features | **REQUIRED.** \[[Item](../../item-spec/item-spec.md#item-fields)] | An array of STAC Items | - -## Implementations - -- [sat-search](https://github.com/sat-utils/sat-search) uses the Single File Catalog to save and load search results. diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json deleted file mode 100644 index 43a99dd41..000000000 --- a/extensions/single-file-stac/examples/example-search.json +++ /dev/null @@ -1,452 +0,0 @@ -{ - "id": "mysearchresults", - "stac_version": "1.0.0-beta.2", - "stac_extensions": [ - "single-file-stac" - ], - "description": "A bunch of results from a search", - "type": "FeatureCollection", - "features": [ - { - "stac_version": "1.0.0-beta.2", - "stac_extensions": [ - "projection", - "view", - "https://example.com/stac/landsat-extension/1.0/schema.json" - ], - "type": "Feature", - "id": "LC80370332018039LGN00", - "collection": "landsat-8-l1", - "bbox": [ - -112.21054, - 37.83042, - -109.4992, - 39.95532 - ], - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [ - -111.6768167850251, - 39.952817693022276 - ], - [ - -109.5010938553632, - 39.55607811527241 - ], - [ - -110.03573868784865, - 37.83172334507642 - ], - [ - -112.20846353249907, - 38.236456540046845 - ], - [ - -111.6768167850251, - 39.952817693022276 - ] - ] - ] - }, - "properties": { - "datetime": "2018-02-08T18:02:15.719478+00:00", - "view:sun_azimuth": 152.63804142, - "view:sun_elevation": 31.82216637, - "landsat:product_id": "LC08_L1TP_037033_20180208_20180221_01_T1", - "landsat:scene_id": "LC80370332018039LGN00", - "landsat:processing_level": "L1TP", - "landsat:tier": "T1", - "proj:epsg": 32612 - }, - "assets": { - "index": { - "type": "text/html", - "title": "HTML index page", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/index.html" - }, - "thumbnail": { - "title": "Thumbnail image", - "type": "image/jpeg", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_thumb_large.jpg" - }, - "B1": { - "type": "image/tiff; application=geotiff", - "title": "Band 1 (coastal)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B1.TIF" - }, - "B2": { - "type": "image/tiff; application=geotiff", - "title": "Band 2 (blue)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B2.TIF" - }, - "B3": { - "type": "image/tiff; application=geotiff", - "title": "Band 3 (green)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B3.TIF" - }, - "B4": { - "type": "image/tiff; application=geotiff", - "title": "Band 4 (red)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B4.TIF" - }, - "B5": { - "type": "image/tiff; application=geotiff", - "title": "Band 5 (nir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B5.TIF" - }, - "B6": { - "type": "image/tiff; application=geotiff", - "title": "Band 6 (swir16)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B6.TIF" - }, - "B7": { - "type": "image/tiff; application=geotiff", - "title": "Band 7 (swir22)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B7.TIF" - }, - "B8": { - "type": "image/tiff; application=geotiff", - "title": "Band 8 (pan)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B8.TIF" - }, - "B9": { - "type": "image/tiff; application=geotiff", - "title": "Band 9 (cirrus)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B9.TIF" - }, - "B10": { - "type": "image/tiff; application=geotiff", - "title": "Band 10 (lwir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B10.TIF" - }, - "B11": { - "type": "image/tiff; application=geotiff", - "title": "Band 11 (lwir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_B11.TIF" - }, - "ANG": { - "title": "Angle coefficients file", - "type": "text/plain", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_ANG.txt" - }, - "MTL": { - "title": "original metadata file", - "type": "text/plain", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_MTL.txt" - }, - "BQA": { - "title": "Band quality data", - "type": "image/tiff; application=geotiff", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/037/033/LC08_L1TP_037033_20180208_20180221_01_T1/LC08_L1TP_037033_20180208_20180221_01_T1_BQA.TIF" - } - }, - "links": [] - }, - { - "stac_version": "1.0.0-beta.2", - "stac_extensions": [ - "projection", - "view", - "https://example.com/stac/landsat-extension/1.0/schema.json" - ], - "type": "Feature", - "id": "LC80340332018034LGN00", - "collection": "landsat-8-l1", - "bbox": [ - -107.6044, - 37.8096, - -104.86884, - 39.97508 - ], - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [ - -107.03912158283073, - 39.975078807631036 - ], - [ - -104.87161559271382, - 39.548160703908025 - ], - [ - -105.43927721248009, - 37.81075859503169 - ], - [ - -107.60423259994965, - 38.24485405534073 - ], - [ - -107.03912158283073, - 39.975078807631036 - ] - ] - ] - }, - "properties": { - "datetime": "2018-02-03T17:43:44Z", - "view:sun_azimuth": 153.39513457, - "view:sun_elevation": 30.41894816, - "landsat:product_id": "LC08_L1TP_034033_20180203_20180220_01_T1", - "landsat:scene_id": "LC80340332018034LGN00", - "landsat:processing_level": "L1TP", - "landsat:tier": "T1", - "proj:epsg": 32613 - }, - "assets": { - "index": { - "type": "text/html", - "title": "HTML index page", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/index.html" - }, - "thumbnail": { - "title": "Thumbnail image", - "type": "image/jpeg", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_thumb_large.jpg" - }, - "B1": { - "type": "image/tiff; application=geotiff", - "title": "Band 1 (coastal)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B1.TIF" - }, - "B2": { - "type": "image/tiff; application=geotiff", - "title": "Band 2 (blue)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B2.TIF" - }, - "B3": { - "type": "image/tiff; application=geotiff", - "title": "Band 3 (green)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B3.TIF" - }, - "B4": { - "type": "image/tiff; application=geotiff", - "title": "Band 4 (red)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B4.TIF" - }, - "B5": { - "type": "image/tiff; application=geotiff", - "title": "Band 5 (nir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B5.TIF" - }, - "B6": { - "type": "image/tiff; application=geotiff", - "title": "Band 6 (swir16)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B6.TIF" - }, - "B7": { - "type": "image/tiff; application=geotiff", - "title": "Band 7 (swir22)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B7.TIF" - }, - "B8": { - "type": "image/tiff; application=geotiff", - "title": "Band 8 (pan)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B8.TIF" - }, - "B9": { - "type": "image/tiff; application=geotiff", - "title": "Band 9 (cirrus)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B9.TIF" - }, - "B10": { - "type": "image/tiff; application=geotiff", - "title": "Band 10 (lwir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B10.TIF" - }, - "B11": { - "type": "image/tiff; application=geotiff", - "title": "Band 11 (lwir)", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_B11.TIF" - }, - "ANG": { - "title": "Angle coefficients file", - "type": "text/plain", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_ANG.txt" - }, - "MTL": { - "title": "original metadata file", - "type": "text/plain", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_MTL.txt" - }, - "BQA": { - "title": "Band quality data", - "type": "image/tiff; application=geotiff", - "href": "https://s3-us-west-2.amazonaws.com/landsat-pds/c1/L8/034/033/LC08_L1TP_034033_20180203_20180220_01_T1/LC08_L1TP_034033_20180203_20180220_01_T1_BQA.TIF" - } - }, - "links": [] - } - ], - "collections": [ - { - "id": "landsat-8-l1", - "title": "Landsat 8 L1", - "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", - "keywords": [ - "landsat", - "earth observation", - "usgs" - ], - "stac_version": "1.0.0-beta.2", - "stac_extensions": [ - "item-assets" - ], - "extent": { - "spatial": { - "bbox": [ - [ - -180, - -90, - 180, - 90 - ] - ] - }, - "temporal": { - "interval": [ - [ - "2013-06-01T00:00:00Z", - null - ] - ] - } - }, - "providers": [ - { - "name": "USGS", - "roles": [ - "producer" - ], - "url": "https://landsat.usgs.gov/" - }, - { - "name": "Planet Labs", - "roles": [ - "processor" - ], - "url": "https://github.com/landsat-pds/landsat_ingestor" - }, - { - "name": "AWS", - "roles": [ - "host" - ], - "url": "https://landsatonaws.com/" - }, - { - "name": "Development Seed", - "roles": [ - "processor" - ], - "url": "https://github.com/sat-utils/sat-api" - } - ], - "license": "PDDL-1.0", - "summaries": { - "gsd": [ - 15 - ], - "platform": [ - "landsat-8" - ], - "instruments": [ - "oli", - "tirs" - ], - "view:off_nadir": [ - 0 - ] - }, - "item_assets": { - "index": { - "type": "text/html", - "title": "HTML index page" - }, - "thumbnail": { - "title": "Thumbnail image", - "type": "image/jpeg" - }, - "B1": { - "type": "image/tiff; application=geotiff", - "title": "Band 1 (coastal)" - }, - "B2": { - "type": "image/tiff; application=geotiff", - "title": "Band 2 (blue)" - }, - "B3": { - "type": "image/tiff; application=geotiff", - "title": "Band 3 (green)" - }, - "B4": { - "type": "image/tiff; application=geotiff", - "title": "Band 4 (red)" - }, - "B5": { - "type": "image/tiff; application=geotiff", - "title": "Band 5 (nir)" - }, - "B6": { - "type": "image/tiff; application=geotiff", - "title": "Band 6 (swir16)" - }, - "B7": { - "type": "image/tiff; application=geotiff", - "title": "Band 7 (swir22)" - }, - "B8": { - "type": "image/tiff; application=geotiff", - "title": "Band 8 (pan)" - }, - "B9": { - "type": "image/tiff; application=geotiff", - "title": "Band 9 (cirrus)" - }, - "B10": { - "type": "image/tiff; application=geotiff", - "title": "Band 10 (lwir)" - }, - "B11": { - "type": "image/tiff; application=geotiff", - "title": "Band 11 (lwir)" - }, - "ANG": { - "title": "Angle coefficients file", - "type": "text/plain" - }, - "MTL": { - "title": "original metadata file", - "type": "text/plain" - }, - "BQA": { - "title": "Band quality data", - "type": "image/tiff; application=geotiff" - } - }, - "links": [ - { - "rel": "self", - "href": "https://n34f767n91.execute-api.us-east-1.amazonaws.com/prod/collections/landsat-8-l1" - }, - { - "rel": "parent", - "href": "https://n34f767n91.execute-api.us-east-1.amazonaws.com/prod" - }, - { - "rel": "root", - "href": "https://n34f767n91.execute-api.us-east-1.amazonaws.com/prod" - }, - { - "rel": "items", - "href": "https://n34f767n91.execute-api.us-east-1.amazonaws.com/prod/collections/landsat-8-l1/items" - } - ] - } - ], - "links": [] -} \ No newline at end of file diff --git a/extensions/single-file-stac/json-schema/schema.json b/extensions/single-file-stac/json-schema/schema.json deleted file mode 100644 index 0dd9086a7..000000000 --- a/extensions/single-file-stac/json-schema/schema.json +++ /dev/null @@ -1,49 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-beta.2/extensions/single-file-stac/json-schema/schema.json#", - "title": "Single File STAC Extension", - "description": "Single File STAC Extension to combine Collections and Items in single file catalog", - "allOf": [ - { - "$ref": "../../../catalog-spec/json-schema/catalog.json" - }, - { - "$ref": "https://geojson.org/schema/FeatureCollection.json" - }, - { - "$ref": "#/definitions/single-file-stac" - } - ], - "definitions": { - "single-file-stac": { - "type": "object", - "required": [ - "stac_extensions", - "features" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "enum": [ - "single-file-stac", - "https://schemas.stacspec.org/v1.0.0-beta.2/extensions/single-file-stac/json-schema/schema.json" - ] - } - }, - "collections": { - "type": "array", - "items": { - "$ref": "../../../collection-spec/json-schema/collection.json" - } - }, - "features": { - "type": "array", - "items": { - "$ref": "../../../item-spec/json-schema/item.json" - } - } - } - } - } -} \ No newline at end of file From 0dcf18fbdcbf103e3e2ea8bdd0d81b9d6b81a6be Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 09:41:20 -0700 Subject: [PATCH 08/28] catalog doesn't declare a summaries field --- collection-spec/collection-spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 5f452bdb8..b783650f6 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -57,8 +57,7 @@ Collections are are *strongly recommended* to provide summaries of the values of of STAC Items contained in this Collection. This enables users to get a good sense of what the ranges and potential values of different fields in the Collection are, without to inspect a number of Items (or crawl them exhaustively to get a definitive answer). Summaries help to fully define Collections, especially if they don't link to any Items. They also give clients enough information to -build tailored user interfaces for querying the data, by presenting the potential values that are available. Summaries can be used in -Collections or Catalogs, and they should summarize all values in every Item underneath it, including in nested sub-Catalogs. +build tailored user interfaces for querying the data, by presenting the potential values that are available. Summaries should summarize all values in every Item underneath the collection, including in any nested sub-Catalogs. A summary for a field can be specified in two ways: From 4e746dbe15e25c25b5fe53065e721be47889da12 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 10:00:35 -0700 Subject: [PATCH 09/28] remove more collection <- catalog inheritance language --- collection-spec/README.md | 9 ++++----- overview.md | 32 ++++++++++++++------------------ 2 files changed, 18 insertions(+), 23 deletions(-) diff --git a/collection-spec/README.md b/collection-spec/README.md index dbf1dfc39..c425b6da7 100644 --- a/collection-spec/README.md +++ b/collection-spec/README.md @@ -1,12 +1,11 @@ # STAC Collections 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. +It builds on fields from 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). 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 +The Collection concept can be used very flexibly - it 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 diff --git a/overview.md b/overview.md index e722cab0e..efc48e240 100644 --- a/overview.md +++ b/overview.md @@ -51,19 +51,17 @@ 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 extends the Catalog spec, so every Collection can serve as a catalog, -requiring the same fields. But it 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. +The Collection specification shares some fields with the catalog spec 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. 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 satellite world these would typically all come from the same sensor or constellation. It corresponds -directly to what others call a 'dataset series' (ESA, ISO 19115), 'collection' (CNES, NASA), and -'dataset (JAXA, DCAT)'. So if all your Items have the same properties, they probably belong in +directly to what others call a "dataset series" (ESA, ISO 19115), "collection" (CNES, NASA), and +"dataset" (JAXA, DCAT). So if all your Items have the same properties, they probably belong in the same Collection. But the construct is deliberately flexible, as there may be good reasons -to 'break' the recommendation. +to break the recommendation. Catalogs in turn are used for two main things: @@ -72,7 +70,7 @@ Catalogs in turn are used for two main things: The first case allows users to browse down into the Items of large collections. A collection like Landsat usually would start with path and row Catalogs to group by geography, and then year, -month and day groups to enable deeper. [Dynamic catalogs](best-practices.md#dynamic-catalogs) can +month and day groups to enable deeper grouping. [Dynamic catalogs](best-practices.md#dynamic-catalogs) can 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 @@ -91,7 +89,7 @@ linking structure that can be used recursively so that many Items can be include 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 a top-most catalog (which has no parent). A nested catalog structure is useful (and +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 @@ -118,8 +116,6 @@ catalogs and items: - `Catalog` -> `Catalog` (this is a common tree structure to group sets of Items. Each catalog in this relationship may also include Item links as well as catalog links) -As all STAC Collections are also valid STAC Catalogs, all Catalogs described here could also be Collections. - The relationships are all described by a common `links` object structure, making use of the `rel` field to further describe the relationship. @@ -165,20 +161,20 @@ each Item and Catalog, as well as ways to achieve that. ## Collection Overview -A STAC Collection extends the Catalog construct to provide additional metadata to describe the set of Items it -contains. So every Collection *is* a Catalog, and can be used in the same ways. The required fields are fairly +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 minimal - it inherits 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 fuller metadata (ISO 19115, etc) when it is available. -As Collections are Catalogs, they can be used just as flexibly. They can have both parent Catalogs and Collections +As Collections contain all of Catalogs' core fields, they can be used just as flexibly. They can have both parent Catalogs and Collections as well as child Items, Catalogs and Collections. Items are strongly recommended to have a link to the Collection -they are a part of. Items can only belong to one Collection, so if an Item is in Collections that is the child of +they are a part of. Items can only belong to one Collection, so if an Item is in a Collection that is the child of another Collection, then it must pick which one to refer to. Generally the 'closer' Collection, the more specific -one, should be the one linked to. +one, should be the one linked to. -The Collection specification is used standalone quite easily - it is used to just describe an aggregation of data, +The Collection specification is used standalone quite easily - it is used to describe an aggregation of data, and doesn't require links down to sub-catalogs and Items. This is most often used when the software does operations at the layer / coverage level, letting users manipulate a whole collection of assets at once. They often have an optimized internal format that doesn't make sense to expose as Items. [OpenEO](https://openeo.org/) and From 740e4515e781f50f0fcee2de56c14a924aebca5a Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 10:10:32 -0700 Subject: [PATCH 10/28] remove inheritance refs from best-practices --- best-practices.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/best-practices.md b/best-practices.md index 2bea3912b..3a57d93a3 100644 --- a/best-practices.md +++ b/best-practices.md @@ -356,8 +356,10 @@ as they can only have a single representation of their catalog, since the static While it is up to the implementor to organize the catalog, it is recommended to arrange it in a way that would make sense for a human to browse a set of STAC Items in an intuitive matter. -The recommendation for static catalogs is to define them using the file name `catalog.json` or `collection.json` to distinguish -the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice +Users indicate their intent for a file to be parsed as a Collection or Catalog using the required `type` field on +each entity. For Collections, this field must have the value `"Collection"`, while for Catalogs, it must have the +value `"Catalog"`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json` +or `collection.json` to distinguish the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice is to place the Catalog file in namespaces "directories". For example: - current/catalog.json @@ -373,7 +375,7 @@ for clients to consume. A dynamic catalog will sometimes be populated by a stati fields stored as a cached static catalog. Dynamic catalogs often also implement the [STAC API](https://github.com/radiantearth/stac-api-spec/) specification, that -responds to search queries (like give me all imagery in Oahu gathered on January 15, 2017). But they are not required to. One +responds to search queries (like "give me all imagery in Oahu gathered on January 15, 2017"). But they are not required to. One can have a dynamic service that only implements the core STAC specification, and is crawled by STAC API implementations that provide 'search'. For example a Content Management Service like Drupal or an open data catalog like CKAN could choose to expose its content as linked STAC Items by implementing a dynamic catalog. @@ -400,7 +402,7 @@ ended up doing. Following these recommendations makes for more legible catalogs, if you follow these recommendations. 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog. -2. Catalogs that are not also Collections should be named `catalog.json` and Collections should be named `collection.json`. +2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`. 3. Items should be named `.json`. 4. Sub-Catalogs should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent) (e.g. `.../sample/sub1/catalog.json`). 5. Items should be stored in subdirectories of their parent Catalog. @@ -632,25 +634,21 @@ Collection, Catalog or [ItemCollection](https://github.com/radiantearth/stac-api (part of the [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1). As of 1.0.0 this is done primarily with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. ```shell -if type is defined - if type is 'Feature' and stac_version is defined // stac_version in items is only available since 0.8, check for (stac_version or assets) to support pre-0.8 data - => Item - else if type is 'FeatureCollection' and stac_version is defined - => ItemCollection - else if type is `Collection` - => Collection - else if type is `Catalog` - => Catalog - else - => Invalid (GeoJSON) +if type is `Collection` + => Collection +else if type is `Catalog` + => Catalog +else if type is 'Feature' and stac_version is defined // stac_version in items is only available since 0.8, check for (stac_version or assets) to support pre-0.8 data + => Item +else if type is 'FeatureCollection' and stac_version is defined + => ItemCollection else - => Invalid (JSON) + => Invalid (GeoJSON) ``` When actually crawling a STAC implementation one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or -`root` then it must be a Catalog or a Collection, and thus can be treated as a Catalog (as a Collection is a Catalog), and then the -`type` field can be used to distinguish if it is a Collection. +`root` then it must be a Catalog or a Collection, and the `type` field can be used to distinguish which one. In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works From 1742c81dd5ad6eed608b35bb4ade19268d34f9f0 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 11:27:21 -0600 Subject: [PATCH 11/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 3a57d93a3..62a9d531a 100644 --- a/best-practices.md +++ b/best-practices.md @@ -358,7 +358,7 @@ for a human to browse a set of STAC Items in an intuitive matter. Users indicate their intent for a file to be parsed as a Collection or Catalog using the required `type` field on each entity. For Collections, this field must have the value `"Collection"`, while for Catalogs, it must have the -value `"Catalog"`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json` +value `Catalog`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json` or `collection.json` to distinguish the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice is to place the Catalog file in namespaces "directories". For example: From 2b9840ee20b23e66a79c6ea16cd56e39e1d5b58c Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 11:27:30 -0600 Subject: [PATCH 12/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 62a9d531a..0d711f6c2 100644 --- a/best-practices.md +++ b/best-practices.md @@ -357,7 +357,7 @@ While it is up to the implementor to organize the catalog, it is recommended to for a human to browse a set of STAC Items in an intuitive matter. Users indicate their intent for a file to be parsed as a Collection or Catalog using the required `type` field on -each entity. For Collections, this field must have the value `"Collection"`, while for Catalogs, it must have the +each entity. For Collections, this field must have the value `Collection`, while for Catalogs, it must have the value `Catalog`. Additionally, we recommend for static STACs indicate contents using the filenames `catalog.json` or `collection.json` to distinguish the Catalog from other JSON type files. In order to support multiple catalogs, the recommended practice is to place the Catalog file in namespaces "directories". For example: From e77843a337338a7a1f0ac0124c1dce580fe32626 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Tue, 2 Mar 2021 10:29:49 -0700 Subject: [PATCH 13/28] capitalization --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index b783650f6..d1ffef2be 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -176,7 +176,7 @@ This is done where there is not a clear official option, or where STAC uses an o | 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. | | 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). | +| 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. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | From b63641cfbb8531e739891d0f08c896df44aba66b Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 2 Mar 2021 14:25:12 -0800 Subject: [PATCH 14/28] fixed small typo --- best-practices.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 0d711f6c2..bd923988c 100644 --- a/best-practices.md +++ b/best-practices.md @@ -631,7 +631,8 @@ database, but it could just as easily be a server-based process. Any tool that crawls a STAC implementation or encounters a STAC file in the wild needs a clear way to determine if it is an Item, Collection, Catalog or [ItemCollection](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1/fragments/itemcollection) -(part of the [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1). As of 1.0.0 this is done primarily with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. +(part of the [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1)). As of 1.0.0 this is done primarily +with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. ```shell if type is `Collection` From 75a9acddac141cb232cab6451ed5cbd6164a3508 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 2 Mar 2021 14:28:22 -0800 Subject: [PATCH 15/28] typo fix: entityt -> entity --- catalog-spec/json-schema/catalog.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 301236e97..0d4f93df3 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -20,7 +20,7 @@ ], "properties": { "type": { - "title": "Type of STAC entityt", + "title": "Type of STAC entity", "const": "Catalog" } } From 7e5d0f5659e4075f92665b1c1f3556a55904980d Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:07:52 -0800 Subject: [PATCH 16/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index bd923988c..fb76f5475 100644 --- a/best-practices.md +++ b/best-practices.md @@ -653,4 +653,4 @@ When actually crawling a STAC implementation one can also make use of the [relat In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works -for older STAC versions (to 0.8.0, older than that should not be needed). +for older STAC versions. From 4b20b90fddd87c6a5a5f69b30f3277695f410f1f Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:08:09 -0800 Subject: [PATCH 17/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index fb76f5475..289337ab9 100644 --- a/best-practices.md +++ b/best-practices.md @@ -635,7 +635,7 @@ Collection, Catalog or [ItemCollection](https://github.com/radiantearth/stac-api with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. ```shell -if type is `Collection` +if type is 'Collection' => Collection else if type is `Catalog` => Catalog From 1c2db9bc3dd0da9f9d6eabfc6a7c71d0f66ec778 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:08:18 -0800 Subject: [PATCH 18/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 289337ab9..713cbaad4 100644 --- a/best-practices.md +++ b/best-practices.md @@ -637,7 +637,7 @@ with the `type` field, and secondarily in Items with `stac_version`, or optional ```shell if type is 'Collection' => Collection -else if type is `Catalog` +else if type is 'Catalog' => Catalog else if type is 'Feature' and stac_version is defined // stac_version in items is only available since 0.8, check for (stac_version or assets) to support pre-0.8 data => Item From 97362a5d5b3c2f7a486422b3b05ae6b0265f204e Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:08:30 -0800 Subject: [PATCH 19/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 713cbaad4..8ebadbfe1 100644 --- a/best-practices.md +++ b/best-practices.md @@ -639,7 +639,7 @@ if type is 'Collection' => Collection else if type is 'Catalog' => Catalog -else if type is 'Feature' and stac_version is defined // stac_version in items is only available since 0.8, check for (stac_version or assets) to support pre-0.8 data +else if type is 'Feature' and stac_version is defined => Item else if type is 'FeatureCollection' and stac_version is defined => ItemCollection From bdf49d5aeee0b974b69f385940287c8c1c95ef13 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:08:43 -0800 Subject: [PATCH 20/28] Update best-practices.md Co-authored-by: Matthias Mohr --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 8ebadbfe1..ef1c7050d 100644 --- a/best-practices.md +++ b/best-practices.md @@ -644,7 +644,7 @@ else if type is 'Feature' and stac_version is defined else if type is 'FeatureCollection' and stac_version is defined => ItemCollection else - => Invalid (GeoJSON) + => Invalid (JSON) ``` When actually crawling a STAC implementation one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types From fdb6deb937c83722d8e95eb9cf3f9699c0a5906e Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 06:10:51 -0800 Subject: [PATCH 21/28] Update collection-spec/collection-spec.md Co-authored-by: Matthias Mohr --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index d1ffef2be..592eff4dc 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -182,7 +182,7 @@ This is done where there is not a clear official option, or where STAC uses an o A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. -**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`Collection` relation type](../item-spec/item-spec.md#relation-types). +**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). ### Asset Object From 4133b1d967af993b1fff2fe76c9f43bc9c80c85e Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 07:42:31 -0800 Subject: [PATCH 22/28] Update best-practices.md Co-authored-by: Phil Varner --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index ef1c7050d..4948cb5d4 100644 --- a/best-practices.md +++ b/best-practices.md @@ -647,7 +647,7 @@ else => Invalid (JSON) ``` -When actually crawling a STAC implementation one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types +When crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or `root` then it must be a Catalog or a Collection, and the `type` field can be used to distinguish which one. From c624dac36a3508414835b534fdaf1742300600c5 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 07:49:25 -0800 Subject: [PATCH 23/28] Clarity on which type field to use --- best-practices.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 4948cb5d4..32295d645 100644 --- a/best-practices.md +++ b/best-practices.md @@ -649,7 +649,8 @@ else When crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or -`root` then it must be a Catalog or a Collection, and the `type` field can be used to distinguish which one. +`root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the the `type` field +in the Catalog or Collection JSON that is linked to. In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works From 339ac7e302e03ee042cf7c34001f8eaf07ebd1f6 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 07:50:31 -0800 Subject: [PATCH 24/28] Update from PR review --- catalog-spec/catalog-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 7e741f67e..5c71b5a94 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -40,7 +40,7 @@ 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, or `Collection` if it additional meets the [collection](../collection-spec/collection-spec.md) requirements and should be treated by clients as such. | +| type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | | 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. | From 6f3489793578159eb4c730f3686d0b9829bc3724 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 07:55:17 -0800 Subject: [PATCH 25/28] Added line back in that was removed. --- overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/overview.md b/overview.md index efc48e240..cb8285a0a 100644 --- a/overview.md +++ b/overview.md @@ -53,7 +53,8 @@ also hold other containers (folders / catalogs). The Collection specification shares some fields with the catalog spec 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. +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. 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 From 681264c75b9fb9eca9d4f491ae2de5571e8330fd Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 08:05:35 -0800 Subject: [PATCH 26/28] More clarity on types. --- best-practices.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 32295d645..cf288e800 100644 --- a/best-practices.md +++ b/best-practices.md @@ -650,7 +650,9 @@ else When crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or `root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the the `type` field -in the Catalog or Collection JSON that is linked to. +in the Catalog or Collection JSON that is linked to. Note that there is also a `type` field in STAC Link and Asset objects, but that +is for the Media Type, but there are not specific media types for Catalog and Collection. See the sections on [STAC media +types](catalog-spec/catalog-spec.md#media-types), and [Asset media types](item-spec/item-spec.md#asset-media-type) for more information. In versions of STAC prior to 1.0 the process was a bit more complicated, as there was no `type` field for catalogs and collections. See [this issue comment](https://github.com/radiantearth/stac-spec/issues/889#issuecomment-684529444) for a heuristic that works From 24e54764c5dc566fde534bfdebcd08dae49c1f5c Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 08:16:41 -0800 Subject: [PATCH 27/28] More on what collections share with catalogs --- collection-spec/collection-spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 592eff4dc..ce7405cab 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -1,8 +1,9 @@ # STAC Collection Specification The STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata. The -Collection Specification shares some fields with the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) with additional fields to -describe the whole dataset and the included set of Items. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. +Collection Specification shares all fields with the STAC [Catalog Specification](../catalog-spec/catalog-spec.md) (with different allowed +values for `type` and `stac_extensions`) and adds fields to describe the whole dataset and the included set of Items. Collections +can have both parent Catalogs and Collections and child Items, Catalogs and Collections. A STAC Collection is represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. From 44f4e6d61f56578d73d018a19f86bb6cf10e3052 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 3 Mar 2021 08:45:13 -0800 Subject: [PATCH 28/28] removed inherits language --- overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/overview.md b/overview.md index cb8285a0a..55cf13f67 100644 --- a/overview.md +++ b/overview.md @@ -164,7 +164,7 @@ each Item and Catalog, as well as ways to achieve that. 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 -minimal - it inherits the 4 required Catalog fields (id, description, stac_version and links), and adds license +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 fuller metadata (ISO 19115, etc) when it is available.