This document explains the structure and content of a STAC Catalog. A STAC Catalog is a collection of STAC Items. These Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain links to Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of online browsing by people.
Catalogs are not intended to be queried. Their purpose is discovery: to be browsed by people and crawled by machines to build a search index. A Catalog can be represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Catalog.
- Examples
- See a minimal example, as well a fuller example includes links to several items.
- JSON Schema
The Catalog section of the Overview document provides background information on the structure of catalogs as well as links to best practices. This specification lays out the requirements and fields to be compliant.
This Catalog specification primarily defines a structure for information to be discoverable. Any use that is publishing a set of related spatiotemporal assets is strongly recommended to also use the STAC Collection specification 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.
| Element | Type | Description |
|---|---|---|
| stac_version | string | REQUIRED. The STAC version the catalog implements. STAC versions can be mixed, but please keep the recommended best practices in mind. |
| stac_extensions | [string] | A list of extension identifiers the Catalog implements. |
| id | string | REQUIRED. Identifier for the catalog. |
| title | string | A short descriptive one-line title for the catalog. |
| description | string | REQUIRED. Detailed multi-line description to fully explain the catalog. CommonMark 0.29 syntax MAY be used for rich text representation. |
| links | [Link Object] | REQUIRED. A list of references to other documents. |
stac_extensions: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official content extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example pointcloud for the Point Cloud extension. This does not apply for API extensions. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file.
This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions.
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. |
A more complete list of possible 'rel' types can be seen at the IANA page of Link Relation Types.
Please see the chapter 'relative vs absolute links' in the Item spec for a discussion on that topic, as well as the use of links section of the catalog best practices document.
The following types are commonly used as rel types in the Link Object of a STAC Catalog:
| Type | Description |
|---|---|
| self | STRONGLY RECOMMENDED. Absolute URL to the location that the catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or Collection. Catalogs should include a link to their root, even if it's the root and points to itself. |
| parent | URL to the parent STAC Catalog or Collection. Non-root catalogs should include a link to their parent. |
| child | URL to a child STAC Catalog or Collection. |
| item | URL to a STAC Item. |
Note: A link to at least one item or child catalog is REQUIRED.
The extensions page gives an overview about relevant extensions for STAC Catalogs.