Adds return value schemas for child processes

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New processes in proposal state
     - `is_infinite`
     - `nan`
+- Added return value details (property `returns`) for the schemas with the subtype `process-graph`. [API#350](https://github.com/Open-EO/openeo-api/issues/350)
+- `apply_neighborhood`: Clarify behavior for data cubes returned by the child processes and for that add the exception `DataCubePropertiesImmutable`.
 
 ### Changed
 - Added `proposals` folder for experimental processes. Experimental processes are not covered by the CHANGELOG and MAY include breaking changes! [#196](https://github.com/Open-EO/openeo-processes/issues/196), [#207](https://github.com/Open-EO/openeo-processes/issues/207), [PSC#8](https://github.com/Open-EO/PSC/issues/8)

aggregate_spatial.json

@@ -49,7 +49,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the vector data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {
@@ -72,7 +78,7 @@
         }
     ],
     "returns": {
-        "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are stored as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.",
+        "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is used for the dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are added as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.",
         "schema": {
             "type": "object",
             "subtype": "vector-cube"

aggregate_temporal.json

@@ -112,7 +112,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {
@@ -157,7 +163,7 @@
         }
     ],
     "returns": {
-        "description": "A data cube with the same dimensions. The dimension properties (name, type, labels, reference system and resolution) remain unchanged, except for the resolution and dimension labels of the given temporal dimension.",
+        "description": "A new data cube with the same dimensions. The dimension properties (name, type, labels, reference system and resolution) remain unchanged, except for the resolution and dimension labels of the given temporal dimension.",
         "schema": {
             "type": "object",
             "subtype": "raster-cube"

aggregate_temporal_period.json

@@ -62,7 +62,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {
@@ -88,7 +94,7 @@
         }
     ],
     "returns": {
-        "description": "A data cube with the same dimensions. The dimension properties (name, type, labels, reference system and resolution) remain unchanged, except for the resolution and dimension labels of the given temporal dimension. The specified temporal dimension has the following dimension labels (`YYYY` = four-digit year, `MM` = two-digit month, `DD` two-digit day of month):\n\n* `hour`: `YYYY-MM-DD-00` - `YYYY-MM-DD-23`\n* `day`: `YYYY-001` - `YYYY-365`\n* `week`: `YYYY-01` - `YYYY-52`\n* `dekad`: `YYYY-00` - `YYYY-36`\n* `month`: `YYYY-01` - `YYYY-12`\n* `season`: `YYYY-djf` (December - February), `YYYY-mam` (March - May), `YYYY-jja` (June - August), `YYYY-son` (September - November).\n* `tropical-season`: `YYYY-ndjfma` (November - April), `YYYY-mjjaso` (May - October).\n* `year`: `YYYY`\n* `decade`: `YYY0`\n* `decade-ad`: `YYY1`",
+        "description": "A new data cube with the same dimensions. The dimension properties (name, type, labels, reference system and resolution) remain unchanged, except for the resolution and dimension labels of the given temporal dimension. The specified temporal dimension has the following dimension labels (`YYYY` = four-digit year, `MM` = two-digit month, `DD` two-digit day of month):\n\n* `hour`: `YYYY-MM-DD-00` - `YYYY-MM-DD-23`\n* `day`: `YYYY-001` - `YYYY-365`\n* `week`: `YYYY-01` - `YYYY-52`\n* `dekad`: `YYYY-00` - `YYYY-36`\n* `month`: `YYYY-01` - `YYYY-12`\n* `season`: `YYYY-djf` (December - February), `YYYY-mam` (March - May), `YYYY-jja` (June - August), `YYYY-son` (September - November).\n* `tropical-season`: `YYYY-ndjfma` (November - April), `YYYY-mjjaso` (May - October).\n* `year`: `YYYY`\n* `decade`: `YYY0`\n* `decade-ad`: `YYY1`",
         "schema": {
             "type": "object",
             "subtype": "raster-cube"

apply.json

@@ -37,7 +37,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {

apply_dimension.json

@@ -41,7 +41,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {

apply_neighborhood.json

@@ -38,7 +38,14 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The data cube with the newly computed values and the same dimensions. The dimension properties (name, type, labels, reference system and resolution) must remain unchanged, otherwise a `DataCubePropertiesImmutable` exception will be thrown.",
+                    "schema": {
+                        "type": "object",
+                        "subtype": "raster-cube"
+                    }
+                }
             }
         },
         {
@@ -214,6 +221,9 @@
     "exceptions": {
         "DimensionNotAvailable": {
             "message": "A dimension with the specified name does not exist."
+        },
+        "DataCubePropertiesImmutable": {
+            "message": "The dimension properties (name, type, labels, reference system and resolution) must remain unchanged."
         }
     }
 }

array_apply.json

@@ -64,7 +64,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new array.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {

array_contains.json

@@ -27,7 +27,7 @@
         }
     ],
     "returns": {
-        "description": "Returns `true` if the list contains the value, false` otherwise.",
+        "description": "`true` if the list contains the value, false` otherwise.",
         "schema": {
             "type": "boolean"
         }

array_element.json

@@ -1,7 +1,7 @@
 {
     "id": "array_element",
     "summary": "Get an element from an array",
-    "description": "Returns the element with the specified index or label from the array.\n\nEither the parameter `index` or `label` must be specified, otherwise the `ArrayElementParameterMissing` exception is thrown. If both parameters are set the `ArrayElementParameterConflict` exception is thrown.",
+    "description": "Gives the element with the specified index or label from the array.\n\nEither the parameter `index` or `label` must be specified, otherwise the `ArrayElementParameterMissing` exception is thrown. If both parameters are set the `ArrayElementParameterConflict` exception is thrown.",
     "categories": [
         "arrays",
         "reducer"

array_filter.json

@@ -65,7 +65,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "`true` if the value should be kept in the array, otherwise `false`.",
+                    "schema": {
+                        "type": "boolean"
+                    }
+                }
             }
         },
         {

array_find.json

@@ -26,7 +26,7 @@
         }
     ],
     "returns": {
-        "description": "Returns the index of the first element with the specified value. If no element was found, `null` is returned.",
+        "description": "The index of the first element with the specified value. If no element was found, `null` is a.",
         "schema": [
             {
                 "type": "null"

array_labels.json

@@ -1,7 +1,7 @@
 {
     "id": "array_labels",
     "summary": "Get the labels for an array",
-    "description": "Returns all labels for a labeled array in the data cube. The labels have the same order as in the array.",
+    "description": "Gives all labels for a labeled array in the data cube. The labels have the same order as in the array.",
     "categories": [
         "arrays"
     ],

count.json

@@ -43,7 +43,13 @@
                             "optional": true,
                             "default": null
                         }
-                    ]
+                    ],
+                    "returns": {
+                        "description": "`true` if the element should increase the counter, otherwise `false`.",
+                        "schema": {
+                            "type": "boolean"
+                        }
+                    }
                 },
                 {
                     "title": "All elements",

dimension_labels.json

@@ -1,7 +1,7 @@
 {
     "id": "dimension_labels",
     "summary": "Get the dimension labels",
-    "description": "Returns all labels for a dimension in the data cube. The labels have the same order as in the data cube.",
+    "description": "Gives all labels for a dimension in the data cube. The labels have the same order as in the data cube.",
     "categories": [
         "cubes"
     ],

eq.json

@@ -44,7 +44,7 @@
         }
     ],
     "returns": {
-        "description": "Returns `true` if `x` is equal to `y`, `null` if any operand is `null`, otherwise `false`.",
+        "description": "`true` if `x` is equal to `y`, `null` if any operand is `null`, otherwise `false`.",
         "schema": {
             "type": [
                 "boolean",

examples/array_contains_nodata.json

@@ -18,7 +18,7 @@
         }
     ],
     "returns": {
-        "description": "Returns `true` if the list contains a no-data value, false` otherwise.",
+        "description": "`true` if the list contains a no-data value, false` otherwise.",
         "schema": {
             "type": "boolean"
         }

examples/array_find_nodata.json

@@ -18,7 +18,7 @@
         }
     ],
     "returns": {
-        "description": "Returns the index of the first element with a no-data value. If only data values are available, `null` is returned.",
+        "description": "The index of the first element with a no-data value. If only data values are available, `null` is returned.",
         "schema": [
             {
                 "type": "null"

load_collection.json

@@ -194,7 +194,13 @@
                                     "description": "Any data type."
                                 }
                             }
-                        ]
+                        ],
+                        "returns": {
+                            "description": "`true` if the data should be loaded into the data cube, otherwise `false`.",
+                            "schema": {
+                                "type": "boolean"
+                            }
+                        }
                     }
                 },
                 {

merge_cubes.json

@@ -52,7 +52,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the merged data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             },
             "default": null,
             "optional": true

