Skip to content

Files

Latest commit

 

History

History
204 lines (131 loc) · 8.11 KB

README.md

File metadata and controls

204 lines (131 loc) · 8.11 KB

Open Science Catalog Extension Specification

This document explains the Open Science Catalog Extension to the SpatioTemporal Asset Catalog (STAC) specification.

Terms

This extension makes use of certain terms and definitions.

Project

A science project dealing with theme, often bound to a certain geographic region. Each project can produce a a number of products, which are sub-collections of type product.

In the OSC STAC Extension, projects are depicted as STAC Collections with additional fields.

Product

The description of a science product which was produced in the context of a project.

In the OSC STAC Extension, products are depicted as STAC Collections with additional fields.

A product can be linked to sub-collections/catalogs of any shape or form or directly reference the STAC Items actually referencing the data files the Product is comprised of. STAC Items should mirror the fields of the product collection for search purposes.

Theme

A thematic grouping of science projects and products, such as "Oceans", "Atmosphere" or "Land".

Variable

An physical variable observed by a science product, such as "Wind stress" or "Geomagnetic field".

EO Mission

A set of satellite missions which provided input for the product.

Workflow

A definition of processing steps defined in a project that can be executed in an experiment to generate a product.

Experiment

A specific execution of a workflow that generated a product.

Fields

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

  • Catalogs
  • Collections
  • Item Properties
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links

NOTE: The Item fields can be added to Collection summaries, but should usually not be added to the summaries as the same fields already exist in the collection as top-level properties anyway. As such the extension does not validate Collection summaries.

Projects and Products

Field Name Type Description
osc:type string REQUIRED. The underlying type of this resource. Either "project" or "product". This field then defines what other fields are allowed and required.
osc:status string REQUIRED. This field details whether the project or product is planned, ongoing, or has been completed.

Additionally, the following fields from other extensions apply:

Products only

Fields that apply when the osc:type is set to product:

Field Name Type Description
osc:project string REQUIRED. The name of the project the product is associated with.
osc:region string The name of the geographic region the project or product is dealing with if any, e.g "Arctic" or "Agulhas".
osc:variables [string] The names of the variables the product is observing, e.g "Wind stress" or "Geomagnetic field".
osc:missions [string] The names of the satellite missions which provided input for this product.
osc:experiment string The name of the experiment that created the product.

Projects only

Fields that apply when the osc:type is set to project:

Field Name Type Description
osc:workflows [string] The names of the workflows created by the project.

Additionally, the following fields from other extensions apply:

Contacts

The following fields should be implemented from the Contacts extension:

Field Name Type Description
contacts [Contact Object] A list of contacts qualified by their role.

The following roles for contacts SHALL be used:

  • The role for the technical officer of a project is technical_officer.
  • The role for consortium partners is consortium_member.

Themes

The following fields should be implemented from the Themes extension:

Field Name Type Description
themes [Theme Object] The names of the themes the project or product is dealing with.

The themes field can contain concepts from different controlled vocabularies (via scheme). By default this extension only asks to add concepts for the scheme https://github.com/stac-extensions/osc#theme.

Relation types

The following types should be used as applicable rel types in the Link Object.

Type Description
related Links to resources that are identified in the osc: fields and themes, e.g. a link to the project as identified in the osc:project field.
environment Links to a file that identifies the execution environment of an experiment (applicable mostly to OGC API - Records)
input Links to a file that identifies any input parameters of an experiment (applicable mostly to OGC API - Records)

Other entities

Variables

Variables don't use any osc: fields, but they expose themes and link to themes via the related relation type.

Workflows and Experiments (via OGC API - Records)

Although this extension is a STAC extension, similar fields with the same osc: prefix are also used in OGC API - Records that describe workflows and experiments.

The following fields occur in workflows:

  • osc:project (string, required)

Additionally, workflows add links with the relation type child that point to the experiments.

The following fields occur in experiments:

  • osc:workflow (string, required)

Additionally, experiments add links with the relation type child that point to the products.

For all entities referenced in osc:project and osc:workflow, links with the related relation type are provided.

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples