Skip to content

Latest commit

 

History

History
110 lines (83 loc) · 5.42 KB

README.md

File metadata and controls

110 lines (83 loc) · 5.42 KB
Raw

Storage Extension Specification

This document explains the Storage Extension to the SpatioTemporal Asset Catalog (STAC) specification. It allows adding details related to cloud object storage access and costs to be associated with STAC Assets. This extension does not cover NFS solutions provided by PaaS cloud companies.

Fields

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
storage:schemes Map<string, Storage Scheme Object> REQUIRED. A property that contains all of the storage schemes used by Assets and Links in the STAC Item, Catalog or Collection.

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
  • Alternate Assets Object
Field Name Type Description
storage:refs [string] A property that specifies which schemes in storage:schemes may be used to access an Asset or Link. Each value must be one of the keys defined in storage:schemes.

Storage Scheme Object

Field Name Type Description
type string REQUIRED. Type identifier for the platform, see below.
platform string REQUIRED. The cloud provider where data is stored as URI or URI template to the API.
region string The region where the data is stored. Relevant to speed of access and inter region egress costs (as defined by PaaS provider).
requester_pays boolean Is the data "requester pays" (true) or is it "data manager/cloud provider pays" (false). Defaults to false.
... ... Additional properties as defined in the URL template or in the platform specific documents.

The properties title and description as defined in Common Metadata should be used as well.

platform

The platform field identifies the cloud provider where the data is stored as URI or URI template to the API of the service.

If a URI template is provided, all variables must be defined in the Storage Scheme Object as a property with the same name. For example, the URI template https://{bucket}.{region}.example.com must have at least the properties bucket and region defined:

{
  "type": "example",
  "platform": "https://{bucket}.{region}.example.com",
  "region": "eu-fr",
  "bucket": "john-doe-stac",
  "requester_pays": true
}

In case an href contains a non-HTTP URL that is not directly resolvable, the platform property must identify the host so that the URL can be resolved without further information. For example, this is especially useful to provide the endpoint URL for custom S3 providers. In this case the platform could effectively provide the endpoint URL.

type

We try to collect pre-defined templates and best pratices for as many providers as possible in this repository, but be aware that these are not part of the official extension releases. This extension just provides the framework, the provider best pratices may change at any time without a new version of this extension being released.

The following providers have defined best pratices at this point:

type Provider and Documentation
aws-s3 AWS S3
custom-s3 Generic S3 (non-AWS)
ms-azure Microsoft Azure

Feel encouraged to submit additional platform specifications via Pull Requests.

The type fields can be any value chosen by the implementor, but the types defined in the table above should be used as defined in the best practices. This ensures proper schema validation.

Contributing

See the Contributor documentation for details.