Link to process examples instead of inlining them. #285

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `GET /udf_runtimes`: Added optional `title` property for UDF runtimes. [#266](https://github.com/Open-EO/openeo-api/issues/266)
 - `GET /service_types`: Added optional `title` and `description` properties for service types. [#266](https://github.com/Open-EO/openeo-api/issues/266)
 - `GET /file_formats`: Added optional `description` property for file formats. [#266](https://github.com/Open-EO/openeo-api/issues/266)
+- `GET /processes`: Mention of link `rel` type `example` to refer to examples. [#285](https://github.com/Open-EO/openeo-api/issues/285)
 - `year` subtype to subtype-schemas.json. `year` was also added to subtypes `temporal-interval` and `temporal-intervals`. [#267](https://github.com/Open-EO/openeo-api/issues/267)
 
 ### Changes
@@ -27,6 +28,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
         - `ServiceArgumentRequired` -> `ServiceConfigRequired`
     - Removed all error messages with tag `Processes` (`CRSInvalid`, `CoordinateOutOfBounds`) or related to storing file formats (`FormatUnsupported`, `FormatArgumentUnsupported`, `FormatArgumentInvalid`, `FormatUnsuitable`) as they are usually defined directly in the process specification as `exceptions`.
 
+### Removed
+- `GET /processes`: Examples containing process graphs. Use links with `rel` type `example` and `type` set to `application/json` instead. [#285](https://github.com/Open-EO/openeo-api/issues/285)
+
 ### Fixed
 - `POST /jobs` and `POST /services`: Clarified definition of `Location` header in `HTTP 201` responses. [#269](https://github.com/Open-EO/openeo-api/issues/269)
 - Several clarifications and improvements for the documentation.

openapi.yaml

@@ -4683,31 +4683,20 @@ components:
           $ref: '#/components/schemas/process_exceptions'
         examples:
           type: array
-          description: >-
-            Examples, may be used for tests. Either `process_graph` or
-            `arguments` must be set, never both.
+          description: Examples, may be used for unit tests.
           items:
             title: Process Example
             type: object
-            oneOf:
-              - title: Process Example with Process Graph
-                required:
-                  - process_graph
-                properties:
-                  process_graph:
-                    $ref: '#/components/schemas/process_graph'
-              - title: Process Example with Arguments
-                required:
-                  - arguments
-                properties:
-                  arguments:
-                    $ref: '#/components/schemas/process_arguments'
+            required:
+              - arguments
             properties:
               title:
                 type: string
                 description: A title for the example.
               description:
                 $ref: '#/components/schemas/process_description'
+              arguments:
+                $ref: '#/components/schemas/process_arguments'
               returns:
                 nullable: true
         links:
@@ -4722,7 +4711,9 @@ components:
             (link to older version) and `successor-version` (link to newer version) can also be used
             to show the relation between versions.
 
-            2. `cite-as`: For all DOIs associated with the process, the respective DOI
+            2. `example`: Used to refer to examples of user-defined processes that use this process.
+
+            3. `cite-as`: For all DOIs associated with the process, the respective DOI
             links should be added.
 
             For additional relation types see also the lists of