--- title: "Validate a user-defined process (graph)" method: POST path: "/validation" tags: ["Data Processing", "User-Defined Processes"] --- # Validate a user-defined process (graph) `POST /validation` Validates a user-defined process without executing it. A user-defined process is considered valid unless the `errors` array in the response contains at least one error. Checks whether the process graph is schematically correct and the processes are supported by the back-end. It MUST also check the arguments against the schema, but checking whether the arguments are adequate in the context of data is OPTIONAL. For example, a non-existing band name may get rejected only by a few back-ends. The validation MUST NOT throw an error for unresolvable process parameters. Back-ends MUST validate the process graph. Validating the corresponding metadata is OPTIONAL. Errors that usually occur during processing MAY NOT get reported, e.g. if a referenced file is accessible at the time of execution. Back-ends can either report all errors at once or stop the validation once they found the first error. Please note that a validation always returns with HTTP status code 200. Error codes in the 4xx and 5xx ranges MUST be returned only when the general validation request is invalid (e.g. server is busy or properties in the request body are missing), but never if an error was found during validation of the user-defined process (e.g. an unsupported process). ## Request body - ProcessGraphWithMetadata - `id` string — The identifier for the process. It MUST be unique across its namespace (e.g. predefined processes or user-defined processes). Clients SHOULD warn the user if a user-defined process is added with the same identifier as one of the predefined process. - `summary` string — A short summary of what the process does. - `description` string, commonmark — Detailed description to explain the entity. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``` ``process_id()`` ``` - `categories` string[] — A list of categories. - `parameters` ProcessParameter[] — A list of parameters. The order in the array corresponds to the parameter order to be used in clients that do not support named parameters. **Note:** Specifying an empty array is different from (if allowed) `null` or the property being absent. An empty array means the process has no parameters. `null` / property absent means that the parameters are unknown as the user has not specified them. There could still be parameters in the process graph, if one is specified. - `name` string, required — A unique name for the parameter. Using [snake case](https://en.wikipedia.org/wiki/Snake_case) (e.g. `window_size` or `scale_factor`) is RECOMMENDED. - `description` string, commonmark, required — Detailed description to explain the entity. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``` ``process_id()`` ``` - `optional` boolean — Determines whether this parameter is optional to be specified even when no default is specified. Clients SHOULD automatically set this parameter to `true`, if a default value is specified. Back-ends SHOULD NOT fail, if a default value is specified and this flag is missing. - `deprecated` boolean — Declares that the specified entity is deprecated with the potential to be removed in any of the next versions. It should be transitioned out of usage as soon as possible and users should refrain from using it in new implementations. - `experimental` boolean — Declares that the specified entity is experimental, which means that it is likely to change or may produce unpredictable behavior. Users should refrain from using it in production, but still feel encouraged to try it out and give feedback. - `default` unknown - `returns` ProcessReturnValue — Description of the data that is returned by this process. - `description` string, commonmark — Detailed description to explain the entity. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``` ``process_id()`` ``` - `schema` union, required — Either a single data type or a list of data types for process parameter or process return values. - ProcessJsonSchema — A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later. JSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved). This allows clients to consume the schemas much better. Clients are not expected to support dereferencing `$refs`. Note: The specified schema in the OpenAPI document is only a common subset of JSON Schema. Additional keywords from the JSON Schema specification MAY be used. - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string' - JsonSchemaType[] - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - unknown - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - JsonSchema[] - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - … - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - … - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - … - JsonSchema — A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later. JSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved). This allows clients to consume the schemas much better. Clients are not expected to support dereferencing `$refs`. Note: The specified schema in the OpenAPI document is only a common subset of JSON Schema. Additional keywords from the JSON Schema specification MAY be used. - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - … - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - … - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - … - ProcessJsonSchema[] — A list of data types supported, specified as JSON Schemas. - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string' - JsonSchemaType[] - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - unknown - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - JsonSchema[] - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - … - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - … - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - … - JsonSchema — A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later. JSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved). This allows clients to consume the schemas much better. Clients are not expected to support dereferencing `$refs`. Note: The specified schema in the OpenAPI document is only a common subset of JSON Schema. Additional keywords from the JSON Schema specification MAY be used. - `$schema` string, uri — The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. - `$id` string, uri — ID of your JSON Schema. - `type` union — The allowed data type(s) for a value. If this property is not present, all data types are allowed. - … - `pattern` string, regex — The regular expression a string value must match against. - `enum` unknown[] — An exclusive list of allowed values. - … - `minimum` number — The minimum value (inclusive) allowed for a numerical value. - `maximum` number — The maximum value (inclusive) allowed for a numerical value. - `minItems` number — The minimum number of items required in an array. - `maxItems` number — The maximum number of items required in an array. - `items` union — Specifies schemas for the items in an array. - … - `deprecated` boolean — Declares that the specified entity is deprecated with the potential to be removed in any of the next versions. It should be transitioned out of usage as soon as possible and users should refrain from using it in new implementations. - `experimental` boolean — Declares that the specified entity is experimental, which means that it is likely to change or may produce unpredictable behavior. Users should refrain from using it in production, but still feel encouraged to try it out and give feedback. - `exceptions` ProcessExceptions — Declares exceptions (errors) that might occur during execution of this process. This list is just for informative purposes and may be incomplete. This list MUST only contain exceptions that stop the execution of a process and MUST NOT contain warnings, notices or debugging messages. It is meant to primarily contain errors that have been caused by the user. It is RECOMMENDED that exceptions are referred to and explained in process or parameter descriptions. The keys define the error code and MUST match the following pattern: `^\w+$` This schema follows the schema of the general openEO error list (see errors.json). - `examples` object[] — Examples, may be used for unit tests. - `title` string — A title for the example. - `description` string, commonmark — Detailed description to explain the entity. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``` ``process_id()`` ``` - `arguments` ProcessArguments, required — unresolved $ref - `returns` unknown - `links` Link[] — Links related to this process, e.g. additional external documentation. Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `latest-version`: If a process has been marked as deprecated, a link SHOULD point to the preferred version of the process. The relation types `predecessor-version` (link to older version) and `successor-version` (link to newer version) can also be used to show the relation between versions. 2. `version-history`: A link to a changelog and/or a list of versions of the process (see also the relation types `latest-version` etc.). 3. `example`: Links to examples of other processes that use this process. 4. `cite-as`: For all DOIs associated with the process, the respective DOI links SHOULD be added. 5. `license`: Links to applicable license(s). The link titles should reflect the license names. 6. `author`: Links to authors of the process. The `href` can use the `mailto:` protocol to link to an email address. The link titles should reflect the author names and affiliations. 7. `canonical`: Points to a publicly accessible and more long-lived URL. For additional relation types see also the lists of [common relation types in openEO](#section/API-Principles/Web-Linking). - `rel` string, required — Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible. - `href` string, uri, required — The value MUST be a valid URL. - `type` string — The value MUST be a string that hints at the format used to represent data at the provided URI, preferably a media (MIME) type. - `title` string — Used as a human-readable label for a link. - `process_graph` ProcessGraph — A process graph defines a graph-like structure as a connected set of executable processes. Each key is a unique identifier (node ID) that is used to refer to the process in the graph. ## Response `200` Returns the validation result as a list of errors. An empty list indicates a successful validation. - object - `errors` Error[], required — A list of validation errors. - `id` string — A back-end MAY add a unique identifier to the error response to be able to log and track errors with further non-disclosable details. A client could communicate this id to a back-end provider to get further information. - `code` string, required — The code is either one of the standardized error codes or a custom code, for example specified by a user in the `inspect` process. - `message` string, required — A message explaining what the client may need to change or what difficulties the server is facing. - `links` Link[] — Links related to this log entry / error, e.g. to a resource that provides further explanations. For relation types see the lists of [common relation types in openEO](#section/API-Principles/Web-Linking). - `rel` string, required — Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible. - `href` string, uri, required — The value MUST be a valid URL. - `type` string — The value MUST be a string that hints at the format used to represent data at the provided URI, preferably a media (MIME) type. - `title` string — Used as a human-readable label for a link. ## Other responses - `4XX` — The request can not be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications. The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6). This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid. See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json) - `5XX` — The request can not be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response. The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6). See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json) --- [API](https://skmtc.net/open-eo/apis/openeo-api.md) · [All operations](https://skmtc.net/open-eo/apis/openeo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/open-eo/openeo-api/revisions/0c5e31955a19/schema)