Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Guidance for AI agents

This repository contains the specification of the STAC Processing extension. It contains no application code.

- Read [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md) before you propose, write or review a change.
The README is the specification. The contributing rules apply to you as they apply to human contributors.
- The [Scope section of the README](README.md#scope) is the authority for what belongs in this extension.
If a request is out of scope, say so and give the reason. Do not implement it in a different form.
- Do not guess. If the specification or the data provider does not give a value, do not invent one.
This includes processing levels, versions and identifiers.
- Run `npm test` before you say that a change is complete.
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- Clarified the scope of the extension in the README (lineage and traceability of the data, not the description of applications or jobs).
No change to the fields, the relation types or the JSON Schema.
- Moved the contribution rules and the test instructions from the README to `CONTRIBUTING.md`.
- Added `AGENTS.md`, a short file that points AI coding agents to the README and to `CONTRIBUTING.md`.

### Deprecated

### Removed
Expand Down
66 changes: 66 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Contributing

All contributions are subject to the
[STAC Specification Code of Conduct](https://github.com/radiantearth/stac-spec/blob/master/CODE_OF_CONDUCT.md).
For contributions, please follow the
[STAC specification contributing guide](https://github.com/radiantearth/stac-spec/blob/master/CONTRIBUTING.md).
The rules below add the specifics of this repository. They apply to all contributors, people and AI agents.

## Repository content

| Path | Content |
| ------------------------- | ------- |
| `README.md` | The specification. It is the source of truth. |
| `json-schema/schema.json` | The JSON Schema that validates the fields. |
| `examples/` | STAC documents that show the extension. The tests validate them. |
| `CHANGELOG.md` | The list of changes, in the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. |

## Scope

Before you propose a new field, relation type or role, make sure that it is in the scope of the extension.
The [Scope section of the README](README.md#scope) gives the scope and a test for new proposals.
If an existing field or relation type can already carry the information, prefer a better description or a new example to a new field.
If you are not sure, open an issue before you write the change.

## Rules for changes

- Keep changes small. One subject for each pull request.
- A change to a field needs four updates: the table in `README.md`, `json-schema/schema.json`, one example in `examples/`
and one entry in `CHANGELOG.md` below `[Unreleased]`.
- Relation types and asset roles are defined only in `README.md`. The JSON Schema does not validate them.
- Do not change the version. The schema identifier, `package.json` and the release headings in `CHANGELOG.md`
change only when a maintainer makes a release.
- Do not remove or rename a field, and do not make the validation more strict, without an agreement of the maintainers.
These are breaking changes.
- Use real data in examples when possible. Do not invent identifiers or values for real datasets.
- The stability that users can expect, and thus the review that a change needs, depends on the
[maturity classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity) of the extension.

## Running tests

The same checks that run as checks on PRs 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](https://nodejs.org/en/download/).

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

```bash
npm install
```

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

```bash
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:

```bash
npm run format-examples
```

The Markdown rules are in `.github/remark.yaml`. The most frequent failures are lines longer than 150 characters,
HTML in Markdown, literal URLs without angle brackets and broken internal links.
68 changes: 39 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,18 @@
- **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Candidate
- **Owner**: @emmanuelmathot

Processing metadata is considered to be data that indicate from which processing chain a data originates and how the data itself has been produced.
Overall, it helps to increase traceability and search among processing levels and multiple algorithm versions.
The Processing extension records the processing lineage of a data product:
where the data comes from, who processed it, when, with which software version, and to which processing level.
Its purpose is traceability. A data user can follow a product back through its processing chain (e.g. L0 → L1 → L2),
tell apart products from different processing baselines,
and search with the qualifiers that are in common use in Earth Observation, such as the processing level.

Often, data items are the result of one or more waterfall processing pipeline. Tracing information such as the processing facility,
Often, data items are the result of one or more waterfall processing pipelines. Tracing information such as the processing facility,
the algorithm version or the processing date helps in the data version management.

The extension describes the data, not the processor.
It does not describe an application, a workflow or a job as a resource of its own. See [Scope](#scope) for the boundary.

This extension applies to STAC Items and STAC Collections. As these processing information are often closely bound to the Collection level
and therefore are shared across all items, it is recommended adding the fields to the corresponding STAC Collection.

Expand All @@ -23,6 +29,35 @@ and therefore are shared across all items, it is recommended adding the fields t
- [JSON Schema](json-schema/schema.json)
- [Changelog](./CHANGELOG.md)

## Scope

All metadata in this extension answers one question: **what happened to this data before it reached the user?**

### In scope

- **Qualifiers** that identify the processing state of the data and that users search and filter on:
`processing:level`, `processing:version`, `processing:facility`, `processing:datetime`, `processing:datastrip_id`.
- **Lineage**, i.e. the chain of products that the data comes from:
`processing:lineage` and the relation types `derived_from` and `source_for`.
- **A record of the processing that was applied**, as far as it helps to understand and to trace the data:
`processing:software`, `processing:expression` and the relation types `processing-expression`, `processing-execution`,
`processing-software` and `processing-validation`.

### Out of scope

- **The description of an application, process or workflow as a resource of its own**:
its interface, its input and output definitions, its entry points or its runtime environment.
Use the [Application extension](https://github.com/stac-extensions/application),
the [MLM extension](https://github.com/stac-extensions/mlm) for machine learning models,
or a dedicated standard such as *OGC API - Processes* or CWL.
- **A complete description of a job that a client can submit or run again**, e.g. the job request and the job results documents.
This extension can link to such resources with the relation type `processing-execution`, but it does not define their content.
- **Processing that can be applied to the data in the future**. The extension records only processing that has occurred.

The metadata in this extension helps reproducibility, but it does not guarantee it.
For example, a `processing:expression` records the transformation that was applied.
It is not a promise that a client can execute it.

## Fields

The fields in the table below can be used in these parts of STAC documents:
Expand Down Expand Up @@ -191,29 +226,4 @@ The following types should be used as applicable `rel` types in the

All contributions are subject to the
[STAC Specification Code of Conduct](https://github.com/radiantearth/stac-spec/blob/master/CODE_OF_CONDUCT.md).
For contributions, please follow the
[STAC specification contributing guide](https://github.com/radiantearth/stac-spec/blob/master/CONTRIBUTING.md) 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](https://nodejs.org/en/download/).

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

Then to check markdown formatting and test the examples against the JSON schema, you can run:
```bash
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:
```bash
npm run format-examples
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the rules for changes and for the instructions to run the tests.
Loading