Appearance
For Experiments
FAIR Experiments Best Practices EarthCODE
In EarthCODE, Experiments are defined as a specific execution of a workflow which produced a Product. An Experiment captures the full context of how a Product was generated, linking together workflows, inputs, and configuration in a way that makes results reusable and reproducible.
An Experiment in EarthCODE typically includes:
- A human-readable description of the purpose and context
- A machine-executable workflow that transforms inputs into outputs
- A definition of the input data
- A configuration specifying parameters and settings used at runtime
Together, these components ensure that scientific results can be re-run, validated, and built upon. Experiments are described using structured OGC API Records metadata, which provide both the semantic and technical context for discovery and reuse across the Open Science Catalog.
Experiment Components
- Experiment Metadata: Central description that ties together workflow, inputs, configuration, and outputs.
- Purpose & Context: Concise summary explaining what the experiment achieves.
- Workflow: Link to a Workflow executable process definition (e.g. openEO graph, CWL workflow, Jupyter Notebook, MLflow model).
- Input Data: Products or datasets used as inputs, linked via unique identifiers.
- Configuration: Parameters, thresholds, or runtime settings applied when executing the workflow.
- Output Products: The resulting datasets, published as EarthCODE Products with references back to the experiment.
In short, a workflow defines the process, but an experiment defines the full execution: inputs, configuration, workflow, and outputs. This layered approach ensures that Products published in EarthCODE are not only FAIR but also traceable, reproducible, and citable.
FAIR Checklist
WARNING
Experiments are typically generated by EarthCODE integrated platforms rather than manually. You can describe the metadata for an experiment by hand, but first make sure to explore using integrated platforms tools! (e.g. Deep-Code for the DeepESDL platform)
Use this checklist to prepare your Experiment for publication in EarthCODE.
FAIR EarthCODE Experiments Standards
EarthCODE's standards for FAIR experiments follow the principles from Applying the FAIR Principles to computational workflows, in combination with FAIR Workflows, where:
| Findable (F) | Accessible (A) |
|---|---|
F1 — Experiments are assigned globally unique, persistent identifiers (e.g., F1.1 — Components at different granularity have distinct identifiers and links (e.g., F1.2 — Versions of experiments are explicitly identified (e.g., a F2 — Experiments are described with rich OGC API Records metadata (title, description, keywords, themes, contacts, inputs, environment, links). F3 — Metadata clearly and explicitly include the experiment identifier (and version when present). F4 — Experiments are indexed and searchable in the ESA Open Science Catalog and browseable via the STAC/Records browser. | A1 — Experiment records and their components are retrievable by identifier over standardized protocols (HTTPS/OGC API Records); linked artifacts (e.g., YAML, notebooks) resolve directly. A1.1 — Protocols are open, free, and universally implementable (HTTPS, JSON). A1.2 — Where needed, links may employ authentication/authorization (e.g., platform endpoints), while keeping metadata itself open. A2 — Metadata remain accessible in the catalog even if some external resources (e.g., a platform or repository) become unavailable. |
| Interoperable (I) | Reusable (R) |
I1 — Experiments and their run context use formal, accessible representations (OGC API Records in JSON); the referenced workflow must follow EarthCODE workflow standards (see Workflows). I2 — Metadata use controlled vocabularies (e.g., EarthCODE OSC themes/variables) and standard schemas. I3 — Experiments specify inputs/outputs and configuration in community formats (e.g., YAML for params, COG/Zarr/NetCDF for data) to enable exchange; workflow interface details are defined in Workflows. I4 — Records include qualified references to related objects: | R1 — Experiments are described with accurate, relevant attributes (purpose, inputs, configuration, execution environment such as R1.1 — A clear, accessible license is stated for the experiment record and any embedded artifacts (e.g., notebooks). R1.2 — Components (inputs, notebooks, environment files) carry their own clear licenses when applicable. R1.3 — Provenance links connect the experiment to the generating workflow and resulting product(s), enabling validation and re-runs. R2 — Experiments may reference other workflows or experiments to indicate alternatives, dependencies, or comparisons. R3 — Experiments align with Earth Observation community standards (OGC API Records, STAC/OSC vocabularies; preferred data formats like COG/Zarr/GeoParquet/NetCDF). |
EarthCODE FAIR Experiment Example
For example the ESA CCI Permafrost (Experiment). Published as an OGC API Record with a stable id and self link (F1, F3), it provides rich metadata (title, description, keywords, contacts, theme) in JSON (F2, I1) and is indexed in the ESA Open Science Catalog (F4). The record exposes distinct, citable components—input.yaml and environment.yaml—to capture parameters and the execution environment (F1.1, I4, R1). All resources are retrievable over open HTTPS (A1, A1.1), and catalog metadata persists even if external endpoints change (A2). Interoperability is achieved via OSC themes (e.g., cryosphere) and standard representations (JSON/YAML) (I2, I3), while qualified links connect the experiment to its generating workflow and resulting product (I4, R1.3). The record declares a license (R1.1) and aligns with EO community standards (OGC API Records; notebook environment specified via jupyter_kernel_info) (R3).
Details
json
{
"id": "esa-cci-permafrost",
"title": "ESA CCI permafrost",
"type": "Feature",
"conformsTo": [
"http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core"
],
"geometry": null,
"properties": {
"created": "2025-03-17T14:30:23.650003+00:00",
"updated": "2025-03-17T14:30:23.650003+00:00",
"type": "experiment",
"title": "ESA CCI permafrost",
"description": "cube generation workflow for esa-cci-permafrost",
"jupyter_kernel_info": {
"name": "deepesdl-xcube-1.8.3",
"python_version": 3.11,
"env_file": "https://github.com/deepesdl/cube-gen/blob/main/Permafrost/environment.yml"
},
"keywords": [
"Earth Science"
],
"contacts": [
{
"name": "Tejas Morbagal Harish",
"organization": "Brockmann Consult GmbH",
"position": "",
"links": [
{
"rel": "about",
"type": "text/html",
"href": "https://www.brockmann-consult.de/"
}
],
"contactInstructions": "",
"roles": [
"principal investigator"
]
}
],
"themes": [
{
"concepts": [
{
"id": "cryosphere"
}
],
"scheme": "https://github.com/stac-extensions/osc#theme"
}
],
"formats": [],
"license": "proprietary",
"osc:workflow": "esa-cci-permafrost"
},
"linkTemplates": [],
"links": [
{
"rel": "root",
"href": "../../catalog.json",
"type": "application/json",
"title": "Open Science Catalog"
},
{
"rel": "parent",
"href": "../catalog.json",
"type": "application/json",
"title": "Experiments"
},
{
"rel": "related",
"href": "../../workflows/esa-cci-permafrost/record.json",
"type": "application/json",
"title": "Workflow: ESA CCI permafrost"
},
{
"rel": "child",
"href": "../../products/esa-cci-permafrost/collection.json",
"type": "application/json",
"title": "esa-cci-permafrost"
},
{
"rel": "related",
"href": "../../projects/deep-earth-system-data-lab/collection.json",
"type": "application/json",
"title": "Project: DeepESDL"
},
{
"rel": "input",
"href": "./input.yaml",
"type": "application/yaml",
"title": "Input parameters"
},
{
"rel": "environment",
"href": "./environment.yaml",
"type": "application/yaml",
"title": "Execution environment"
},
{
"rel": "self",
"href": "https://esa-earthcode.github.io/open-science-catalog-metadata/experiments/esa-cci-permafrost/record.json",
"type": "application/json"
},
{
"rel": "related",
"href": "../../themes/cryosphere/catalog.json",
"type": "application/json",
"title": "Theme: Cryosphere"
}
]
}