meta/subtype-schemas.json

@@ -222,7 +222,13 @@
                             "description": "Any data type."
                         }
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "`true` if the data should be used, otherwise `false`.",
+                    "schema": {
+                        "type": "boolean"
+                    }
+                }
             }
         },
         "output-format": {

neq.json

@@ -44,7 +44,7 @@
         }
     ],
     "returns": {
-        "description": "Returns `true` if `x` is *not* equal to `y`, `null` if any operand is `null`, otherwise `false`.",
+        "description": "`true` if `x` is *not* equal to `y`, `null` if any operand is `null`, otherwise `false`.",
         "schema": {
             "type": [
                 "boolean",

proposals/aggregate_spatial_binary.json

@@ -54,7 +54,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the vector data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {
@@ -77,7 +83,7 @@
         }
     ],
     "returns": {
-        "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are stored as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.",
+        "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is used for the dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are added as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.",
         "schema": {
             "type": "object",
             "subtype": "vector-cube"

proposals/aggregate_spatial_window.json

@@ -42,7 +42,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {

proposals/debug.json

@@ -49,7 +49,7 @@
         }
     ],
     "returns": {
-        "description": "Returns the data as passed to the `data` parameter.",
+        "description": "The data as passed to the `data` parameter without any modification.",
         "schema": {
             "description": "Any data type is allowed."
         }

proposals/filter_labels.json

@@ -25,7 +25,7 @@
                 "parameters": [
                     {
                         "name": "value",
-                        "description": "A single dimension label to compare against. The data type of the parameter depends on the dimension labels stored for the dimension.",
+                        "description": "A single dimension label to compare against. The data type of the parameter depends on the dimension labels set for the dimension.",
                         "schema": [
                             {
                                 "type": "number"
@@ -44,7 +44,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "`true` if the dimension label should be kept in the data cube, otherwise `false`.",
+                    "schema": {
+                        "type": "boolean"
+                    }
+                }
             }
         },
         {

proposals/reduce_dimension_binary.json

@@ -46,7 +46,13 @@
                         "optional": true,
                         "default": null
                     }
-                ]
+                ],
+                "returns": {
+                    "description": "The value to be set in the new data cube.",
+                    "schema": {
+                        "description": "Any data type."
+                    }
+                }
             }
         },
         {