proposal to add 'error' function

proposals/0013-error-function.md

@@ -0,0 +1,57 @@
+# Add 'error' function
+
+|||
+|---|---
+| **JEP**    |  20
+| **Author** | Sebastien Rosset
+| **Created**| 22-March-2023
+| **[SemVer](https://semver.org/spec/v2.0.0.html#summary)** | 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:
+```json
+{ "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`.
+1. 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.
+   1. Constructing a JSON schema may be difficult when the input data is generated by a 3rd-party component.
+   1. JSON schema validation may have a significant runtime cost, especially for large documents with a complex schema.
+1. 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?