From 57500275bb9418bf0a9eb70a695e2f1eab8c7b66 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Wed, 14 Oct 2026 21:10:15 -0400 Subject: [PATCH 1/6] add processing:expression results --- CHANGELOG.md | 2 ++ README.md | 26 +++++++++++++++++++++++--- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6838d0c..5657783 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Recommended `processing:expression` with `format: results` for literal data processing results. + ### Changed ### Deprecated diff --git a/README.md b/README.md index 7590950..576b27c 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,26 @@ Potential expression formats with examples: | `gdal-calc` | string | A [`gdal_calc.py`](https://gdal.org/programs/gdal_calc.html) expression based on numpy syntax. | `A*logical_or(A<=177,A>=185)` | | `openeo` | object | [openEO process](https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes) | [Example](https://raw.githubusercontent.com/Open-EO/openeo-processes/1.2.0/normalized_difference.json) | | `rio-calc` | string | A [rio-calc](https://rasterio.readthedocs.io/en/latest/topics/calc.html) (RasterIO) expression | `(b4-b1)/(b4+b1)` | +| `results` | [Literal](#literal-result) \| Map | A literal data processing results. | `{"mean": 0.5, "stddev": 0.1}` | + +#### Literal Result + +Represents a literal data processing result. +The value can be any literal value (e.g., a `number`, `string`, `boolean`, or `null`). +If an `object` or `array` value is needed, it must be provided in a nested object with result identifiers to avoid ambiguity. + +> ![NOTE] +> It is typically not recommended to have `object` or `array` unless they are very small values (e.g.: a bbox `[xmin, ymin, xmax, ymax]`). +> Bigger results should instead be indicated in Assets via `href` and corresponding `type` to better interpret their contents. + +When a result is provided directly (e.g., `processing:expression: {format: results, expression: 3.1416}`), this should indicate that +the referenced `processing-expression`, `processing-execution`, or `processing-software` produced a nameless literal result. +For example, a CLI script that prints a value with no specific identifier. + +When provided as a map (e.g., `processing:expression: {format: results, expression: {"mean": 0.5, "stddev": 0.1}}`), +this should indicate that the respective named-outputs produced the provided literal values. +Those names would typically be indicated in an _openEO_ or _OGC API - Process_ process description, or some other kind +of metadata definition, obtained from one of the `processing-*` [Relation Type](#relation-types) link. ## Relation types @@ -183,7 +203,7 @@ The following types should be used as applicable `rel` types in the | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | | source_for | URL to a STAC Item that was derived from this Item (forward provenance, inverse of `derived_from`). | | processing-expression | A processing chain (or script) that describes how the data has been processed. | -| processing-execution | URL to any resource representing the processing execution (e.g. OGC Process API). | +| processing-execution | URL to any resource representing the processing execution (e.g. _OGC API - Process_). | | processing-software | URL to any resource that identifies the software and versions used for processing the data, e.g. a `Pipfile.lock` (Python) or `package-lock.json` (NodeJS). | | processing-validation | URL to any kind of validation that has been applied after processing, e.g. a validation report or a script used for validation. | @@ -197,10 +217,10 @@ 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. +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 +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 From 0d234a93ed403dce4339c5178c9913e870aa4cce Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Wed, 14 Oct 2026 21:18:00 -0400 Subject: [PATCH 2/6] fix rendering --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 576b27c..a81897b 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ Represents a literal data processing result. The value can be any literal value (e.g., a `number`, `string`, `boolean`, or `null`). If an `object` or `array` value is needed, it must be provided in a nested object with result identifiers to avoid ambiguity. -> ![NOTE] +> [!NOTE] > It is typically not recommended to have `object` or `array` unless they are very small values (e.g.: a bbox `[xmin, ymin, xmax, ymax]`). > Bigger results should instead be indicated in Assets via `href` and corresponding `type` to better interpret their contents. From e37387451a38187a59932ea033dba5630f373cf5 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Wed, 14 Oct 2026 21:21:40 -0400 Subject: [PATCH 3/6] fix names OAP --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a81897b..e661e7c 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ For example, a CLI script that prints a value with no specific identifier. When provided as a map (e.g., `processing:expression: {format: results, expression: {"mean": 0.5, "stddev": 0.1}}`), this should indicate that the respective named-outputs produced the provided literal values. -Those names would typically be indicated in an _openEO_ or _OGC API - Process_ process description, or some other kind +Those names would typically be indicated in an _OGC API - Processes_ or _openEO_ process description, or some other kind of metadata definition, obtained from one of the `processing-*` [Relation Type](#relation-types) link. ## Relation types @@ -203,7 +203,7 @@ The following types should be used as applicable `rel` types in the | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | | source_for | URL to a STAC Item that was derived from this Item (forward provenance, inverse of `derived_from`). | | processing-expression | A processing chain (or script) that describes how the data has been processed. | -| processing-execution | URL to any resource representing the processing execution (e.g. _OGC API - Process_). | +| processing-execution | URL to any resource representing the processing execution (e.g. _OGC API - Processes_). | | processing-software | URL to any resource that identifies the software and versions used for processing the data, e.g. a `Pipfile.lock` (Python) or `package-lock.json` (NodeJS). | | processing-validation | URL to any kind of validation that has been applied after processing, e.g. a validation report or a script used for validation. | From 778a1cadcee397c54fbb60f4f2fe156962ce7a29 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Wed, 14 Oct 2026 21:23:47 -0400 Subject: [PATCH 4/6] fix lint md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e661e7c..d85dd24 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ For example, a CLI script that prints a value with no specific identifier. When provided as a map (e.g., `processing:expression: {format: results, expression: {"mean": 0.5, "stddev": 0.1}}`), this should indicate that the respective named-outputs produced the provided literal values. -Those names would typically be indicated in an _OGC API - Processes_ or _openEO_ process description, or some other kind +Those names would typically be indicated in an *OGC API - Processes* or *openEO* process description, or some other kind of metadata definition, obtained from one of the `processing-*` [Relation Type](#relation-types) link. ## Relation types @@ -203,7 +203,7 @@ The following types should be used as applicable `rel` types in the | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | | source_for | URL to a STAC Item that was derived from this Item (forward provenance, inverse of `derived_from`). | | processing-expression | A processing chain (or script) that describes how the data has been processed. | -| processing-execution | URL to any resource representing the processing execution (e.g. _OGC API - Processes_). | +| processing-execution | URL to any resource representing the processing execution (e.g. *OGC API - Processes*). | | processing-software | URL to any resource that identifies the software and versions used for processing the data, e.g. a `Pipfile.lock` (Python) or `package-lock.json` (NodeJS). | | processing-validation | URL to any kind of validation that has been applied after processing, e.g. a validation report or a script used for validation. | From a50539bd9e877a0fc6d42c7384a0b9a6baa2a590 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Mon, 19 Oct 2026 21:30:52 -0400 Subject: [PATCH 5/6] proposal processing:expression parameters and asset roles --- README.md | 69 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index d85dd24..83f2509 100644 --- a/README.md +++ b/README.md @@ -160,38 +160,59 @@ This list is not exhaustive and can be extended with the processing level specif ### Expression Object -| Field Name | Type | Description | -| ---------- | ------ | ----------- | -| format | string | **REQUIRED** The type of the expression that is specified in the `expression` property. | -| expression | \* | **REQUIRED** An expression compliant with the `format` specified. The expression can be any data type and depends on the `format` given, e.g. string or object. | +| Field Name | Type | Description | +| ---------- | --------------- | ----------- | +| format | string | **REQUIRED** The type of the expression that is specified in the `expression` property (see [Format](#format) examples). | +| expression | \* | **REQUIRED** An expression compliant with the `format` specified. The expression can be any data type and depends on the `format` given, e.g. string or object. | +| parameters | Map | Optional parameters relevant for the context of the `format` specified (e.g., _openEO_ or _OGC API - Processes_ execution inputs, a variable name/file mapping for `gdal-calc`, etc. | + +#### Format Potential expression formats with examples: -| Format | Type | Description | Example | -| ----------- | ------ | ----------- | ------- | -| `gdal-calc` | string | A [`gdal_calc.py`](https://gdal.org/programs/gdal_calc.html) expression based on numpy syntax. | `A*logical_or(A<=177,A>=185)` | -| `openeo` | object | [openEO process](https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes) | [Example](https://raw.githubusercontent.com/Open-EO/openeo-processes/1.2.0/normalized_difference.json) | -| `rio-calc` | string | A [rio-calc](https://rasterio.readthedocs.io/en/latest/topics/calc.html) (RasterIO) expression | `(b4-b1)/(b4+b1)` | -| `results` | [Literal](#literal-result) \| Map | A literal data processing results. | `{"mean": 0.5, "stddev": 0.1}` | +| Format | Type | Description | Example | +| ------------------ | ------ | ----------- | ------- | +| `gdal-calc` | string | A [`gdal_calc.py`](https://gdal.org/programs/gdal_calc.html) expression based on numpy syntax. | `A*logical_or(A<=177,A>=185)` | +| `openeo` | object | An [openEO process](https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes) | [Example](https://raw.githubusercontent.com/Open-EO/openeo-processes/1.2.0/normalized_difference.json) | +| `ogcapi-processes` | object | An [OGC ProcessDescription](https://docs.ogc.org/is/18-062r2/18-062r2.html#ogc_process_description) | [Example](https://schemas.opengis.net/ogcapi/processes/part1/1.0/examples/json/ProcessDescription.json) | +| `rio-calc` | string | A [rio-calc](https://rasterio.readthedocs.io/en/latest/topics/calc.html) (RasterIO) expression | `(b4-b1)/(b4+b1)` | + +> [!NOTE] +> To ensure portability, `format` may employ a specific profile URI from a registered naming authority +> that explicitly describes the represented `expression` without ambiguity. -#### Literal Result +#### Parameters -Represents a literal data processing result. -The value can be any literal value (e.g., a `number`, `string`, `boolean`, or `null`). -If an `object` or `array` value is needed, it must be provided in a nested object with result identifiers to avoid ambiguity. +The `parameters` object represents a mapping of named entities that can be interpreted by the `format` expression and +their corresponding values. The specific structure of those values and how they can be applied is specific to the `format`. -> [!NOTE] -> It is typically not recommended to have `object` or `array` unless they are very small values (e.g.: a bbox `[xmin, ymin, xmax, ymax]`). -> Bigger results should instead be indicated in Assets via `href` and corresponding `type` to better interpret their contents. +For example, an _OGC API - Processes_ or _openEO_ taking an input named `threshold` could supply their respective +_ProcessDecription_ or _Process Graph_ in `expression`, and along it, the `"parameters": {"threshold": 0.5}` inputs +it employed for its execution. -When a result is provided directly (e.g., `processing:expression: {format: results, expression: 3.1416}`), this should indicate that -the referenced `processing-expression`, `processing-execution`, or `processing-software` produced a nameless literal result. -For example, a CLI script that prints a value with no specific identifier. +## Asset Roles -When provided as a map (e.g., `processing:expression: {format: results, expression: {"mean": 0.5, "stddev": 0.1}}`), -this should indicate that the respective named-outputs produced the provided literal values. -Those names would typically be indicated in an *OGC API - Processes* or *openEO* process description, or some other kind -of metadata definition, obtained from one of the `processing-*` [Relation Type](#relation-types) link. +In certain cases, such as when large data is employed or produced by a processing expression, it may not be convenient +or reasonable to provide inputs and results inline of the STAC object. For this purpose, the following roles are defined +to annotate [Asset Objects](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#assets). + +| Role | Description | +| --------------------- | ----------- | +| processing-input | An Asset that represents an individual input (e.g., a configuration file required by the processing expression). Note that an input STAC object should instead use the `derived_from` link [relation type](#relation-types). | +| processing-parameters | An Asset that embeds the entire processing parametrization contents that were submitted. This is similar to [Parameters](#parameters) but is not limited to `application/json` and can contain much more data. | +| processing-output | An Asset that represents an invidivudal output (possibily amongst multiple) that was generated by the processing expression. These Assets should typically include `data` role as well, although not strictly required. | +| processing-results | An Asset that embeds the entire processing results contents generated by the processing expression (e.g., an _OGC API - Processes_ [Results](https://schemas.opengis.net/ogcapi/processes/part1/1.0/examples/json/Result.json) document. | + +> [!NOTE] +> For each Asset that includes those roles, it is *STRONGLY RECOMMENDED* to include both a `profile` URI and a `type` field +> that will respectively describe the nature of the their contents. Alternate representations of those Assets could then +> be provided using other equivalent content negotiation by profile mechanisms. + +> [!WARNING] +> The abscence of the `processing-output` role does **NOT** necessarily indicate that a certain Asset is not a result +> of the processing. This is to support previous versions of the extension and existing STAC definitions that did not +> supply it. Instead, it should be interpreted as *additional indication* to distinguish various Assets amongst +> themselves, notably when inputs and outputs are combined. ## Relation types From e249cdbe9b859e73ef432aa22f96633bd196454b Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Mon, 19 Oct 2026 21:35:26 -0400 Subject: [PATCH 6/6] update changelog --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5657783..e17b695 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Recommended `processing:expression` with `format: results` for literal data processing results. +- New `parameters` field under `processing:expression` to provide a mapping of named input values employed. +- Asset roles `processing-input`, `processing-output`, `processing-parameters` and `processing-results`. +- Recommendation to employ `profile` in Asset using the above roles and examples for common applications. ### Changed