[Proposal] add `error` function

[sebastien-rosset]

Problem Statement

AFAIK, there is no built-in capability to raise errors from within a JMESpath expression. For example, suppose a JSON document has a status property, and its value is supposed to be up or down. The user wants to map up to 1 and down to 0, which could be done using the following JMESpath expression:

((status == 'up') && `1`) || `0`)

The user may want to detect and raise an error when the input document has a value other than up or down. A workaround is to rely on the fact that some JMESpath expressions are invalid, e.g., to_number('bad') would raise an error.

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

This works but it's very kludgy. In this specific example, one might argue this issue could be validated using a JSON schema, but sometimes there are no JSON schemas.

Proposal

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

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

Additional Information

The spec states errors are raised when problems are encountered during the evaluation process. Currently, the following errors are defined:

1. invalid-type
2. unknown-function
3. invalid-arity

Related: jmespath/jmespath.site#115 , jmespath/jmespath.site#116

[jamesls]

Moving over to jmespath.jep repo for consideration.