Consider adding a runtime 'error()' function

[springcomp]

@sebastien-rosset proposes a new error() function that will fail the evaluation with runtime errors.

[springcomp]

User-defined runtime errors

JEP
Author	Sebastien Rosset
Created	22-March-2023
SemVer	MINOR

Abstract

This JEP proposes a new function error() that raises a runtime error.
This could be used to detect and raise an error when input JSON documents have unexpected data.

Motivation

AFAIK, there is no dedicated function to raise a runtime error within a JMESpath expression.

Specification

Add a new error function that takes a string expression.
If the error function is evaluated, an error is raised with the specified string message.

Rationale

Suppose we have the following JSON documents:

{ "id": "eth0", "status": "up" }
{ "id": "eth1", "status": "down" }

In this example, the values of status are either up or down.
Suppose the JMESpath author wants to:

1. Map the values of status to 0 and 1.
2. Raise an error when an expected status value is encountered. For example, when the value of status is set to degraded.

((status == 'up') && `1`) || ((status == 'down') && `0`) || error(join(" ", ["invalid value", status]))

Other options that have been considered

1. When appropriate, use a JSON schema to validate the input. However, this may not always be the right tool:
   1. The JSON schema may not be available.
   2. Constructing a JSON schema may be difficult when the input data is generated by a 3rd-party component.
   3. JSON schema validation may have a significant runtime cost, especially for large documents with a complex schema.
2. Leverage the fact that some JMESpath expressions are invalid, e.g., to_number('bad') would raise an error. However, this is a kludgy workaround.

((status == 'up') && `1`) || ((status == 'down') && `0`) || to_number('bad')

Implementation Notes

Are there any details that implementers should try to follow?

[springcomp]

For the record, one of my concerns was with this sentence int the spec:

The result of applying a JMESPath expression against a JSON document will always result in valid JSON, provided there are no errors during the evaluation process. Structured data in, structured data out.

But it appears this proposal will not violate this part.

[sebastien-rosset]

Agreed. There are many syntactically correct expressions that yield an error. For example, to_number('bad') does not result in valid JSON since it causes an error "during the evaluation process".