diff --git a/.circleci/config.yml b/.circleci/config.yml index 3f1d938fd..67d786485 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -21,7 +21,7 @@ jobs: command: | cd validation npm run validate_catalog -- -d ../catalog-spec/examples/catalog.json - npm run validate_dataset -- -d ../dataset-spec/examples/sentinel2.json + npm run validate_collection -- -d ../collection-spec/examples/sentinel2.json npm run validate_extension -- -s ../extensions/scientific/schema.json -d ../extensions/scientific/example-merraclim.json npm run validate_item -- -d ../item-spec/examples/sample.json # ToDo: More files should be validated diff --git a/contribute.md b/CONTRIBUTING.md similarity index 100% rename from contribute.md rename to CONTRIBUTING.md diff --git a/README.md b/README.md index bbe15d7df..daa3358cc 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ The specification is currently still an early version, with the potential for so fleshed out, so implementors are encouraged to try it out and give feedback. But the goal is to actually be able to act on that feedback, which will mean changes are quite possible. -But efforts will be made to maintain the core fields established in the central [Item spec](item-spec/) and -[Catalog spec](catalog-spec). The minimal amount is specified right now, but best practices should emerge with -implementation and more will likely be specified. +But efforts will be made to maintain the core fields established in the central [Item spec](item-spec/), +[Catalog spec](catalog-spec/) and [Collection spec](collection-spec/). +The minimal amount is specified right now, but best practices should emerge with implementation and more will likely be specified. ## Current version and branches @@ -40,7 +40,7 @@ not require lots of updating. For any questions feel free to jump on our [gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby) or email our [google group](https://groups.google.com/forum/#!forum/stac-spec). The majority of communication about the evolution of the specification takes place in the [issue tracker](https://github.com/radiantearth/stac-spec/issues) and in -[pull requests](https://github.com/radiantearth/stac-spec/pulls) +[pull requests](https://github.com/radiantearth/stac-spec/pulls). ## In this Repository @@ -50,24 +50,25 @@ README explaining the layout of the folder, the main specification document, exa documents (if relevant). The four specifications detailed are meant to be used together, but are designed so each piece is small, self-contained and reusable in other contexts. -**[item-spec/](item-spec/)** defines a SpatioTemporal Asset Catalog `Item`, which is a [GeoJSON](http://geojson.org) Feature +**[item-spec/](item-spec/)** defines a STAC Item, which is a [GeoJSON](http://geojson.org) Feature with additional fields for things like time, links to related entities and assets (including thumbnails). This is the atomic unit that describes the data to be discovered. -**[catalog-spec/](catalog-spec/)** specifies a structure to link various `Items` together to be crawled or browsed. It is a -simple, flexible JSON file of links to `Item`s or other `Catalogs` that can be used in a variety of ways. +**[catalog-spec/](catalog-spec/)** specifies a structure to link various STAC Items together to be crawled or browsed. It is a +simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways. -**[dataset-spec/](dataset-spec/)** provides additional information about a set of `Item`s that are made available by a -data provider. It includes things like the spatial and temporal extent of the set of data, the license, keywords, etc. It -enables discovery at a higher level than individual items, providing a simple way to describe sets of data. +**[collection-spec/](collection-spec/)** provides additional information about a spatio-temporal collection of data. +In the context of STAC it is most likely a collection of STAC Items that is made available by a data provider. +It includes things like the spatial and temporal extent of the data, the license, keywords, etc. +It enables discovery at a higher level than individual items, providing a simple way to describe sets of data. **[api-spec/](api-spec/)** extends the core publishing capabilities of STAC with an active REST search endpoint that returns -just the `Item`s a user requests in their query. It is specified as a couple [OpenAPI](http://openapis.org) documents, one +just the Items a user requests in their query. It is specified as a couple [OpenAPI](http://openapis.org) documents, one [standalone](api-spec/STAC-standalone.yaml) and one that is [integrated with WFS3](api-spec/WFS3core%2BSTAC.yaml) -(see [wfs github](https://github.com/opengeospatial/wfs_fes) for info on it). The documents also include the `/stac/` -endpoint which is a way for a dynamic server to provide catalog and dataset browsing. +(see [WFS3 on GitHub](https://github.com/opengeospatial/wfs_fes) for info on it). The documents also include the `/stac/` +endpoint which is a way for a dynamic server to provide catalog and collection browsing. -**Extensions:** The *[extensions/](extensions/)* folder is where extensions (profiles) live. Extensions can extend the +**Extensions:** The *[extensions/](extensions/)* folder is where extensions live. Extensions can extend the functionality of the core spec or add fields for specific domains. **Additional documents** include the current [roadmap](roadmap.md) and a complementary [how to help](how-to-help.md) @@ -78,7 +79,8 @@ and a discussion of the collaboration [principles](principles.md) and specificat An important core principle of the STAC design is to embrace best practices of making data available on the web (like [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) and [W3C Spatial Data on the Web](https://www.w3.org/TR/sdw-bp/)), and -to leverage the reliability of flat files on object stores like [AWS S3](https://aws.amazon.com/s3/) and [Google Cloud Storage](https://cloud.google.com/storage/). This leads to putting the 'static catalog' at the core of the STAC spec. +to leverage the reliability of flat files on object stores like [AWS S3](https://aws.amazon.com/s3/) and [Google Cloud Storage](https://cloud.google.com/storage/). +This leaded to designing a static catalog at the core of the STAC spec. #### Static Catalog @@ -99,17 +101,14 @@ or at least may have a 'backup' of its fields stored as a cached static catalog. #### Core Metadata and Extensions -The [SpatioTemporal Asset Metadata](https://github.com/radiantearth/stam-spec) specification defines the core fields that all -assets must make available for searching in a catalog. Vendors can extend those core fields for the metadata they want to -make available, and the community is starting to define shared extensions, with 'electro-optical' being -the first one. This repo contains the [STAC Item](item-spec/item-spec.md) definition, which is the primary json extension of STAM, -so it can evolve with the rest of the STAC spec more easily. The STAM repo retains the abstract definition, and may evolve -to contain other extensions. +The Item specification defines the core fields that all assets must make available for searching in a catalog. +In addition there are some basic fields for describing collections of data. +Vendors can extend those core fields for the metadata they want to make available, and the community has started to define shared extensions. ## Contributing Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate. -Beforehand, please review our [guidelines for contributions](contribute.md). +Beforehand, please review our [guidelines for contributions](CONTRIBUTING.md). diff --git a/api-spec/README.md b/api-spec/README.md index 8ef38b496..9e24c4441 100644 --- a/api-spec/README.md +++ b/api-spec/README.md @@ -1,11 +1,8 @@ - # STAC API Specification -## Overview - -A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns [STAC Items](../item-spec/item-spec.md) -(GeoJSON objects with required links time stamp and links to assets) from search queries on a RESTful endpoint, and also -offers an endpoint to return STAC Items as a compliant [Catalog](../catalog-spec/) for discovery. +A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns [STAC Items](../item-spec/README.md) +(GeoJSON objects with required links, time stamp and links to assets) from search queries on a RESTful endpoint, and also +offers an endpoint to return STAC Items as a compliant [STAC Catalog](../catalog-spec/README.md) for discovery. The core of the spec is a single endpoint: @@ -16,7 +13,6 @@ The core of the spec is a single endpoint: It takes a JSON object that can filter on date and time: ``` - { "bbox": [ 5.5, 46, 8, 47.4 ], "time": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" @@ -31,18 +27,18 @@ that fall within this area: *map © OpenStreetMap contributors* The return format is a [GeoJSON](http://geojson.org) feature collection with features compliant with the -[Item spec]((../item-spec/item-spec.md) for STAC. It returns to a limit optionally requested by the client, and includes +[Item spec]((../item-spec/README.md) for STAC. It returns to a limit optionally requested by the client, and includes pageable links to iterate through any results past that limit. -### Dynamic Catalog API +## Dynamic Catalog API -The other endpoint that is included as an option in STAC API is `/stac/`, which implements the [Catalog Spec](../catalog-spec/). +The other endpoint that is included as an option in STAC API is `/stac/`, which implements the [STAC Catalog Spec](../catalog-spec/README.md). See the [Dynamic Catalog](https://github.com/radiantearth/stac-spec/blob/structure_and_cleanup/catalog-spec/catalog-spec.md#dynamic-catalogs) section of that spec for more information. Implementing this enables tools like [STAC Browser](https://medium.com/@mojodna/a-stac-browser-348a60674061) to use the dynamic catalog, to enable better discovery through people browsing and search engines crawling. -The OpenAPI spec in this directory documents the endpoint, and refer to the Catalog and [Dataset](../dataset-spec) for more information about the full content and link structure. +The OpenAPI spec in this directory documents the endpoint, and refer to the STAC Catalog and [STAC Collection](../collection-spec/README.md) for more information about the full content and link structure. ## API Fragments diff --git a/api-spec/STAC-query.yaml b/api-spec/STAC-query.yaml index 8098c5c01..fc485bda9 100644 --- a/api-spec/STAC-query.yaml +++ b/api-spec/STAC-query.yaml @@ -512,15 +512,15 @@ components: additionalProperties: description: Any additional properties added in via extensions. itemCollectionLinks: - type: object - properties: - next: - type: string - format: url - description: >- - A URL to obtain the next paginated data set. If not present, the - client should utilize the `nextPageToken`. - example: >- + type: array + description: >- + An array of links. Can be used for pagination, e.g. by providing a link + with the `next` relation type. + items: + $ref: '#/components/schemas/link' + example: + - rel: next + href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk queryFilter: type: object diff --git a/api-spec/STAC-standalone.yaml b/api-spec/STAC-standalone.yaml index f849bf05d..4e2458fdc 100644 --- a/api-spec/STAC-standalone.yaml +++ b/api-spec/STAC-standalone.yaml @@ -481,15 +481,15 @@ components: additionalProperties: description: Any additional properties added in via extensions. itemCollectionLinks: - type: object - properties: - next: - type: string - format: url - description: >- - A URL to obtain the next paginated data set. If not present, the - client should utilize the `nextPageToken`. - example: >- + type: array + description: >- + An array of links. Can be used for pagination, e.g. by providing a link + with the `next` relation type. + items: + $ref: '#/components/schemas/link' + example: + - rel: next + href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk tags: - name: STAC diff --git a/api-spec/WFS3core+STAC.yaml b/api-spec/WFS3core+STAC.yaml index 10ca57f63..a54cb584c 100644 --- a/api-spec/WFS3core+STAC.yaml +++ b/api-spec/WFS3core+STAC.yaml @@ -640,15 +640,15 @@ components: additionalProperties: description: Any additional properties added in via extensions. itemCollectionLinks: - type: object - properties: - next: - type: string - format: url - description: >- - A URL to obtain the next paginated data set. If not present, the - client should utilize the `nextPageToken`. - example: >- + type: array + description: >- + An array of links. Can be used for pagination, e.g. by providing a link + with the `next` relation type. + items: + $ref: '#/components/schemas/link' + example: + - rel: next + href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk root: type: object @@ -785,11 +785,11 @@ components: - properties - constructions version: - title: Dataset Version + title: Collection Version type: string example: 1 license: - title: Dataset License Name + title: Collection License Name type: string example: Apache-2.0 provider: diff --git a/api-spec/definitions/STAC-collections.fragment.yaml b/api-spec/definitions/STAC-collections.fragment.yaml index e10c98173..9e786bbaf 100644 --- a/api-spec/definitions/STAC-collections.fragment.yaml +++ b/api-spec/definitions/STAC-collections.fragment.yaml @@ -26,11 +26,11 @@ components: - properties - constructions version: - title: Dataset Version + title: Collection Version type: string example: 1 license: - title: Dataset License Name + title: Collection License Name type: string example: Apache-2.0 provider: diff --git a/api-spec/definitions/STAC-standalone.yaml b/api-spec/definitions/STAC-standalone.yaml index 7c61558a0..3d4dd675c 100644 --- a/api-spec/definitions/STAC-standalone.yaml +++ b/api-spec/definitions/STAC-standalone.yaml @@ -474,16 +474,14 @@ components: additionalProperties: description: Any additional properties added in via extensions. itemCollectionLinks: - type: object - properties: - next: - type: string - format: url - description: >- - A URL to obtain the next paginated data set. If not present, the - client should utilize the `nextPageToken`. - example: >- - http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk + type: array + description: >- + An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type. + items: + $ref: '#/components/schemas/link' + example: + - rel: next + href: http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk tags: - name: STAC description: Extension to WFS3 Core to support STAC metadata model and search API diff --git a/api-spec/wfs-stac.md b/api-spec/wfs-stac.md index 8829ff0ec..64cdc3854 100644 --- a/api-spec/wfs-stac.md +++ b/api-spec/wfs-stac.md @@ -26,16 +26,17 @@ that capability. So any WFS that is providing data that can be represented as ST STAC endpoint. In addition to the `/stac/search` endpoint, STAC API's provide the ability to 'browse' all the [Items](../item-spec/) that -are available from a service. This is done using the `/stac/` endpoint, returning a full [STAC Catalog](../catalog-spec/). Ideally that Catalog makes extensive use of [STAC Datasets](../dataset-spec/) to further describe the holdings. +are available from a service. This is done using the `/stac/` endpoint, returning a full [STAC Catalog](../catalog-spec/). +Ideally that Catalog makes extensive use of [STAC Collections](../collection-spec/) to further describe the holdings. -The STAC Dataset spec is designed to be compatible with the WFS /collections/{collectionId} endpoint's response. This enables -WFS + STAC implementations to just extend their collections with a bit more information to be STAC Compliant dataset +The STAC Collection spec is designed to be compatible with the WFS /collections/{collectionId} endpoint's response. This enables +WFS + STAC implementations to just extend the WFS collections with a bit more information to be STAC compliant Collection definitions. An additional best practice is to use the WFS items available in /collections/{collectionId}/items as the 'canonical' web location. Then the STAC Catalogs returned from `/stac/` can either link directly to those (from the appropriate sub-catalog - for example /stac/landsat8/42/31/2017/ would be a catalog consisting of links to /collections/). Or it can return json -in the link structure (like /stac/landsat8/42/31/2017/item203123.json), and have that returned json use a link with rel=canonical that goes back to the `Item` that is in the collection. +in the link structure (like /stac/landsat8/42/31/2017/item203123.json), and have that returned json use a link with rel=canonical that goes back to the Item that is in the collection. ### WFS Structure @@ -47,8 +48,9 @@ GET /collections Lists the collections of data on the server that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)), and each describes basic information about the geospatial data collection, like its name and description, as well as the -spatial and temporal extents of all the data contained. A STAC search extension would only query those collections which -have data that validates as STAC `Items` - with a datetime field and references to assets. But a STAC can live alongside +spatial and temporal extents of all the data contained. The collections returned are compliant to both WFS Collections and +[STAC collections](../collections-spec/README.md). A STAC search extension would only query those collections which +have data that validates as STAC Items - with a datetime field and references to assets. But a STAC can live alongside other WFS collections, like an organization might choose to have their building and road data in WFS collections, alongside their STAC-compatible imagery data. diff --git a/catalog-spec/README.md b/catalog-spec/README.md index 45d35755e..e5d8a9342 100644 --- a/catalog-spec/README.md +++ b/catalog-spec/README.md @@ -1,13 +1,14 @@ # STAC Catalogs -While an [Item](../item-spec/item-spec.md) is the atomic unit of a SpatioTemporal Asset Catalog, the Catalog JSON definition is the core structure that enables browsers and crawlers to access +While a [STAC Item](../item-spec/item-spec.md) is the atomic unit of a SpatioTemporal Asset Catalog, +the Catalog JSON definition is the core structure that enables browsers and crawlers to access the sets of Items. A Catalog consists of links to other Catalogs and Items, and can include additional metadata to further describe its holdings. It is defined in full in the -[Catalog Specification](catalog-spec.md). +[STAC Catalog Specification](catalog-spec.md). -While Catalogs mostly describe a structure of links and Items, a key related specification is the [Datasets](../dataset-spec/) -spec, which extend Catalogs with additional fields to further describe the set of Items in a Catalog. Datasets share the same -fields with Catalogs and therefore every Dataset is also a valid Catalog. +While STAC Catalogs mostly describe a structure of links and Items, a key related specification is the [STAC Collection Specification](../collection-spec/), +which extends Catalogs with additional fields to further describe the set of Items in a Catalog. STAC Collections share the same +fields with Catalogs and therefore every Collection is also a valid Catalog. Catalogs are designed so that a simple file server on the web or object store like Amazon S3 can store JSON that defines a full Catalog. More dynamic services can also return a Catalog structure, and the [STAC API](../api-spec/) folder contains @@ -15,18 +16,18 @@ an OpenAPI definition of the standard way to do this, at the `/stac/` endpoint. ## In this directory -**The Specification:** The main Catalog specification is in -*[catalog-spec.md](catalog-spec.md)*. It includes an overview and in depth explanation of the -structures and fields. +**The Specification:** The main Catalog specification is in *[catalog-spec.md](catalog-spec.md)*. +It includes an overview and in depth explanation of the structures and fields. **Examples:** For samples of how Catalogs can be implemented the *[examples/](examples/)* folder contains a full sample catalog. -**Schemas:** The schemas to validate the core `Catalog` definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[catalog.json](json-schema/catalog.json)*. +**Schemas:** The schemas to validate the core Catalog definition are found in the *[json-schema/](json-schema/)* folder. +The primary one is *[catalog.json](json-schema/catalog.json)*. ## In the API directory -**Dynamic Catalog OpenAPI Definition:** The [stac-api](../api-spec) directory contains OpenAPI definitions of the `/stac/` +**Dynamic Catalog OpenAPI Definition:** The [api-spec](../api-spec) directory contains OpenAPI definitions of the `/stac/` endpoint, that is the dynamic version of a Catalog. See [STAC-standalone.yaml](../api-spec/STAC-standalone.yaml), or you can browse it online on [swaggerhub's STAC-standalone](https://app.swaggerhub.com/apis/cholmesgeo/STAC-standalone/0.6.0-beta#/STAC/get_stac) definition. @@ -43,9 +44,3 @@ be defined in additional specifications and extensions. The only anticipated cha additional extension mechanisms for others to use. -#### Recommendations - -The evolution of static catalogs is driven by real implementations in the world. Many are adding in additional innovations -that are not yet part of the specification, but other implementors are encouraged to make use of. The various recommendations -can be viewed in the [Catalog Recommendations](catalog-recommendations.md) document. Some of these will likely -evolve to be requirements, or at least documented specification options and extensions. diff --git a/catalog-spec/catalog-recommendations.md b/catalog-spec/catalog-recommendations.md deleted file mode 100644 index d58d7eaa4..000000000 --- a/catalog-spec/catalog-recommendations.md +++ /dev/null @@ -1,126 +0,0 @@ -# About - -This document represents a number of ideas for options and requirements that are under discussion. -Some will likely evolve in to requirements, or at least documented specification extensions. But there -is not yet enough consensus on how to represent them. - -### Metadata Linking - -In general STAC aims to be oriented around **search**, centered on the core fields that users will want to search on to find imagery. -The core is space and time, but there are often other metadata attributes that are useful. While the specification is flexible enough that -providers can fill it with tens or even hundreds of fields of metadata that is not recommended. If providers have lots of metadata then -that should be linked to in an 'asset', indeed even a new json asset that is potentially easier to parse. There is a lot of metadata that -is only of relevance to advanced processing algorithms, and while that is important it should not be in the core STAC items. - - -### Prefixes - -A spatiotemporal asset catalog item can combine schema information from several different sources - the core STAC item information, -an earth observation community extension, and a vendor specific provider. It can be difficult to distinguish exactly where each definition -came from, and to pull out the most relevant information, especially when vendors often will dump in all the metadata they have in to the -STAC definition. - -So one idea is to have prefixes to differentiate specific vendors (like dg: for DigitalGlobe), and for communities of practice (like eo: for Earth -Observation). These wouldn't be full namespacing, though an extension for like JSON-LD could potentially evolve to make fully resolved namespacing -an option. - -An example of this can be seen in a Landsat example: - -```json - - "properties": { - "start_datetime": "2014-06-02T2014-06-02", - "end_datetime": "2014-06-02T2014-06-02", - "provider": "LANDSAT_8", - "license": "PDDL-1.0", - - "eo:off_nadir_angle" : -0.001, - "eo:cloud_cover" : 10.31, - "eo:sun_azimuth" : 149.01607154, - "eo:sun_elevation" : 59.21424700, - "eo:resolution" : 30, - - "l8:data_type": "L1T", - "l8:wrs_path": 153, - "l8:wrs_row": 25, - "l8:earth_sun_distance": 1.0141560, - "l8:ground_control_points_verify": 114, - "l8:geometric_rmse_model": 7.562, - "l8:image_quality_tirs": 9, - "l8:ground_control_points_model": 313, - "l8:geometric_rmse_model_x": 5.96, - "l8:geometric_rmse_model_y": 4.654, - "l8:geometric_rmse_verify": 5.364, - "l8:image_quality_oli": 9 - - }, - -``` - - - -### Asset definition - -**Note: 0.6.0 defines Media types for assets, to provide more information about what is download, but there is likely -more work to be done to fully define the asset, so this section is left in for discussion** - - -It is of top priority to provide definitions of assets, so clients can know get some information as to -what is actually contained in the data they are downloading. Assets should contain the metadata that is -specific to the format of the asset. The asset must have some way to state its format. - -While assets in Catalog APIs can easily represent files that are generated on demand, a static -catalog should only list assets that already exist online. This increases the reliability and speed -of the catalog and makes it easier to fully duplicate or back-up a static catalog. - - - There are a couple of ideas on how to define metadata for assets: - -#### Inline Asset Definition - -In this scenario assets would include a number of optional metadata fields that would provide additional -definition for clients. See for example DigitalGlobe's definition: - -```json - - { - "href": "https://digitalglobe.com/catalog-spec/L1B/15NOV09180446-M1BS-056823192010_01_P002.TIF", - "metadata": { - "filetype": "geotif", - "content": "image", - "processing": { - "RadiometricallyCorrected": true - } - }, - - ``` - - They then define the bands for the product directly within the 'properties'. - -#### Linking to common definitions - -In this scenario, an `Asset` must have some field that specifies a uri to a JSON file that has the additional metadata. - -This would make sense at a Catalog or Dataset level, though more work is needed to define exactly how it would look. It -could be a generic Asset Definition JSON set of fields, that could be added at the dataset level or could be used -independently. Ideally each Asset would have a way to link directly to its definition. - -See for example a sample landsat definition: - -```json - - { - "href": "LC81530252014153LGN00_B4.TIF", - "product" : "http://landsat-pds.s3.amazonaws.com/L8/landsat8_product-band-4.json", - }, - -``` - -All the needed metadata for a client would be in the product level definition, which would mean a lot less -repeating of fields. But clients would have to be a bit smarter to actually follow the links. Though ideally -clients would be able to cache and reuse product definitions, and hopefully there would be a small number -of canonical product definitions online, that all static catalogs using a particular provider would be -able to reference. - - - diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 3e1b956e8..ef2dd317c 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -1,7 +1,7 @@ # STAC Catalog Specification -This document explains the structure and content of a STAC `Catalog`. A STAC Catalog is a -collection of SpatioTemporal `Item`s. These `Item`s can be linked to directly from a Catalog, +This document explains the structure and content of a STAC Catalog. A STAC Catalog is a +collection of [STAC Items](../item-spec/). These Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain links to Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of online browsing by people. @@ -15,8 +15,9 @@ that contains all the required fields is a valid STAC Catalog. This Catalog specification primarily defines a structure for information to be discoverable. Any use that is publishing a set of related spatiotemporal assets is strongly recommended to also use the -[Dataset specification](../dataset-spec/) to provide additional information about a set of `Item`s -contained in a catalog, to give contextual information to aid in discovery. +[STAC Collection specification](../collection-spec/) to provide additional information about a set of Items +contained in a catalog, to give contextual information to aid in discovery. Every STAC Collection is +also a valid STAC Catalog. ## WARNING @@ -30,19 +31,17 @@ incorporated. ## Catalog Definitions - There are two required element types of a Catalog: Catalog and Item. A STAC Catalog -points to [STAC Items](../item-spec/), or to other STAC catalogs. It provides a simple -linking structure that can be used recursively so that many `Items` can be included in +points to [STAC Items](../item-spec/README.md), or to other STAC catalogs. It provides a simple +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 a top-most `catalog` (which has no parent). A nested `catalog` structure is useful (and +is simply a top-most catalog (which 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, +it might make sense to organize a catalog by date (year, month, day), or geography (continent, country, state/prov). Any scheme may be used, but it's considered a best practice to keep the size -of each `catalog` under a a megabyte. - +of each catalog under a megabyte. A simple Catalog structure might look like this: @@ -72,15 +71,18 @@ catalogs and items: - `Item` -> `Item` (example: this relationship may be used to describe a 1-1 parent-child relationship, such as a single derived item from one parent item) -These relationships are all described by a common `links` object structure, making use of -the *rel* attribute to further describe the relationship. +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` attribute to further describe the relationship. There are a few types of catalogs that implementors occasionally refer to. These get defined by the `links` structure. - * A **sub-catalog** is a Catalog that is linked to from another Catalog that is used to better organize data. For example a Landsat dataset might have sub-catalogs for each Path and Row, so as to create a nice tree structure for users to follow. + * A **sub-catalog** is a Catalog that is linked to from another Catalog that is used to better organize data. For example a Landsat collection + might have sub-catalogs for each Path and Row, so as to create a nice tree structure for users to follow. * A **root catalog** is a Catalog that only links to sub-catalogs. These are typically entry points for browsing data. Often - they will contain the [dataset](../dataset-spec) definition, but in implementations that publish diverse information it may - contain sub-catalogs that provide a variety of datasets. + they will contain the [STAC Collection](../collection-spec) definition, but in implementations that publish diverse information it may + contain sub-catalogs that provide a variety of collections. * A **parent catalog** is the Catalog that sits directly above a sub-catalog. Following parent catalog links continuously will naturally end up at a root catalog definition. @@ -91,14 +93,13 @@ linked to across the web. ### Catalog Types -The core `Item`s and `Catalog`s of a SpatioTemporal Asset Catalog are designed for ease of implementation. +The core Items and Catalogs of a SpatioTemporal Asset Catalog are designed for ease of implementation. With the same core JSON documents and link structures it can be implemented in a way that is just files available online, or easily implementable with modern REST service infrastructures. These represent two different types of catalogs, the 'static catalog' and the 'dynamic catalog', which can operate a bit differently though they can be treated the same by clients. - - But any server can implement the same JSON and link structure, creating responses +But any server can implement the same JSON and link structure, creating responses dynamically as REST calls. These are referred to as 'dynamic catalogs'. #### Static Catalogs @@ -108,7 +109,7 @@ A main target for STAC has been object storage services like [Amazon S3](https:/ so that users can stand up a full STAC implementation with static files. Implementations created with just files online are referred to as 'static catalogs'. These include not just the cloud services, but any type of file server that is online. -Static Catalogs tend to make extensive use of *sub-catalogs* to organize their `Item`s in to sensible browsing structures, +Static Catalogs tend to make extensive use of *sub-catalogs* to organize their Items in to sensible browsing structures, as they can only have a single representation of their catalog, as the static nature means the structure is baked in. While it is up to the implementor to organize the catalog, it is recommended to arrange the in a way that would make sense for a human to browse a set of STAC Items in an intuitive matter. @@ -132,10 +133,11 @@ as linked STAC Items by implementing a dynamic catalog. One benefit of a dynamic catalog is that it can generate various 'views' of the catalog, exposing the same `Items` in different sub-catalog organization structures. For example one catalog could divide sub-catalogs by date and another by -providers, and users could browse down to both. The leaf `Item`s should just be linked to in a single canonical location (or at least use a *rel* link that indicates the location of the canonical one. +providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location +(or at least use a `rel` link that indicates the location of the canonical one. The STAC API is also made to be compatible with WFS3, which has a set structure for the canonical location of its features. -STAC `Item`s should use the WFS3 location as their canonical location, and then in the `/stac/` browse structure would just +STAC Items should use the WFS3 location as their canonical location, and then in the `/stac/` browse structure would just link to those locations. ## Catalog fields @@ -148,7 +150,7 @@ link to those locations. | description | string | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.28](http://commonmark.org/) syntax MAY be used for rich text representation. | | links | [Link Object] | **REQUIRED.** A list of references to other documents. | -**stac_version**: It is not allowed to mix STAC versions. The root catalog/dataset MUST specify the implemented STAC versions and child catalogs/datasets MUST NOT specify a different STAC version. +**stac_version**: It is not allowed to mix STAC versions. The root catalog or the root collection respectively MUST specify the implemented STAC version. Child Catalogs and child Collections MUST NOT specify a different STAC version. **Examples:** @@ -169,7 +171,7 @@ might look something like this: } ``` -In addition, the catalog shown above is strongly recommended to also follow the [Dataset specification](../dataset-spec/dataset-spec.md) +In addition, the catalog shown above is strongly recommended to also follow the [STAC Collection specification](../collection-spec/collection-spec.md) to add more information about the NAIP imagery such as the spatial and temporal extents, a license and more. A typical '_child_' sub-catalog could look similar: @@ -189,7 +191,7 @@ A typical '_child_' sub-catalog could look similar: } ``` -The `root` catalog in this example could hold a set of catalogs with different datasets, e.g. data from other satellites or processed variants of the NAIP imagery. +The `root` catalog in this example could hold a set of sub-catalogs with different STAC collections, e.g. data from other satellites or processed variants of the NAIP imagery. ### Link Object @@ -203,16 +205,25 @@ with links. | type | string | Media type of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | +Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for a discussion on that topic. + #### Relation types -The following types are commonly used as `rel` types in the Link Object of a Dataset: +The following types are commonly used as `rel` types in the Link Object of a STAC Collection: -| Type | Description | -| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Type | Description | +| ------- | ----------- | | self | **REQUIRED.** _Absolute_ URL to the catalog file itself. This is required, to represent the location that the file can be found online. 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 | **REQUIRED.** _Absolute_ URL to the root [STAC Catalog](../catalog-spec/), even if it's the root and points to itself. | -| parent | URL to the parent [STAC Catalog](../catalog-spec/). Non-root catalogs should include a link to their parent. | -| child | URL to a child [STAC Catalog](../catalog-spec/). | -| item | URL to a [STAC Item](../item-spec/). | +| root | **REQUIRED.** _Absolute_ URL to the root [STAC Catalog](../catalog-spec/), even if it's the root and points to itself. | +| parent | URL to the parent [STAC Catalog](../catalog-spec/). Non-root catalogs should include a link to their parent. | +| child | URL to a child [STAC Catalog](../catalog-spec/). | +| item | URL to a [STAC Item](../item-spec/). | **Note:** A link to at least one `item` or `child` catalog is _required_. + +## Extensions + +There are emerging best practices, which in time will evolve in to specification extensions for +particular domains or uses. + +The [extensions page](../extensions/) gives an overview about relevant extensions for STAC Catalogs. \ No newline at end of file diff --git a/collection-spec/README.md b/collection-spec/README.md new file mode 100644 index 000000000..f13458a44 --- /dev/null +++ b/collection-spec/README.md @@ -0,0 +1,65 @@ +# STAC Collections + +[STAC Items](../item-spec/README.md) are focused on search within a collection*. Another topic of +interest is the search of collections, instead of within a collection. The [STAC Collection specification](collection-spec.md) +is independent of STAC Items and +[STAC Catalogs](../catalog-spec/README.md). Items are required to provide a link back to their collection definition. Other parties +can also use this specification standalone, as a way to describe collections in a lightweight way. + +The STAC Collection specification is a set of JSON fields to describe a set of Items in a STAC Catalog, to help enable discovery. It builds on +the [Catalog Spec](../catalog-spec/README.md), using the flexible structure specified there to further define and explain logical +groups of Items. It shares the same fields and therefore every Collection is also a valid Catalog - the JSON structure extends +the core Catalog definition. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. + +*\* There is no standardized name for the concept we are describing here, a set of assets that are defined with the same +properties and share higher level metadata. Others called it: dataset series (ESA, ISO 19115), collection (CNES, NASA), dataset (JAXA), product (JAXA).* + +## In this directory + +**The Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*. It includes an overview and in depth explanation of the +structures and fields. + +**Examples:** For samples of how Collections can be implemented the *[examples/](examples/)* folder contains a sample collection. + +**Schemas:** The schemas to validate the STAC Collection definition are found in the +*[json-schema/](json-schema/)* folder. The primary one is *[collection.json](json-schema/collection.json)*. + +## In the API directory + +**Dynamic Catalog OpenAPI Definition:** The [api-spec](../api-spec) directory contains OpenAPI definitions of the WFS3 `/collections` and `/collections/{collectionId}` +endpoints in the file [WFS3core+STAC.yaml](../api-spec/WFS3core+STAC.yaml.yaml). These endpoints are the dynamic versions of a STAC and WFS3 Collection. See + +## Schema Validation + +Instruction on schema validation for STAC Items can be found in the [validation instructions](validation/README.md). + +## Collection Flexibility + +STAC Collections are defined for flexibility. They only require a handful of fields, and +implementors are free to add most any JSON field or object that they want via extensions. +Many fields originating from the [STAC Item spec](../item-spec/item-spec.md) can already be +reused using the [Commons extension](../extensions/commons/README.md). +This flexibility and extensibility is a design goal, so that it is quite easy to implement a +collection and be able to adapt it to most any data model. + +But it is expected that some more firm recommendations and even requirements will emerge, so that clients will be able to glean +more meaningful information. In the meantime implementors are encouraged to do what makes sense for +them, and to check out the [examples](examples/) and [other implementations](../implementations.md) for emerging best practices. + +## Collection Evolution + +The Collection specification is maturing, but it is still relatively early days. As real world +implementations innovate in different ways, we will update the core fields to handle. + +The goal of the Collection spec is not to reinvent the wheel by making yet another set of fields for metadata. The hope is to +align with the latest efforts of the Open Geospatial Consortium, particularly their work around WFS 3 and hopefully CSW 4. +Indeed the field names are chosen to fully align with WFS 3, so a WFS 3 `collections/{collectionId}` endpoint can return +a valid STAC Collection that is also a valid WFS Collection. + +Effort will also be made to align with Dublin Core and [DCAT](https://www.w3.org/TR/vocab-dcat/), though it is likely to +start using it as a microformat in STAC Browser HTML output to start. But future iterations could align with a JSON-LD DCAT +and/or [GeoDCAT](https://github.com/SEMICeu/GeoDCAT-AP) recommendation. + +The immediate goal is to just be a simple explanation of fields to describe a collection, and as the spec evolves it will look to +continually align with other efforts. Indeed it could make sense in the future to just 'use' another spec by subsetting it +and explaining it. But nothing was found that exactly matched the needs of STAC to keep things very approachable to developers. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md new file mode 100644 index 000000000..be8e81c92 --- /dev/null +++ b/collection-spec/collection-spec.md @@ -0,0 +1,113 @@ +# 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 +STAC Collections Specification extends the [STAC Catalog Spec](../catalog-spec/README.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. + +A STAC ollection can be represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. + +* [Example (Sentinel 2)](examples/sentinel2.json) +* [JSON Schema](json-schema/collection.json) - please see the [validation instructions](../validation/README.md) + +## WARNING + +**This is still an early version of the STAC spec, expect that there may be some changes before everything is finalized.** + +Implementations are encouraged, however, as good effort will be made to not change anything too drastically. Using the specification now will ensure that needed changes can be made before everything is locked in. So now is an ideal time to implement, as your feedback will be directly incorporated. + +## Collection fields + +| Element | Type | Description | +| ------------ | ----------------- | ------------------------------------------------------------ | +| stac_version | string | **REQUIRED.** The STAC version 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.28](http://commonmark.org/) syntax MAY be used for rich text representation. | +| keywords | [string] | List of keywords describing the collection. | +| version | string | Version of the collection. | +| license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) or `proprietary` if the license is not on the SPDX license list. Proprietary licensed data SHOULD add a link to the license text, see the `license` relation type. | +| provider | [Provider Object] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | +| extent | [Extent Object] | **REQUIRED.** Spatial and temporal extents. | +| links | [Link Object] | **REQUIRED.** A list of references to other documents. | + +**stac_version**: It is not allowed to mix STAC versions. The root catalog or the root collection respectively MUST specify the implemented STAC version. Child Catalogs and child Collections MUST NOT specify a different STAC version. + +### Extent Object + +The object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified. + +**Note:** The STAC Collection Specification tries to align with [WFS 3.0](https://github.com/opengeospatial/WFS_FES), but there are still issues to be solved. +The WFS specification is in draft state and may change, especially regarding [extents](https://github.com/opengeospatial/WFS_FES/issues/168) or +[open date ranges](https://github.com/opengeospatial/WFS_FES/issues/155) for temporal extents. Therefore, it is also likely that the following fields change over time. +Please also note that WFS Collections and STAC Collections originate from different specifications and despite the fact that we try to aling them as good as possible +be aware of their differences by reading both specifications. + +| Element | Type | Description | +| -------- | -------------- | ------------------------------------------------------------------- | +| spatial | [number] | **REQUIRED.** Potential *spatial extent* covered by the collection. | +| temporal | [string\|null] | **REQUIRED.** Potential *temporal extent* covered by the collection. A list of two timestamps, which MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Open date ranges are supported by setting either the start or the end time to `null`. Example for data from the beginning of 2019 until now: `["2009-01-01T00:00:00Z", null]`. | + +**temporal** - The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth): + +- Lower left corner, coordinate axis 1 (west) +- Lower left corner, coordinate axis 2 (north) +- Lower left corner, coordinate axis 3 (base, optional) +- Upper right corner, coordinate axis 1 (east) +- Upper right corner, coordinate axis 2 (south) +- Upper right corner, coordinate axis 3 (height, optional) + +The coordinate reference system of the values is WGS84 longitude/latitude. + +### Provider Object + +The object provides information about a provider. A provider is any of the organizations that captured or processed the content of the collection and therefore influenced the data offered by this collection. May also include information about the final storage provider hosting the data. + +| Field Name | Type | Description | +| ---------- | ------ | ------------------------------------------------------------ | +| name | string | **REQUIRED.** The name of the organization or the individual. | +| type | string | The type of provider. Any of `producer`, `processor` or `host`. | +| url | string | Homepage of the provider. | + +**type**: The type of the provider can be one of the following elements: + +* *producer*: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data. +* *processor*: A processor is any provider who processed data to a derived product. +* *host*: The host is the actual provider offering the data on their storage. There should be no more than one host, specified as last element of the list. + +### 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. | +| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | +| type | string | Media type of the referenced entity. | + +Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for a discussion on that topic. + +#### Relation types + +The following types are commonly used as `rel` types in the Link Object of a Collection: + +| Type | Description | +| ------- | ------------------------------------------------------------ | +| self | **REQUIRED.** *Absolute* URL to the collection. This is required, to represent the location that the file can be found online. 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](../catalog-spec/README.md) or Collection. | +| parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or Collection. | +| child | URL to a child STAC [Catalog](../catalog-spec/README.md) or Collection. | +| item | URL to a STAC [Item](../item-spec/README.md). All items linked from a collection MUST refer back to its collection with the `collection` relation type. | +| license | The license URL for the collection SHOULD be specified if the `license` field is set to `proprietary`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with 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#relation-types) for more info. | + +**Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) 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. + +## Extensions + +Important related extensions for the STAC Collection Specification: + +* [Commons extension](../extensions/commons/README.md), which primarily allows to add shared Item metadata to Collections, + but could also be used to describe Collections better that are not referring to Items by adding additional fields from Item extensions. + Please note that this extension is only in '[proposal](../extensions/README.md#extension-maturity)' stage. + +The [extensions page](../extensions/README.md) gives a full overview about relevant extensions for STAC Collections. diff --git a/dataset-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json similarity index 100% rename from dataset-spec/examples/sentinel2.json rename to collection-spec/examples/sentinel2.json diff --git a/dataset-spec/json-schema/dataset.json b/collection-spec/json-schema/collection.json similarity index 92% rename from dataset-spec/json-schema/dataset.json rename to collection-spec/json-schema/collection.json index e065cf85c..c2c2a36ae 100644 --- a/dataset-spec/json-schema/dataset.json +++ b/collection-spec/json-schema/collection.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-06/schema#", - "id": "dataset.json#", - "title": "Dataset Item", - "description": "This object represents the dataset in a SpatioTemporal Asset Catalog.", + "id": "collection.json#", + "title": "STAC Collection Specification", + "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", "type": "object", "required": [ "stac_version", @@ -38,11 +38,11 @@ } }, "version": { - "title": "Dataset Version", + "title": "Collection Version", "type": "string" }, "license": { - "title": "Dataset License Name", + "title": "Collection License Name", "type": "string" }, "provider": { diff --git a/dataset-spec/README.md b/dataset-spec/README.md deleted file mode 100644 index 2bdeedc92..000000000 --- a/dataset-spec/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# STAC Datasets - -[Items](https://github.com/radiantearth/stac-spec/item-spec/) are focused on search within a dataset*. Another topic of -interest is the search of datasets, instead of within a dataset. The Dataset Spec is independent of Items and -[Catalogs](../catalog-spec/). STAC Items are *strongly recommended* to provide a link to a dataset definition. Other parties -can also use this spec standalone, as a way to describe datasets in a lightweight way. Datasets are defined in full in the -Dataset Specification. - -The Dataset Spec is a set of JSON fields to describe a set of `Item`s in a `Catalog`, to help enable discovery. It builds on -the [Catalog Spec](../catalog-spec/), using the flexible structure specified there to further define and explain logical -groups of `Item`s. It shares the same fields and therefore every Dataset is also a valid Catalog - the JSON structure extends -the core Catalog definition. Datasets can have both parent Catalogs and Datasets and child Items, Catalogs and Datasets. - -*\* There is no standardized name for the concept we are describing here, a set of assets that are defined with the same -properties and share higher level metadata. Others called it: dataset series (ESA, ISO 19115), collection (CNES, NASA), dataset (JAXA), product (JAXA).* - -## In this directory - -**The Specification:** The main Dataset specification is in *[dataset-spec.md](dataset-spec.md)*. It includes an overview and in depth explanation of the -structures and fields. - -**Examples:** For samples of how Datasets can be implemented the *[examples/](examples/)* folder contains a sample dataset. - -**Schemas:** The schemas to validate the core `Dataset` definition are found in the -*[json-schema/](json-schema/)* folder. The primary one is *[dataset.json](json-schema/dataset.json)*. - - -## Schema Validation - -Instruction on schema validation for STAC Items can be found in the [validation instructions](validation/README.md). - -## Dataset Flexibility - -STAC Datasets are defined for flexibility. They only require a handful of fields, and -implementors are free to add most any JSON field or object that they want via extensions. This is a design goal, so -that it is quite easy to implement a dataset and be able to adapt it to most any data model. - -But it is expected that some more firm recommendations and even requirements will emerge, so that clients will be able to glean -more meaningful information. In the meantime implementors are encouraged to do what makes sense for -them, and to check out the [examples](examples/) and [other implementations](../implementations.md) for emerging best practices. - -## Dataset Evolution - -The Dataset specification is maturing, but it is still relatively early days. As real world -implementations innovate in different ways, we will update the core fields to handle. - -The goal of the Dataset spec is not to reinvent the wheel by making yet another set of fields for metadata. The hope is to -align with the latest efforts of the Open Geospatial Consortium, particularly their work around WFS 3 and hopefully CSW 4. -Indeed the field names are chosen to fully align with WFS 3, so a WFS 3 `collections/{collectionId}` endpoint can return -a valid STAC Dataset that is also valid for their response. - -Effort will also be made to align with Dublin Core and [DCAT](https://www.w3.org/TR/vocab-dcat/), though it is likely to -start using it as a microformat in STAC Browser HTML output to start. But future iterations could align with a JSON-LD DCAT -recommendation. - -The immediate goal is to just be a simple explanation of fields to describe a dataset, and as the spec evolves it will look to -continually align with other efforts. Indeed it could make sense in the future to just 'use' another spec by subsetting it -and explaining it. But nothing was found that exactly matched the needs of STAC to keep things very approachable to developers. diff --git a/dataset-spec/dataset-spec.md b/dataset-spec/dataset-spec.md deleted file mode 100644 index 3e4f29521..000000000 --- a/dataset-spec/dataset-spec.md +++ /dev/null @@ -1,110 +0,0 @@ -# STAC Dataset Specification - -The Dataset Spec defines a set of common fields to describe a group of `Item`s that share properties and metadata. The -Datasets Spec extends the [Catalog Spec](../catalog-spec/) with additional fields to describe the set of items in the catalog. -It shares the same fields and therefore every Dataset is also a valid Catalog. Datasets can have both parent Catalogs and Datasets and child Items, Catalogs and Datasets. - -A Dataset can be represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Dataset and Catalog. - -* [Example (Sentinel 2)](examples/sentinel2.json) -* [JSON Schema](json-schema/dataset.json) - please see the [validation instructions](../validation/README.md) - -## WARNING - -**This is still an early version of the STAC spec, expect that there may be some changes before everything is finalized.** - -Implementations are encouraged, however, as good effort will be made to not change anything too drastically. Using the specification now will ensure that needed changes can be made before everything is locked in. So now is an ideal time to implement, as your feedback will be directly incorporated. - -## Dataset fields - -| Element | Type | Description | -| ------------ | ----------------- | ------------------------------------------------------------ | -| stac_version | string | **REQUIRED.** The STAC version the dataset implements. | -| id | string | **REQUIRED.** Identifier for the dataset that is unique across the provider. | -| title | string | A short descriptive one-line title for the dataset. | -| description | string | **REQUIRED.** Detailed multi-line description to fully explain the entity. [CommonMark 0.28](http://commonmark.org/) syntax MAY be used for rich text representation. | -| keywords | [string] | List of keywords describing the dataset. | -| version | string | Version of the dataset. | -| license | string | **REQUIRED.** Dataset's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) or `proprietary` if the license is not on the SPDX license list. Proprietary licensed data SHOULD add a link to the license text, see the `license` relation type. | -| provider | [Provider Object] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | -| extent | [Extent Object] | **REQUIRED.** Spatial and temporal extents. | -| links | [Link Object] | **REQUIRED.** A list of references to other documents. | - -**stac_version**: It is not allowed to mix STAC versions. The root catalog/dataset MUST specify the implemented STAC versions and child catalogs/datasets MUST NOT specify a different STAC version. - -### Extent Object - -The object describes the spatio-temporal extents of the dataset. Both spatial and temporal extents are required to be specified. - -**Note:** STAC datasets tries to be compliant to [WFS 3.0](https://github.com/opengeospatial/WFS_FES), but there are still issues to be solved. The WFS specification is in draft state any may change, especially regarding [3D support](https://github.com/opengeospatial/WFS_FES/issues/143) for spatial extents or the handling of [open date ranges](https://github.com/opengeospatial/WFS_FES/issues/155) for temporal extents. Therefore, It is also likely that the following fields change over time. - -| Element | Type | Description | -| -------- | -------- | ------------------------------------------------------------ | -| spatial | [number] | **REQUIRED.** Potential *spatial extent* covered by the dataset. | -| temporal | [string\|null] | **REQUIRED.** Potential *temporal extent* covered by the dataset. A list of two timestamps, which MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Open date ranges are supported by setting either the start or the end time to `null`. Example for data from the beginning of 2019 until now: `["2009-01-01T00:00:00Z", null]`. | - -**temporal** - The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth): - -- Lower left corner, coordinate axis 1 (west) -- Lower left corner, coordinate axis 2 (north) -- Lower left corner, coordinate axis 3 (base, optional) -- Upper right corner, coordinate axis 1 (east) -- Upper right corner, coordinate axis 2 (south) -- Upper right corner, coordinate axis 3 (height, optional) - -The coordinate reference system of the values is WGS84 longitude/latitude. - -### Provider Object - -The object provides information about a provider. A provider is any of the organizations that captured or processed the content of the dataset and therefore influenced the data offered by this dataset. May also include information about the final storage provider hosting the data. - -| Field Name | Type | Description | -| ---------- | ------ | ------------------------------------------------------------ | -| name | string | **REQUIRED.** The name of the organization or the individual. | -| type | string | The type of provider. Any of `producer`, `processor` or `host`. | -| url | string | Homepage of the provider. | - -**type**: The type of the provider can be one of the following elements: - -* *producer*: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data. -* *processor*: A processor is any provider who processed data to a derived product. -* *host*: The host is the actual provider offering the data on their storage. There should be no more than one host, specified as last element of the list. - -### 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. | -| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | -| type | string | Media type of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | - -#### Relation types - -The following types are commonly used as `rel` types in the Link Object of a Dataset: - -| Type | Description | -| ------- | ------------------------------------------------------------ | -| self | **REQUIRED.** *Absolute* URL to the dataset file itself. This is required, to represent the location that the file can be found online. 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](../catalog-spec/) or Dataset. | -| parent | URL to the parent [STAC Catalog](../catalog-spec/) or Dataset. | -| child | URL to a child [STAC Catalog](../catalog-spec/) or Dataset. | -| item | URL to a [STAC Item](../item-spec/). All items linked from a dataset MUST refer back to its dataset with the `dataset` relation type. | -| license | The license URL for the dataset SHOULD be specified if the `license` field is set to `proprietary`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with the license text in a separate file and link to this file. | -| derived_from | URL to a STAC `Dataset` that was used as input data in the creation of this `Dataset`. See the note in [STAC Item](../item-spec/item-spec.md) for more info. | - -**Note:** The [catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is _not_ a requirement for datasets, but _recommended_. In contrast to catalogs, it is **required** that items linked from a dataset MUST refer back to its dataset with the `dataset` relation type. - -## Extensions - -Important related extensions for the dataset spec: - -* [EO extension](../extensions/stac-eo-spec.md) - Please note that some fields such as `eo:sun_elevation ` or `eo:sun_azimuth` are only meaningful on the item level and MUST not be used in datasets. -* Dimensions extension (proposed, see [PR #227](https://github.com/radiantearth/stac-spec/pull/227)) -* [Scientific extension](../extensions/scientific) -* Provenance extension (planned, see [issue #179](https://github.com/radiantearth/stac-spec/issues/179)) - -The [extensions page](../extensions/) gives a full overview about relevant extensions for STAC Datasets. diff --git a/extensions/README.md b/extensions/README.md index fd151abc8..d1e9daf0b 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -1,17 +1,16 @@ # Extensions -This folder contains extensions to the core SpatioTemporal Asset Catalog specification. The core -spec is designed for extension, defining just a minimal core. It is expected that most real world +This folder contains extensions to the SpatioTemporal Asset Catalog specification. The specification +is designed for extension, defining just a minimal core. It is expected that most real world implementations will use several extensions to fully describe their data and API. - Extensions can be changes in functionality or new fields. This can include new JSON files that are linked to from the core `links`, as well as new OpenAPI fragments. Extensions should include narrative explaining the fields, a comprehensive example and a JSON-Schema to validate compliance. Any data provider can create an extension, and when providers work together to share fields between them they can create a shared extension and include it in the STAC repository. -Anyone is welcome to create an extension, and is encouraged to at least link to the extension from +Anyone is welcome to create an extension (see section 'Extending STAC'), and is encouraged to at least link to the extension from here. The third-party / vendor extension section is for the sharing of extensions. As third parties create useful extensions for their implementation it is expected that others will make use of it, and then evolve to make it a 'community extension', that several providers maintain @@ -46,12 +45,11 @@ stable for over a year and are used in twenty or more implementations. | Extension Name (Prefix) | Scope | Description | Maturity | | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | -------- | -| [Commons](commons/) (-) | Item | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | -| [EO](stac-eo-spec.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | -| [Datetime Range](datetime-range/) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | -| [EO](eo/) (`eo`) | Item | Covers data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands in any part of the electromagnetic spectrum. Examples of EO data include sensors with visible bands, infrared bands (near and shortwave), red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | -| [Scientific](scientific/) (`sci`) | Catalog +Dataset | Scientific metadata is considered to be data that indicate from which publication a dataset originates and how the dataset itself should be cited or referenced. | *Proposal* | -| [Transaction](transaction/) | API | Provides an API extension to support the creation, editing, and deleting of items on a specific WFS3 collection. | *Pilot* | +| [Commons](commons/README.md) (-) | Item +Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | +| [Datetime Range](datetime-range//README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | +| [EO](eo//README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | +| [Scientific](scientific//README.md) (`sci`) | Item | Scientific metadata is considered to be data that indicate from which publication a collection originates and how the collection itself should be cited or referenced. | *Proposal* | +| [Transaction](transaction//README.md) | API | Provides an API extension to support the creation, editing, and deleting of items on a specific WFS3 collection. | *Pilot* | ## Third-party / vendor extensions @@ -59,7 +57,7 @@ The following extensions are provided by third parties (vendors). They tackle ve use-cases and may be less stable than the official extensions. Once stable and adopted by multiple parties, extensions may be made official and incorporated in the STAC repository. -Please contact a STAC maintainer to add your extension to this table. +Please contact a STAC maintainer or open a Pull Request to add your extension to this table. | Name | Scope | Description | Vendor | | -------- | ----- | ----------- | ------ | @@ -76,3 +74,52 @@ extension, please get in touch through the referenced issues: - [Full Motion Video Content Extension](https://github.com/radiantearth/stac-spec/issues/156) - [Point Cloud Extension](https://github.com/radiantearth/stac-spec/issues/157) - [Storage Extensions](https://github.com/radiantearth/stac-spec/issues/148) + +## Extending STAC + +Anyone is welcome to create an extension. There are several types of extensions, some just add additional fields, +some change the behaviour of STAC and some introduce completely new functionality. New extensions should try to align +with existing extensions as good as possible and may even re-use fields and their definitions until they may get split +into a new extension that combines commonly used fields across multiple extensions. +Best practices for extension proposals are still emerging in this section. + +### Prefixes + +A STAC Item can combine schema information from several different sources - the core STAC item information, +an earth observation community extension, and a vendor specific provider. It can be difficult to distinguish exactly where each definition +came from, and to pull out the most relevant information, especially when vendors often will dump in all the metadata they have in to the +STAC definition. + +So one idea is to have prefixes to differentiate specific vendors (like `dg:` for DigitalGlobe), and for communities of practice +(like `eo:` for Electro-Optical). These wouldn't be full namespacing, though an extension for like JSON-LD could potentially +evolve to make fully resolved namespacing an option. + +An example of this can be seen in a Landsat example: + +```json + "properties": { + "datetime":"2018-01-01T13:21:30Z", + + "dtr:start_datetime":"2018-01-01T13:21:30Z", + "dtr:end_datetime":"2018-01-01T13:31:30Z", + + "eo:off_nadir_angle": -0.001, + "eo:cloud_cover": 10.31, + "eo:sun_azimuth": 149.01607154, + "eo:sun_elevation": 59.21424700, + "eo:resolution": 30, + + "l8:data_type": "L1T", + "l8:wrs_path": 153, + "l8:wrs_row": 25, + "l8:earth_sun_distance": 1.0141560, + "l8:ground_control_points_verify": 114, + "l8:geometric_rmse_model": 7.562, + "l8:image_quality_tirs": 9, + "l8:ground_control_points_model": 313, + "l8:geometric_rmse_model_x": 5.96, + "l8:geometric_rmse_model_y": 4.654, + "l8:geometric_rmse_verify": 5.364, + "l8:image_quality_oli": 9 + }, +``` diff --git a/extensions/commons/README.md b/extensions/commons/README.md index a3c8ef83b..c2ca42563 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -1,8 +1,8 @@ -# Commons Extension Spec +# Commons Extension Specification **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../dataset-spec/) that the STAC Items belong to. +A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../collection-spec/README.md) that the STAC Items belong to. - Examples (missing, PRs welcome) - JSON Schema (missing, PRs welcome) @@ -91,7 +91,7 @@ An incomplete item: } ``` -The merged `Item` then looks like this: +The merged Item then looks like this: ```json { diff --git a/extensions/datetime-range/stac-datetime-range-spec.md b/extensions/datetime-range/README.md similarity index 88% rename from extensions/datetime-range/stac-datetime-range-spec.md rename to extensions/datetime-range/README.md index a6a924f9c..61b5b8fb0 100644 --- a/extensions/datetime-range/stac-datetime-range-spec.md +++ b/extensions/datetime-range/README.md @@ -1,6 +1,6 @@ -# STAC Datetime Range Extension Spec (`dtr`) +# Datetime Range Extension Specification (`dtr`) -**Extension [Maturity Classification](./README.md#extension-maturity): Proposal** +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. diff --git a/extensions/eo/README.md b/extensions/eo/README.md index 9fd78a1fc..f42138043 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -1,24 +1,24 @@ -# STAC EO Extension Spec (`eo`) +# EO Extension Specification (`eo`) **Extension [Maturity Classification](../README.md#extension-maturity): Pilot** -This document explains the fields of the STAC Electro-Optical (EO) Extension to a STAC `Item`. EO +This document explains the fields of the STAC Electro-Optical (EO) Extension to a STAC Item. EO data is considered to be data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands in any part of the electromagnetic spectrum. Examples of EO data include sensors with visible, short-wave and mid-wave IR bands (e.g., the OLI instrument on Landsat-8), long-wave IR bands (e.g. TIRS aboard Landsat-8). -*\* Note: This extension used to be called Earth Observation with a much broader scope (including +**Note:** This extension used to be called Earth Observation with a much broader scope (including Synthetic Aperture Radar (SAR), etc). The decision was made to limit this to what was already its natural focus, and encourage other sensors to make their own extensions. Once that happens some of these fields will evolve to higher level extensions. In the meantime other implementations are welcome -to reuse the names and definitions here.* +to reuse the names and definitions here. -It is not necessary, but recommended to use the [Commons extension](../commons) -(see chapter "Using collections"). +It is not necessary, but recommended to use the [Commons extension](../commons/README.md) +(see chapter "Placing common fields in Collections"). - [Example (Landsat 8)](example-landsat8.json) -- [JSON Schema](json-schema.json) +- [JSON Schema](schema.json) ## Item fields @@ -194,16 +194,15 @@ Planet example: ## Implementations -A number of implementations listed on [STAC Implementations page](../implementations.md) are making use of the core EO +A number of implementations listed on [STAC Implementations page](../../implementations.md) are making use of the core EO properties, including the SpaceNet, CBERS, sat-api and Planet implementations. This is not marked as more mature because the eo:bands portion is still being fleshed out, with changes coming in 0.6.0. ## Extensions -The [extensions page](../extensions/) gives an overview about related extensions. +The [extensions page](../README.md) gives an overview about related extensions. -### Using collections - A lot of EO data will have common metadata across many `Items`. It is not necessary, but recommended -to use the [Collections extension](stac-collection-spec.md). While the exact metadata that would -appear in a `Collection` record will vary depending on the dataset, the most common collection-level -metadata fields are indicated with an \* in the tables below. +### Placing common fields in Collections +A lot of EO data will have common metadata across many Items. It is not necessary, but recommended +to use the [Commons extension](../commons/README.md) in combination with [STAC Collections](../../collection-spec/README.md). +The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. \ No newline at end of file diff --git a/extensions/eo/json-schema.json b/extensions/eo/schema.json similarity index 100% rename from extensions/eo/json-schema.json rename to extensions/eo/schema.json diff --git a/extensions/examples/README.md b/extensions/examples/README.md deleted file mode 100644 index 03c1843e4..000000000 --- a/extensions/examples/README.md +++ /dev/null @@ -1,8 +0,0 @@ -## Landsat Example with EO and Collection extension - -The files in this directory contain a full example of Landsat data. It follows the EO -extension, and uses the 'Collection' extension to be less duplicative of information - -* [landsat8-sample](landsat8-sample.json) is a core `Item` including the link to its collection information. -* [L1T-collection](L1T-collection.json) shows the collection information for Landsat 8 L1T collection -* [landsat8-merged](landsat8-merged.json) is a fully expanded record, showing the result of merging of the collection data and the core `Item`. \ No newline at end of file diff --git a/extensions/scientific/README.md b/extensions/scientific/README.md index 775039430..7b471db5c 100644 --- a/extensions/scientific/README.md +++ b/extensions/scientific/README.md @@ -1,49 +1,55 @@ -# STAC Scientific Extension Spec (`sci`) +# Scientific Extension Specification (`sci`) **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -This document explains the fields of the STAC Scientific Extension to a STAC Catalog. Scientific -metadata is considered to be data that indicate from which publication a dataset originates and how -the dataset itself should be cited or referenced. Overall, it helps to increase reproducibility and -citability. +Scientific metadata is considered to be data that indicate from which publication a data originates and how +the data itself should be cited or referenced. Overall, it helps to increase reproducibility and citability. Human-readable references and [DOIs](https://www.doi.org/) can be used in this extension. DOIs are persistent digital interoperable identifier that uniquely identify for digital publications. They can be registered at registration agencies affiliated with the [International DOI Foundation](https://www.doi.org/). -- [Example](example-merraclim.json) +As these scientific information are often closely bound to the collection level and therefore are shared across all items, +it is recommended to use the [Commons extension](../commons/README.md) to add the fields to a corresponding +[STAC Collection](../../collection-spec/README.md). + +- [Example (Collection)](example-merraclim.json) - [JSON Schema](schema.json) -## Catalog Fields +## Item Fields -| Field Name | Type | Description | -| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| sci:doi | string | The DOI name of the dataset, e.g. `10.1000/xyz123`. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section of the catalog (see chapter "Relation types"). | -| sci:citation | string | The recommended human-readable reference (citation) to be used by publications citing this dataset. No specific citation style is suggested, but the citation should contain all information required to find the publication distinctively. | -| sci:publications | [Publication Object] | List of relevant publications referencing and describing this dataset. | +| Field Name | Type | Description | +| ---------------- | -------------------- | ----------- | +| sci:doi | string | The DOI name of the data, e.g. `10.1000/xyz123`. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section (see chapter "Relation types"). | +| sci:citation | string | The recommended human-readable reference (citation) to be used by publications citing the data. No specific citation style is suggested, but the citation should contain all information required to find the publication distinctively. | +| sci:publications | [Publication Object] | List of relevant publications referencing and describing the data. | ### Publication Object -| Field Name | Type | Description | -| ---------- | ------ | --------------------------------------------------- | -| doi | string | DOI of a publication referencing this dataset. | -| citation | string | Citation of a publication referencing this dataset. | +| Field Name | Type | Description | +| ---------- | ------ | ----------- | +| doi | string | DOI of a publication referencing the data. | +| citation | string | Citation of a publication referencing the data. | -**doi** - The DOI name of a publication which describes and references the dataset. The publications -should include more information about the dataset and how it was processed. This MUST NOT be a DOI -link. For all DOI names respective DOI links SHOULD be added to the links section of the catalog +**doi** - The DOI name of a publication which describes and references the data. The publications +should include more information about the data and how it was processed. This MUST NOT be a DOI +link. For all DOI names respective DOI links SHOULD be added to the links section (see chapter "Relation types"). **citation** - Human-readable reference (citation) of a publication which describes and references -the dataset. The publications should include more information about the dataset and how it was +the data. The publications should include more information about the data and how it was processed. No specific citation style is suggested, but a citation should contain all information required to find the publication distinctively. ## Relation types -This extension adds the following types as applicable `rel` types for the Link Object of a Catalog: +This extension adds the following types as applicable `rel` types for the Link Object: + +| Type | Description | +| ------- | ----------- | +| cite-as | For all DOI names specified the respective DOI links SHOULD be added to the links section with the `rel` type `cite-as` (see the [IETF draft](https://tools.ietf.org/id/draft-vandesompel-citeas-03.html)). | + +## Implementations -| Type | Description | -| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| cite-as | For all DOI names specified in a Catalog the respective DOI links SHOULD be added to the links section of the catalog with the `rel` type `cite-as` (see the [IETF draft](https://tools.ietf.org/id/draft-vandesompel-citeas-03.html)). | +None yet, still in proposal stage. \ No newline at end of file diff --git a/extensions/scientific/example-merraclim.json b/extensions/scientific/example-merraclim.json index d0ffebe36..0a499da4a 100644 --- a/extensions/scientific/example-merraclim.json +++ b/extensions/scientific/example-merraclim.json @@ -26,12 +26,14 @@ "href": "https://doi.org/10.1038/sdata.2017.78" } ], - "sci:doi": "10.5061/dryad.s2v81.2", - "sci:citation": "Vega GC, Pertierra LR, Olalla-Tárraga MÁ (2017) Data from: MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling. Dryad Digital Repository.", - "sci:publications": [ - { - "doi": "10.1038/sdata.2017.78", - "citation": "Vega GC, Pertierra LR, Olalla-Tárraga MÁ (2017) MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling. Scientific Data 4: 170078." - } - ] + "properties": { + "sci:doi": "10.5061/dryad.s2v81.2", + "sci:citation": "Vega GC, Pertierra LR, Olalla-Tárraga MÁ (2017) Data from: MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling. Dryad Digital Repository.", + "sci:publications": [ + { + "doi": "10.1038/sdata.2017.78", + "citation": "Vega GC, Pertierra LR, Olalla-Tárraga MÁ (2017) MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling. Scientific Data 4: 170078." + } + ] + } } \ No newline at end of file diff --git a/extensions/scientific/schema.json b/extensions/scientific/schema.json index 9e2235206..970264820 100644 --- a/extensions/scientific/schema.json +++ b/extensions/scientific/schema.json @@ -2,31 +2,36 @@ "$schema": "http://json-schema.org/draft-06/schema#", "id": "schema.json#", "type": "object", - "title": "STAC Scientific Profile Spec", + "title": "STAC Scientific Extension Spec", "properties": { - "sci:doi": { - "type": "string", - "title": "Dataset DOI", - "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" - }, - "sci:citation": { - "type": "string", - "title": "Proposed Dataset Citation" - }, - "sci:publications": { - "type": "array", - "title": "Publications", - "items": { - "type": "object", - "properties": { - "doi": { - "type": "string", - "title": "Publication DOI", - "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" - }, - "citation": { - "type": "string", - "title": "Publication Citation" + "properties": { + "type": "object", + "properties": { + "sci:doi": { + "type": "string", + "title": "Data DOI", + "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" + }, + "sci:citation": { + "type": "string", + "title": "Proposed Data Citation" + }, + "sci:publications": { + "type": "array", + "title": "Publications", + "items": { + "type": "object", + "properties": { + "doi": { + "type": "string", + "title": "Publication DOI", + "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" + }, + "citation": { + "type": "string", + "title": "Publication Citation" + } + } } } } diff --git a/extensions/stac-collection-spec.md b/extensions/stac-collection-spec.md deleted file mode 100644 index ce54ca350..000000000 --- a/extensions/stac-collection-spec.md +++ /dev/null @@ -1,241 +0,0 @@ -# STAC Collection Extension Spec (`c`) - -**Extension [Maturity Classification](./README.md#extension-maturity): Proposal** - -A group of STAC `Item` objects from a single source can share a lot of common metadata. This is -especially true with satellite imagery that uses the STAC EO Extension. Rather than including these -common metadata fields on every `Item`, they can be grouped into a `Collection`. - -- [Examples](examples/) -- JSON Schema (missing, [PRs welcome](https://github.com/radiantearth/stac-spec/issues/94)) - -## WARNING - -**This is still an early version of the STAC Collection Extension Spec, expect that there may be -some changes before everything is finalized.** - -Implementations are encouraged, however, as good effort will be made to not change anything too -drastically. Using the specification now will ensure that needed changes can be made before -everything is locked in. So now is an ideal time to implement, as your feedback will be directly -incorporated. - -## Item and Collection fields - -| Field name | Type | description | -| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -| c:id | string | **REQUIRED.** Machine readable ID for the collection. | -| c:name | string | A name given to the Collection, used for display. | -| c:description | string | A human readable description of the collection. [CommonMark 0.28](http://commonmark.org/) syntax MAY be used for rich text representation. | - -A `Collection` does not have many specific fields, as it may contain any fields that are in the core -spec as well as any other extension. This provides maximum flexibility to data providers, as some -the set of common metadata fields can vary between different types of data. For instance, Landsat -and Sentinel data always has a eo:off_nadir value of 0, because those satellites are always pointed -downward (i.e., nadir), while satellite that can be pointed will have varying eo:off_nadir values. - -Collections allow the data provider to define the common set of metadata themselves. Some metadata -fields are more likely to be part of the common set, such as 'license', or 'eo:instrument', however -depending on the data provider this could vary among `Item`s. - -All `Items` that use the collection extension to designate additional fields must include the `c:id` -field, which enables a user to search STAC records by the collection. The optional `c:name` and -`c:description` fields are used to display to human users. If no name is specified then the id will -be used for display. The other requirement to implement the collection extension is the -`c:collection` object in the links dictionary, as specified below. - -If a metadata field is specified in `Collection`, it will be ignored in any `Item` that links to -that `Collection`. This is important because a `Collection` is the metadta that is common across all -`Item` objects. If a field is variable at all, it should be part of the `Item` record. - -### Linking to a `Collection` - -An `Item` specifies the collection it belongs to in two places. One is a field called 'collection' -which is a key to a `Collection` record, which also also has a 'collection' field. This acts as a -way to provide a 2-way link between `Collection` and `Item` records through the 'collection' field. -In database terms, the 'collection' field is like a Foreign Key in the `Item` that links to a -`Collection`. - -An `Item` also provides a link to a collection under the links dictionary: - -``` -{ "collection": { "rel": "collection", href": "link/to/collection/record.json" } -``` - -### The Collection JSON - -The `Collection` JSON that a set of Items link to is a fragment of a full STAC Item, containing any -fields that are fixed for the set of Items that link to it. Most fields will live under the -`properties` object, and represent the fields that would be in each Item JSON. The Collection JSON -may contain other JSON objects, which should be thought of as objects that would live in each Item -and repeat. The `eo:bands` in the example below work this way. The `eo:bands` object lives parallel -to the `properties` object in the JSON. - -### Using a `Collection` - -The fields from the `Collection` record can be merged with an `Item` record to get the complete -metadata for the `Item`. - -``` -# a collection -{ - "properties": { - "c:name": "My Collection", - "c:id": "my_collection", - "c:description": "A description of my collection", - "provider": "me", - "license": "MIT" - } -} -# an item (incomplete) -{ - "id": "SCENE_001", - "properties": { - "c:id": "my_collection", - "datetime": "2017-01-01T00:00:00Z", - "geometry": {...} - }, - "links": [ - {"rel": "collection", "href": "link/to/my_collection" } - ... - ], - "assets": {...} -} -``` - -The merged `Item` then looks like this: - -``` -{ - "id": "SCENE_001", - "properties": { - "c:id": "my_collection", - "c:name": "My Collection", - "c:description": "A description of my collection", - "provider": "me", - "license": "MIT", - "datetime": "2017-01-01T00:00:00Z", - "geometry": {...} - }, - "links": [ - { - "rel": "collection", - "href": "link/to/my_collection" - }, - ... - ], - "assets": {...} -} -``` - -### `Collection` Example - -This is an example `Collection` for Landsat-8 imagery and uses the [EO extension](eo/). - -``` -{ - "properties": { - "c:name": "Landsat 8", - "c:id": "landsat-8", - "c:description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", - "provider": "LANDSAT_8", - "license": "PDDL-1.0", - "eo:gsd" : 30, - }, - - "eo:bands": [ - { - "name": "1", - "common_name": "coastal", - "gsd": 30.0, - "accuracy": null, - "wavelength": 0.44, - "full_width_half_max": 0.02 - }, - { - "name": "2", - "common_name": "blue", - "gsd": 30.0, - "accuracy": null, - "wavelength": 0.48, - "full_width_half_max": 0.06 - }, - { - "name": "3", - "common_name": "green", - "gsd": 30.0, - "accuracy": null, - "wavelength": 0.56, - "full_width_half_max": 0.06 - }, - { - "name": "4", - "common_name": "red", - "gsd": 30.0, - "accuracy": null, - "wavelength": 0.65, - "full_width_half_max": 0.04 - }, - { - "name": "5", - "common_name": "nir", - "gsd": 30.0, - "accuracy": null, - "wavelength": 0.86, - "full_width_half_max": 0.03 - }, - { - "name": "6", - "common_name": "swir16", - "gsd": 30.0, - "accuracy": null, - "wavelength": 1.6, - "full_width_half_max": 0.08 - }, - { - "name": "7", - "common_name": "swir22", - "gsd": 30.0, - "accuracy": null, - "wavelength": 2.2, - "full_width_half_max": 0.2 - }, - { - "name": "8", - "common_name": "pan", - "gsd": 15.0, - "accuracy": null, - "wavelength": 0.59, - "full_width_half_max": 0.18 - }, - { - "name": "9", - "common_name": "cirrus", - "gsd": 30.0, - "accuracy": null, - "wavelength": 1.37, - "full_width_half_max": 0.02 - }, - { - "name": "10", - "common_name": "lwir11", - "gsd": 100.0, - "accuracy": null, - "wavelength": 10.9, - "full_width_half_max": 0.8 - }, - { - "name": "11", - "common_name": "lwir12", - "gsd": 100.0, - "accuracy": null, - "wavelength": 12.0, - "full_width_half_max": 1.0 - } - ] -``` - -## Implementations - -[sat-api](https://github.com/sat-utils/sat-api/) has pioneered this functionality. You can see it in action at https://sat-api.developmentseed.org/search/stac - -Note this is in flux for 0.6.0, figuring out how 'dataset' fits in, as well as a general metadata model. \ No newline at end of file diff --git a/extensions/transaction/README.md b/extensions/transaction/README.md index c7e93a41b..05aa6e2e2 100644 --- a/extensions/transaction/README.md +++ b/extensions/transaction/README.md @@ -1,6 +1,6 @@ -# Transaction Extensions for WFS3 Core / STAC +# Transaction Extension Specification for WFS3 Core / STAC -**Extension [Maturity Classification](./README.md#extension-maturity): Proposal** +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** This folder contains an API extension to support the creation, editing, and deleting of items on a specific WFS3 collection. @@ -16,10 +16,10 @@ specific WFS3 collection. ## Items -As defined here, these methods operate on STAC items and item collections. However, apart from the -body schema defining the STAC item "payload", these API methods are completely generic and could be +As defined here, these methods operate on STAC Items and both STAC and WFS3 Collections. However, apart from the +body schema defining the STAC Item "payload", these API methods are completely generic and could be reused as an extension for WFS3 Core. ## Implementations -Both Boundless and Harris servers have sample implementations of this transaction extension. \ No newline at end of file +Both Boundless and Harris servers have sample [implementations](../../implementations.md) of this transaction extension. \ No newline at end of file diff --git a/extensions/transaction/WFS3core+STAC+extensions.yaml b/extensions/transaction/WFS3core+STAC+extensions.yaml index 90d73bc12..31aa7fb02 100644 --- a/extensions/transaction/WFS3core+STAC+extensions.yaml +++ b/extensions/transaction/WFS3core+STAC+extensions.yaml @@ -772,15 +772,15 @@ components: additionalProperties: description: Any additional properties added in via extensions. itemCollectionLinks: - type: object - properties: - next: - type: string - format: url - description: >- - A URL to obtain the next paginated data set. If not present, the - client should utilize the `nextPageToken`. - example: >- + type: array + description: >- + An array of links. Can be used for pagination, e.g. by providing a link + with the `next` relation type. + items: + $ref: '#/components/schemas/link' + example: + - rel: next + href: >- http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk root: type: object @@ -917,11 +917,11 @@ components: - properties - constructions version: - title: Dataset Version + title: Collection Version type: string example: 1 license: - title: Dataset License Name + title: Collection License Name type: string example: Apache-2.0 provider: diff --git a/how-to-help.md b/how-to-help.md index 804171cfd..8df533ff4 100644 --- a/how-to-help.md +++ b/how-to-help.md @@ -11,8 +11,8 @@ few best practices to evolve and [improvements](roadmap.md) to the spec that wil ## Implementations and Feedback -The best way to help out with STAC is to try to implement the specification, either a [static catalog](catalog-spec/), a -[catalog api](api-spec) or even both. This can be done by extending existing catalog software, creating new software, or +The best way to help out with STAC is to try to implement the specification, either a [static catalog](catalog-spec/README.md), a +[catalog api](api-spec/README.md) or even both. This can be done by extending existing catalog software, creating new software, or standing up a service end point that exposes data. Implementations using the specification as it stands will likely have to make a number of decisions while building, as there is a lot that is left unspecified. The best thing to do is to document those decisions, and share them with the core STAC group. Ideally make mini-specifications, but even just diff --git a/item-spec/README.md b/item-spec/README.md index 92ae068a6..c9d41b94c 100644 --- a/item-spec/README.md +++ b/item-spec/README.md @@ -1,9 +1,9 @@ # STAC Items The core of a SpatioTemporal Asset Catalog (STAC) is a set of JSON fields defined by the -[STAC Item spec](item-spec.md). These fields define an `Item` - the atomic units that contain +[STAC Item spec](item-spec.md). These fields define an Item - the atomic units that contain metadata for search as plus links to the actual assets that they represent. Their main function -is as the leaf nodes of a [Catalog](../catalog-spec/), and are also returned from the search +is as the leaf nodes of a [Catalog](../catalog-spec/README.md), and are also returned from the search endpoints of a `/stac/search` endpoint. ## In this directory @@ -16,7 +16,7 @@ endpoints of a `/stac/search` endpoint. contains a number of real world examples. See the [readme](examples/README.md) for additional discussion of the examples. -**Schemas:** The schemas to validate the core `Item` definition are found in the +**Schemas:** The schemas to validate the core Item definition are found in the *[json-schema/](json-schema/)* folder. The primary one is *[stac-item.json](json-schema/stac-item.json)*, and it also includes the necessary *[geojson.json](json-schema/geojson.json)* schema definition, which is a dependency. @@ -40,7 +40,7 @@ This will enable a spreading of best practices, as organizations can see how oth similar concepts and adopt them. These should eventually evolve in to extensions that are widely used. -There is already some first iterations of shared fields in the [extensions/](../extensions/) +There is already some first iterations of shared fields in the [extensions/](../extensions/README.md) folder, which is used mostly to represent additional domain-specific information. The core STAC fields were made to be flexible to a variety of assets. But there is a lot of value in shared fields that may not apply to every STAC data type, but are shared by a certain domain. There is a diff --git a/item-spec/examples/CBERS_4_MUX_20170528_090_084_L2.json b/item-spec/examples/CBERS_4_MUX_20170528_090_084_L2.json index e112aca5a..8c842c80a 100644 --- a/item-spec/examples/CBERS_4_MUX_20170528_090_084_L2.json +++ b/item-spec/examples/CBERS_4_MUX_20170528_090_084_L2.json @@ -56,7 +56,7 @@ "href": "https://cbers-stac.s3.amazonaws.com/CBERS4/MUX/090/catalog.json" }, { - "rel": "dataset", + "rel": "collection", "href": "https://cbers-stac.s3.amazonaws.com/collections/CBERS_4_MUX_L2_collection.json" } ], @@ -64,48 +64,36 @@ "thumbnail": { "href": "https://s3.amazonaws.com/cbers-meta-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084.jpg", "required": true, - "type": "jpeg" + "type": "image/jpeg" }, "metadata": { "href": "s3://cbers-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084_L2_BAND6.xml", "required": true, - "type": "xml" + "type": "application/xml" }, "B5": { "href": "s3://cbers-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084_L2_BAND5.tif", - "type": "GeoTIFF", - "format": "COG", + "type": "image/x.cloud-optimized-geotiff", "required": true, - "eo:bands": [ - "5" - ] + "eo:bands": [5] }, "B6": { "href": "s3://cbers-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084_L2_BAND6.tif", - "type": "GeoTIFF", - "format": "COG", + "type": "image/x.cloud-optimized-geotiff", "required": true, - "eo:bands": [ - "6" - ] + "eo:bands": [6] }, "B7": { "href": "s3://cbers-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084_L2_BAND7.tif", - "type": "GeoTIFF", - "format": "COG", + "type": "image/x.cloud-optimized-geotiff", "required": true, - "eo:bands": [ - "7" - ] + "eo:bands": [7] }, "B8": { "href": "s3://cbers-pds/CBERS4/MUX/090/084/CBERS_4_MUX_20170528_090_084_L2/CBERS_4_MUX_20170528_090_084_L2_BAND8.tif", - "type": "GeoTIFF", - "format": "COG", + "type": "image/x.cloud-optimized-geotiff", "required": true, - "eo:bands": [ - "8" - ] + "eo:bands": [8] } } } \ No newline at end of file diff --git a/item-spec/examples/README.md b/item-spec/examples/README.md index 8fea60e02..bfc6ac396 100644 --- a/item-spec/examples/README.md +++ b/item-spec/examples/README.md @@ -1,8 +1,8 @@ -# STAC JSON Examples +# STAC Item Examples ## Overview -This directory contains a number of samples and more 'real world' examples of how a STAC `Item` could be implemented. As of right +This directory contains a number of samples and more 'real world' examples of how a STAC Item could be implemented. As of right now none of these are actual production implementations - they are more adaptations of current catalogs to the STAC specifications. In time these will evolve to be examples of truly real world implementations. @@ -10,7 +10,7 @@ This document also contains discussion of the various examples in this folder. ## In this directory -**[sample.json](examples/sample.json)** is the most minimal possible compliant `Item` record. Most all data will +**[sample.json](examples/sample.json)** is the most minimal possible compliant Item record. Most all data will include additional fields, as STAC is designed to be a minimal common subset. But it is useful for showing exactly what is required. @@ -34,7 +34,7 @@ returned JSON, with minor tweaks to have it fit in to a STAC Item. ## Example Discussion -These examples demonstrate that there is a range of potential implementations of STAC `Item`s. Most were made by adapting +These examples demonstrate that there is a range of potential implementations of STAC Items. Most were made by adapting the current implementations as minimally as possible. The hope is that there will emerge more consensus and best practices on the things outside of the core fields, to increase interoperability. diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 2cf7754ed..b85607a06 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -88,7 +88,7 @@ "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_LV1B/103001004B316600_P002_MUL" }, { - "rel": "dataset", + "rel": "collection", "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_LV1B.json" } ] diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index 138ed525d..8e636a0f4 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -58,15 +58,15 @@ "links": [ { "rel":"self", "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00.json"}, - { "rel":"alternate", "href": "https://landsatonaws.com/L8/153/025/LC81530252014153LGN00", "type": "html"}, - { "rel":"dataset", "href": "http://landsat-pds.s3.amazonaws.com/L8/L1T-collection.json"} + { "rel":"alternate", "href": "https://landsatonaws.com/L8/153/025/LC81530252014153LGN00", "type": "text/html"}, + { "rel":"root", "href": "http://landsat-pds.s3.amazonaws.com/L8/L1T-collection.json"} ], "assets" :{ "thumbnail": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_thumb_large.jpg", "required": true, - "type": "jpeg" + "type": "image/jpeg" }, "metadata": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_MTL.txt", @@ -75,67 +75,67 @@ }, "B1": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B1.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [0] }, "B2": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B2.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [1] }, "B3": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B3.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [2] }, "B4": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B4.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [3] }, "B5": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B5.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [4] }, "B6": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B6.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [5] }, "B7": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B7.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [6] }, "B8": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B8.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [7] }, "B9": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B9.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [8] }, "B10": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B10.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [9] }, "B11": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B11.TIF", - "type": "GeoTIFF", + "type": "image/x.geotiff", "required": true, "eo:bands": [10] } diff --git a/item-spec/examples/planet-sample.json b/item-spec/examples/planet-sample.json index 9c39bf994..70a3d5c9c 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -91,7 +91,7 @@ "href": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTcxMTEwXzEyMTAxMF8xMDEzIiwgImMiOiAiUFNTY2VuZTRCYW5kIiwgInQiOiAiYW5hbHl0aWMiLCAiY3QiOiAiaXRlbS10eXBlIn0", "title": "PSScene4Band GeoTIFF (COG)", "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTcxMTEwXzEtMTAzMF8xMDEzIiwgImMiOiAiUFNTY2VuZTRCYW5kIiwgInQiOiAiYW5hbHl0aWMiLCAiY3QiOiAiaXRlbS10eXBlIn0/activate", - "type": "https://api.planet.com/data/v1/asset-types/analytic", + "asset_type": "https://api.planet.com/data/v1/asset-types/analytic", "_permissions": [ "download" ], @@ -102,7 +102,7 @@ "href": "https://api.planet.com/data/v1/assets/NTY2VuZTReyJpIjogIjIwMTcxMTEwXzEyMTAxMF8xMDEzIiQiOiAiaXRlbS10ewgImMiOiAiUFbHl0aWMiLCAiY3XBlIn0", "title": "PSScene4Band XML Metadata", "activate": "https://api.planet.com/data/v1/assets/tMTAzMF8xMDEzIiwInQiOiAeyJpIjogIjIwMTcxMTEwXzEiYW5hbHl0aWMiLCAiY3gImMiOiAiUFNTY2VuZTRCYW5kIiwgQiOiAiaXRlbS10eXBlIn0/activate", - "type": "https://api.planet.com/data/v1/asset-types/analytic_xml", + "asset_type": "https://api.planet.com/data/v1/asset-types/analytic_xml", "_permissions": [ "download" ], @@ -113,7 +113,7 @@ "href": "https://api.planet.com/data/v1/assets/NTY2VuZTReyJpIzEyMTAxMF8xMDEzIiQiOiAiaXRlbTcxMTEwXAiUFbHl0S10ewgImMiOijogIjIwMaWMiLCAiY3XBlIn0", "title": "PSScene4Band Unusable Data Mask", "activate": "https://api.planet.com/data/v1/assets/tMTAzMF8xMDEzIiwInQiOiAeyJpIjogIjIgImMiOiAiUFwMTcxMTEwXzEiYW5hbHl0aWMiLCAiY3NTY2VuZTRCYW5kIiwgQiOiAiaXRlbS10eXBlIn0/activate", - "type": "https://api.planet.com/data/v1/asset-types/udm", + "asset_type": "https://api.planet.com/data/v1/asset-types/udm", "_permissions": [ "download" ], diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json index 074505428..5d19273f6 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -1,20 +1,18 @@ { "type": "Feature", "id" : "CS3-20160503_132131_05", - "bbox": [ -122.59750209, 37.48803556, - -122.2880486, 37.613537207 - ], + "bbox": [-122.59750209, 37.48803556, -122.2880486, 37.613537207], "geometry": { "type": "Polygon", "coordinates": [ - [ - [-122.308150179, 37.488035566], - [-122.597502109, 37.538869539], - [-122.576687533, 37.613537207], - [-122.288048600, 37.562818007], - [-122.308150179, 37.488035566] - ] - ] + [ + [-122.308150179, 37.488035566], + [-122.597502109, 37.538869539], + [-122.576687533, 37.613537207], + [-122.288048600, 37.562818007], + [-122.308150179, 37.488035566] + ] + ] }, "properties": { "datetime": "2016-05-03T13:22:30.040Z", @@ -33,7 +31,9 @@ "links": [ {"rel": "self", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json"}, {"rel": "thumbnail", "href":"thumbnail.png"}, - {"rel": "dataset", "href": "http://cool-sat.com/catalog/"}, + {"rel": "root", "href": "http://cool-sat.com/catalog/catalog.json"}, + {"rel": "parent", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/catalog.json"}, + {"rel": "collection", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/catalog.json"}, {"rel": "acquisition", "href": "http://cool-sat.com/catalog/acquisitions/20160503_56"} ], "assets": { diff --git a/item-spec/examples/sample.json b/item-spec/examples/sample.json index b1d4d3cbd..c4451540f 100644 --- a/item-spec/examples/sample.json +++ b/item-spec/examples/sample.json @@ -1,36 +1,40 @@ { "type": "Feature", - "id" : "CS3-20160503_132130_04", - "bbox": [ -122.59750209, 37.48803556, - -122.2880486, 37.613537207 - ], + "id": "CS3-20160503_132130_04", + "bbox": [-122.59750209, 37.48803556, -122.2880486, 37.613537207], "geometry": { "type": "Polygon", "coordinates": [ - [ - [-122.308150179, 37.488035566], - [-122.597502109, 37.538869539], - [-122.576687533, 37.613537207], - [-122.288048600, 37.562818007], - [-122.308150179, 37.488035566] - ] - ] + [ + [-122.308150179, 37.488035566], + [-122.597502109, 37.538869539], + [-122.576687533, 37.613537207], + [-122.288048600, 37.562818007], + [-122.308150179, 37.488035566] + ] + ] }, "properties": { "datetime": "2016-05-03T13:21:30.040Z" }, "links": [ - { "rel": "self", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json"}, - { "rel": "dataset", "href": "http://cool-sat.com/catalog.json"} + { + "rel": "self", + "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json" + }, + { + "rel": "collection", + "href": "http://cool-sat.com/catalog.json" + } ], "assets": { "analytic": { - "href": "relative-path/to/analytic.tif", - "title": "4-Band Analytic" + "href": "relative-path/to/analytic.tif", + "title": "4-Band Analytic" }, "thumbnail": { - "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", - "title": "Thumbnail" + "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", + "title": "Thumbnail" } } -} +} \ No newline at end of file diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index ea7960792..edfdbf772 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -7,7 +7,11 @@ "href": "s3://sentinel-s2-l2a-catalog/tiles/35/V/MK/2018/6/5/0/sentinel2-sample.json" }, { - "rel": "dataset", + "rel": "root", + "href": "s3://sentinel-s2-l2a-catalog/catalog.json" + }, + { + "rel": "collection", "href": "s3://sentinel-s2-l2a-catalog/catalog.json" } ], @@ -50,251 +54,247 @@ "metadata": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/metadata.xml", "title": "Tile metadata", - "format": "xml" + "type": "application/xml" }, "tileInfo": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/tileInfo.json", "title": "Tile info", - "format": "json" + "type": "application/json" }, "productInfo": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/productInfo.json", "title": "Product info", - "format": "json" + "type": "application/json" }, "thumbnail": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/L2A_PVI.jp2", "title": "True color thumbnail", - "format": "jp2" + "type": "image/jp2" }, "B02_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/B02.jp2", "title": "Band 2 - Blue 0.490 (10m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [1] }, "B03_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/B03.jp2", "title": "Band 3 - Green 0.560 (10m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [2] }, "B04_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/B04.jp2", "title": "Band 4 - Red 0.665 (10m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [3] }, "B08_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/B08.jp2", "title": "Band 8 – NIR 0.842 (10m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [7] }, "AOT_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/AOT.jp2", "title": "Aerosol Optical Thickness (10m)", - "format": "jp2" + "type": "image/jp2" }, "TCI_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/TCI.jp2", "title": "True Color Image (10m)", - "format": "jp2" + "type": "image/jp2" }, "WVP_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/WVP.jp2", "title": "Water Vapor (10m)", - "format": "jp2" + "type": "image/jp2" }, "B02_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B02.jp2", "title": "Band 2 - Blue 0.490 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [1] }, "B03_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B03.jp2", "title": "Band 3 - Green 0.560 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [2] }, "B04_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B04.jp2", "title": "Band 4 - Red 0.665 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [3] }, "B05_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B05.jp2", "title" : "Band 5 - Vegetation Red Edge 0.705 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [4] }, "B06_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B06.jp2", "title": "Band 6 – Vegetation Red Edge 0.740 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [5] }, "B07_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B07.jp2", "title": "Band 7 – Vegetation Red Edge 0.783 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [6] }, "B8A_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B8A.jp2", "title": "Band 8A – Narrow NIR 0.865 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [8] }, "B11_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B11.jp2", "title": "Band 11 – SWIR 1.610 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [11] }, "B12_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/B12.jp2", "title": "Band 12 – SWIR 2.190 (20m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [12] }, "AOT_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/AOT.jp2", "title": "Aerosol Optical Thickness (20m)", - "format": "jp2" + "type": "image/jp2" }, "SCL_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/SCL.jp2", "title": "Scene Classification (20m)", - "format": "jp2" + "type": "image/jp2" }, "TCI_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/TCI.jp2", "title": "True Color Image (20m)", - "format": "jp2" + "type": "image/jp2" }, "WVP_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R20m/WVP.jp2", "title": "Water Vapor (20m)", - "format": "jp2" + "type": "image/jp2" }, "CLD_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/CLD_20m.jp2", "title": "Cloud (20m)", - "format": "jp2" + "type": "image/jp2" }, "SNW_20m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/SNW_20m.jp2", "title": "Snow (20m)", - "format": "jp2" + "type": "image/jp2" }, "B01_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B01.jp2", "title": "Band 1 - Coastal aerosol (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [0] }, "B02_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B02.jp2", "title": "Band 2 - Blue 0.490 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [1] }, "B03_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B03.jp2", "title": "Band 3 - Green 0.560 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [2] }, "B04_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B04.jp2", "title": "Band 4 - Red 0.665 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [3] }, "B05_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B05.jp2", "title" : "Band 5 - Vegetation Red Edge 0.705 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [4] }, "B06_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B06.jp2", "title": "Band 6 – Vegetation Red Edge 0.740 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [5] }, "B07_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B07.jp2", "title": "Band 7 – Vegetation Red Edge 0.783 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [6] }, "B8A_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B8A.jp2", "title": "Band 8A – Narrow NIR 0.865 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [8] }, "B09_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B09.jp2", "title": "Band 9 – Water vapour 0.945 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [9] }, "B11_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B11.jp2", "title": "Band 11 – SWIR 1.610 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [11] }, "B12_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/B12.jp2", "title": "Band 12 – SWIR 2.190 (60m)", - "format": "jp2", + "type": "image/jp2", "eo:bands": [12] }, "AOT_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/AOT.jp2", "title": "Aerosol Optical Thickness (60m)", - "format": "jp2" + "type": "image/jp2" }, "SCL_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/SCL.jp2", "title": "Scene Classification (60m)", - "format": "jp2" + "type": "image/jp2" }, "TCI_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/TCI.jp2", "title": "True Color Image (60m)", - "format": "jp2" + "type": "image/jp2" }, "WVP_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/WVP.jp2", "title": "Water Vapor (60m)", - "format": "jp2" + "type": "image/jp2" }, "CLD_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/CLD_60m.jp2", "title": "Cloud (60m)", - "format": "jp2" + "type": "image/jp2" }, "SNW_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/SNW_60m.jp2", "title": "Snow (60m)", - "format": "jp2" + "type": "image/jp2" } }, "properties": { "datetime": "2018-06-05T10:00:27.464Z", - "provider": "ESA", - "c:id": "L2A", - "c:name": "Sentinel-2 L2A", - "c:description": "Sentinel-2 L2A orthorectified Bottom-Of-Atmosphere (BOA) reflectance, with sub-pixel multispectral registration.", "eo:platform": "sentinel-2", - "eo:epsg": "EPSG:32635", + "eo:epsg": 32635, "eo:cloud_cover": 88.459539, "eo:sun_azimuth" : 176.091667178268 } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 0d536b71e..17debc62d 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -6,8 +6,8 @@ a few required fields that identify the time range and assets of the item. An It granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial 'assets' - satellite imagery, derived data, DEM's, etc. -The same Item definition is used in both '[catalogs](../catalog-spec/)' and -the '[/stac/search](../api-spec/)' endpoint. Catalogs are simply sets of items that are linked online, +The same Item definition is used in both '[catalogs](../catalog-spec/README.md)' and +the '[/stac/search](../api-spec/README.md)' endpoint. Catalogs are simply sets of items that are linked online, generally served by simple web servers and used for crawling data. The search endpoint enables dynamic queries, for example selecting all Items in Hawaii on June 3, 2015, but the results they return are FeatureCollections of items. @@ -77,7 +77,7 @@ datetime fields. This object describes a relationship with another entity. Data providers are advised to be liberal with the links section, to describe things like the catalog an item is in, related items, parent or child items (modeled in different ways, like an 'acquisition' or derived data). The `self` link is -required as an absolute URL, to represent the location that the `Item` can be found online. It is +required as an absolute URL, to represent the location that the Item can be found online. It is allowed to add additional fields such as a `title` and `type`. | Field Name | Type | Description | @@ -91,13 +91,13 @@ allowed to add additional fields such as a `title` and `type`. The following types are commonly used as `rel` types in the Link Object of an Item: -| Type | Description | -| ------- | ------------------------------------------------------------ | -| self | **REQUIRED.** _Absolute_ URL to the item file itself. This is required, to represent the location that the file can be found online. 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](../catalog-spec/) or [Dataset](../dataset-spec/). | -| parent | URL to the parent [STAC Catalog](../catalog-spec/) or [Dataset](../dataset-spec/). | -| dataset | **REQUIRED.** URL to a [STAC Dataset](../dataset-spec/). | -| derived_from | URL to a STAC `Item` that was used as input data in the creation of this `Item` | +| Type | Description | +| ------------ | ------------------------------------------------------------ | +| self | **REQUIRED.** _Absolute_ URL to the item file itself. This is required, to represent the location that the file can be found online. 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](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | +| parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | +| collection | STRONGLY RECOMMENDED. URL to a [Collection](../collection-spec/README.md), which may use the [Commons extension](../extensions/commons/README.md) and holds common fields of this and other Items (see chapter '[Collections](#Collections)' for more explanations). | +| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | *Note regarding the type `derived_from`: A full provenance model is far beyond the scope of STAC, and the goal is to align with any good independent spec that comes along for that. But the derived_from field is seen as a way to encourage fuller specs and at least start a linking @@ -111,12 +111,12 @@ whenever possible. But Static Catalogs are potentially more portable if they can relative links, so that every link doesn't need to be rewritten when the data is copied. The `self` link is required to be absolute. -#### Datasets +#### Collections -Items are *strongly recommended* to provide a link to a dataset definition. It is important as datasets -provide additional information about a set of items, for example the license and provider information -and optionally any common information shared across all items, giving context on the overall set of -data that an individual Item is a part of.. +Items are *strongly recommended* to provide a link to a STAC Collection definition. It is important as Collections +provide additional information about a set of items, for example the license, provider and other information (see section 'Extensions') +giving context on the overall set of data that an individual Item is a part of. If Items are part of a STAC Collection, +the [STAC Collection spec *requires* Items to link back to the Collection](collection-spec/collection-spec.md#relation-types). ### Asset Object @@ -134,8 +134,8 @@ or streamed. It is allowed to add additional fields. The following types are commonly for assets and are used as key for the Asset Object: -| Type | Description | -| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Type | Description | +| --------- | ----------- | | thumbnail | STRONGLY RECOMMENDED. A downsampled image of the core asset, for direct display online in a web page or interactive search application. Even assets that are less easily translated in to a visual image should provide some visual representation, that users can browse. For example a SAR asset can render an elevation mask or hillshade for display. If at all possible it should be included for a better user experience in searching data. | #### Media Types @@ -160,7 +160,7 @@ Common STAC Item Media Types: | `image/jp2` | JPEG 2000 | | `image/png` | Visual PNGs (e.g. thumbnails) | | `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | -| `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | +| `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | | `application/json` | JSON metadata | | `text/plain` | Plain text metadata | | `application/geo+json` | GeoJSON | @@ -176,4 +176,18 @@ media type. There are emerging best practices, which in time will evolve in to specification extensions for particular domains or uses. -The [extensions page](../extensions/) gives an overview about relevant extensions for STAC Items. +Optionally, common information shared across items can be split up into STAC Collections using the +[Commons extension](../extensions/commons/README.md). Please note that this extension is only in +'[proposal](../extensions/README.md#extension-maturity)' stage. + +The [extensions page](../extensions/README.md) gives an overview about relevant extensions for STAC Items. + +## Recommendations + +### Metadata Linking + +In general STAC aims to be oriented around **search**, centered on the core fields that users will want to search on to find imagery. +The core is space and time, but there are often other metadata attributes that are useful. While the specification is flexible enough that +providers can fill it with tens or even hundreds of fields of metadata that is not recommended. If providers have lots of metadata then +that should be linked to in the Asset Object or in a Link Object, or even a new Asset Object could be added that is potentially easier to parse. +There is a lot of metadata that is only of relevance to advanced processing algorithms, and while that is important it should not be in the core STAC items. \ No newline at end of file diff --git a/principles.md b/principles.md index 240341676..875180646 100644 --- a/principles.md +++ b/principles.md @@ -6,11 +6,11 @@ This project will be governed by a set of informal core principles. These princi * **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible, defining one core concept and refraining from describing lots of options. Additional options can be made as separate specifications that build on the core. But the core specs should be small and easily understandble, with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces. Implementors should not be forced to implement lots of options just for basic compliance - they should be able to pick and choose which pieces are relevant to the problems they are trying to solve. -* **Specify in OpenAPI 3.0 (formerly known as Swagger) specification.** All web interfaces should be specified in [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md). This enables generation of live documentation, client libraries and test engines, and makes the spec less ambiguous. Accompanying human readable specifications should be available in github and auto-built in to html (likely using [asciidoc](http://asciidoc.org/) as it handles specifications (headings, reorganization, etc) better than markdown). +* **Specify in OpenAPI 3.0 (formerly known as Swagger) specification.** All web interfaces should be specified in [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md). This enables generation of live documentation, client libraries and test engines, and makes the spec less ambiguous. Accompanying human readable specifications should be available in github and auto-built in to html. * **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice should be considered with a developer audience. And specifications should be accessible to developers who do not have geospatial background. A developer should not need to understand 'projections' to implement a simple feature access service. But we should think through the spec extensions they could use in the future when their client asks for data in a different projection. -* **Working code required.** Proposed changes should be accompanied by working code (ideally with a link to an online service running the code). A reference implementation should be available online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations that cover the entire specification. +* **Working code required.** Proposed changes should be accompanied by working code (ideally with a link to an online service running the code). A reference implementation should be available online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations that cover the entire specification. Extensions have their own [Extention Maturity](https://github.com/radiantearth/stac-spec/blob/dev/extensions/README.md#extension-maturity) model. * **Design for scale.** The design should work great with more data than can be imagined right now. Ideally implementations are built with large test data sets to validate that they will work. Everything should be compatible with content distribution network (CDN) caching. diff --git a/roadmap.md b/roadmap.md index 79f506dde..7684e316d 100644 --- a/roadmap.md +++ b/roadmap.md @@ -48,7 +48,7 @@ from instead of repeating each field. ### Domain and Vendor extensions Ideally there is a way for domains (like Earth Observation / satellite imagery) or specific vendors to publish -more meta information about the additional fields they use. The STAC mechanisms should enable a full `Item` with +more meta information about the additional fields they use. The STAC mechanisms should enable a full Item with all the extra fields included to be self-describing, so clients could understand more than just the core fields. This likely would involve ways of defining additional schemas, and ways to share those schemas and validate a response against several schemas. This could be some additional mechanics in Catalog API (likely optional, to diff --git a/validation/README.md b/validation/README.md index 825fd6430..5056ead4d 100644 --- a/validation/README.md +++ b/validation/README.md @@ -20,7 +20,7 @@ In the following chapter there are commands to run a validation of any STAC agai **Warning:** Not all validation is fully complete. For items, the validator does not yet check for `self` links. The `href` checking is probably too loose right now, it just checks for a string, see the -'relative vs absolute links' section in the [Item spec](../item-spec/item-spec.md) for reasons why. +'relative vs absolute links' section in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for reasons why. ### Catalogs @@ -30,12 +30,12 @@ To run the validation for a catalog file: npm run validate_catalog -- -d ../catalog-spec/examples/catalog.json ``` -### Datasets +### Collections -To run the validation for a dataset file: +To run the validation for a collection file: ```bash -npm run validate_dataset -- -d ../dataset-spec/examples/sentinel2.json +npm run validate_collection -- -d ../collection-spec/examples/sentinel2.json ``` ### Extensions diff --git a/validation/package.json b/validation/package.json index a3b8f6255..d99f308c8 100644 --- a/validation/package.json +++ b/validation/package.json @@ -1,6 +1,6 @@ { "name": "stac_validation", - "description": "Package to validate STAC items, catalogs and datasets.", + "description": "Package to validate STAC items, catalogs and collections.", "version": "0.6.0", "author": "STAC Team", "license": "Apache-2.0", @@ -12,6 +12,6 @@ "validate_item": "node_modules/.bin/ajv validate -s ../item-spec/json-schema/stac-item.json -r ../item-spec/json-schema/geojson.json --verbose", "validate_extension": "node_modules/.bin/ajv validate --verbose", "validate_catalog": "node_modules/.bin/ajv validate -s ../catalog-spec/json-schema/catalog.json -r ../item-spec/json-schema/geojson.json --verbose", - "validate_dataset": "node_modules/.bin/ajv validate -s ../dataset-spec/json-schema/dataset.json --verbose" + "validate_collection": "node_modules/.bin/ajv validate -s ../collection-spec/json-schema/collection.json --verbose" } }