Clarifies the terms "end"/"result" nodes and "root"/"child" process graphs (#572)

* Clarified the relation between "result nodes" and "end nodes", the usage of the `result` flag, and the relation between the outermost ("root") and "child" process graphs #547

* Update openapi.yaml

Co-authored-by: Stefaan Lippens <[email protected]>

---------

Co-authored-by: Stefaan Lippens <[email protected]>

Author: m-mohr

CHANGELOG.md

@@ -41,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Clarified the behaviour of `federation:backends` for `POST /validation`
 - Clarified the meaning of `expires` in batch job results
 - Clarified that `last_successful_check` (from Federation Extension) can be null.
+- Clarified the relation between result and end nodes, the usage of the result flag, and the relation between the outermost ("root") and child process graphs [#547](https://github.com/Open-EO/openeo-api/issues/547)
 - Fixed various OpenAPI issues reported by redocly lint
 
 ## [1.2.0] - 2021-05-25

openapi.yaml

@@ -323,10 +323,14 @@ info:
     ```
     A process node MUST always contain key-value-pairs named `process_id` and `arguments`. It MAY contain a `description`.
 
-    One of the nodes in a map of processes (the final one) MUST have the `result` flag set to `true`, all the other nodes can omit it as the default value is `false`. Having such a node is important as multiple end nodes are possible, but in most use cases it is important to exactly specify the return value to be used by other processes. Each child process graph must also specify a result node similar to the "main" process graph.
-
     `process_id` MUST be a valid process ID in the `namespace` given. Clients SHOULD warn the user if a user-defined process is added with the same identifier as one of the predefined process.
 
+    In the following, "end node" (also known as "leaf node") defines a node that is not referenced by any other node in the same process graph. The "root process graph" is the outermost process graph, which is not part of any other process graph.
+
+    A "result node" is a node (often an end node, but that's not required) that defines the return value of the process graph and has the `result` flag set to `true`. Exactly one of the nodes in a map of processes MUST have the `result` flag set to `true`, all the other nodes can omit it as the default value is `false`. Each child process graph MUST specify its own result node. The root process graph MUST also specify a result node although not strictly needed in all use cases.
+    
+    Having a result node is important as multiple end nodes are possible and in many use cases it is important to identify a specific return value for the process graph that is passed to other processes. The result node is not necessarily an end node.
+
     ### Arguments
 
     A process can have an arbitrary number of arguments. Their name and value are specified 
@@ -437,7 +441,7 @@ info:
 
     ### Full example for an EVI computation
 
-    Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel-2 imagery. The main process graph in blue, child process graphs in yellow:
+    Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel-2 imagery. The root process graph in blue, child process graphs in yellow:
 
     ![Graph with processing instructions](assets/pg-evi-example.png)