From 1d18c2cdaf5197572b7eb275c42999274f3fbdbd Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 17 Nov 2026 21:20:30 +0100 Subject: [PATCH 1/2] Clarify scope of the Processing extension in README and add guidance for AI agents in AGENTS.md --- AGENTS.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 4 +++ README.md | 41 +++++++++++++++++++++++-- 3 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ec58330 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# Guidance for AI agents + +This file gives instructions to AI coding agents and assistants that work in this repository. +Human contributors can read it as a short contribution checklist. + +## What this repository is + +This is the specification of the STAC Processing extension. It contains no application code. + +| 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 Items and Collections that show the extension. The tests validate them. | +| `CHANGELOG.md` | The list of changes, in the *Keep a Changelog* format. | + +## Scope comes first + +The extension records the processing lineage of a data product, for traceability. +It describes the data, not the processor. +The [Scope section of the README](README.md#scope) is the authority. Read it before you propose or review a change. + +Before you add a field, a relation type, an asset role or an expression format, apply the test from the README: + +1. Does it tell a data user something about the origin or the processing state of the data? If not, stop. +2. Does it describe a tool, a service or a job, independently of the data? + Then it does not belong here. Point to the Application extension, the MLM extension or the applicable standard. +3. Can an existing field or relation type already carry the information? + Then propose a better description or an example, not a new field. + +If a request is out of scope, say so and give the reason. Do not implement it in a different form. +If you are not sure, ask the maintainer before you write the change. + +### Test for new proposals + +Proposals for new fields, relation types or roles should pass this test: + +1. Does it tell a data user something about the origin or the processing state of *this* data? + Then it can be part of this extension. +2. Does it describe a tool, a service or a job, and is it also correct without this data? + Then it belongs to another extension or standard. A link from the data to that resource is the right connection. +3. Can an existing field or relation type already carry the information? + Then prefer a better description or a new example to a new field. + +## 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 the maintainer makes a release. +- Do not remove or rename a field, and do not make validation more strict, unless the maintainer asks for it. + These are breaking changes. +- Do not change the lists of values (processing levels, expression formats) into closed enumerations. They are open on purpose. +- Use real data in examples when possible. Do not invent identifiers for real missions. + +## Tests + +Run the tests before you say that a change is complete: + +```bash +npm install +npm test +``` + +`npm test` checks the Markdown files (also this one) and validates the examples against the JSON Schema. +`npm run format-examples` corrects the formatting of the 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. + +## Writing style + +- Write short sentences with simple words. Many readers are not native English speakers. +- Use the terms of the STAC specification: Item, Collection, Asset, Link Object, relation type. +- Use the Earth Observation terms that the README already uses: processing level, processing baseline, datatake, datastrip. +- Give a real example for each new field, e.g. from the Sentinel or Landsat missions. + +## When you generate STAC metadata with this extension + +- Prefer the Collection for values that are the same for all Items. +- `processing:level` uses the short name: `L1`, not `Level 1`. +- Use `derived_from` links for input products. Do not copy the metadata of the inputs into the Item. +- Put a reference to external code, a container image or a job in a Link Object with the applicable relation type, + not in `processing:expression`. +- Do not provide a field if the provider does not give the value. Do not guess a processing level or a version. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6838d0c..72cdb32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ 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. +- Added `AGENTS.md` with guidance for AI coding agents that contribute to this repository. + ### Deprecated ### Removed diff --git a/README.md b/README.md index 7590950..c321fb7 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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: From 379ad78180a42616375a1318664b4990f59d79f4 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Wed, 18 Nov 2026 07:24:41 +0100 Subject: [PATCH 2/2] Refactor contribution guidelines: move rules and test instructions to CONTRIBUTING.md, add AGENTS.md for AI agents --- AGENTS.md | 94 +++++-------------------------------------------- CHANGELOG.md | 3 +- CONTRIBUTING.md | 66 ++++++++++++++++++++++++++++++++++ README.md | 27 +------------- 4 files changed, 78 insertions(+), 112 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md index ec58330..5a0326d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,87 +1,11 @@ # Guidance for AI agents -This file gives instructions to AI coding agents and assistants that work in this repository. -Human contributors can read it as a short contribution checklist. - -## What this repository is - -This is the specification of the STAC Processing extension. It contains no application code. - -| 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 Items and Collections that show the extension. The tests validate them. | -| `CHANGELOG.md` | The list of changes, in the *Keep a Changelog* format. | - -## Scope comes first - -The extension records the processing lineage of a data product, for traceability. -It describes the data, not the processor. -The [Scope section of the README](README.md#scope) is the authority. Read it before you propose or review a change. - -Before you add a field, a relation type, an asset role or an expression format, apply the test from the README: - -1. Does it tell a data user something about the origin or the processing state of the data? If not, stop. -2. Does it describe a tool, a service or a job, independently of the data? - Then it does not belong here. Point to the Application extension, the MLM extension or the applicable standard. -3. Can an existing field or relation type already carry the information? - Then propose a better description or an example, not a new field. - -If a request is out of scope, say so and give the reason. Do not implement it in a different form. -If you are not sure, ask the maintainer before you write the change. - -### Test for new proposals - -Proposals for new fields, relation types or roles should pass this test: - -1. Does it tell a data user something about the origin or the processing state of *this* data? - Then it can be part of this extension. -2. Does it describe a tool, a service or a job, and is it also correct without this data? - Then it belongs to another extension or standard. A link from the data to that resource is the right connection. -3. Can an existing field or relation type already carry the information? - Then prefer a better description or a new example to a new field. - -## 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 the maintainer makes a release. -- Do not remove or rename a field, and do not make validation more strict, unless the maintainer asks for it. - These are breaking changes. -- Do not change the lists of values (processing levels, expression formats) into closed enumerations. They are open on purpose. -- Use real data in examples when possible. Do not invent identifiers for real missions. - -## Tests - -Run the tests before you say that a change is complete: - -```bash -npm install -npm test -``` - -`npm test` checks the Markdown files (also this one) and validates the examples against the JSON Schema. -`npm run format-examples` corrects the formatting of the 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. - -## Writing style - -- Write short sentences with simple words. Many readers are not native English speakers. -- Use the terms of the STAC specification: Item, Collection, Asset, Link Object, relation type. -- Use the Earth Observation terms that the README already uses: processing level, processing baseline, datatake, datastrip. -- Give a real example for each new field, e.g. from the Sentinel or Landsat missions. - -## When you generate STAC metadata with this extension - -- Prefer the Collection for values that are the same for all Items. -- `processing:level` uses the short name: `L1`, not `Level 1`. -- Use `derived_from` links for input products. Do not copy the metadata of the inputs into the Item. -- Put a reference to external code, a container image or a job in a Link Object with the applicable relation type, - not in `processing:expression`. -- Do not provide a field if the provider does not give the value. Do not guess a processing level or a version. +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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 72cdb32..3e5bb5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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. -- Added `AGENTS.md` with guidance for AI coding agents that contribute to this repository. +- 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..93b448d --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index c321fb7..5cbecc9 100644 --- a/README.md +++ b/README.md @@ -226,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.