[JEP] proposal to add new 'error' function

[sebastien-rosset]

Add 'error' function

JEP	20
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]))

Since there is no built-in function to raise error, one may rely on the fact that some JMESpath expressions are invalid, e.g., to_number('bad') would raise an error, but this is kludgy.

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

Implementation Notes

Are there any details that implementers should try to follow?

[springcomp]

@sebastien-rosset thanks a lot for your feedback, and kudos for drafting the first version of a JEP !

I have some reservations about such a function though.
It seems to me the motivation is not sufficient to warrant such a function.

For instance, JMESPath has extensive type checking and error handing.
Provided that the expression is valid, it is guaranteed to produce valid JSON if fed valid JSON as input.

It seems to me valid JSON can be enforced before evaluating the JMESPath expression using JSON Schema validation for instance.

Is there a specific scenarios where you embed JMESPath into your own application and you cannot for some reason enforce a particular JSON schema to validate the input before hand?

[sebastien-rosset]

We have an application that processes a large amount of data in various formats. ETL pipelines are used to transform the data, including extraction and transformation of JSON documents. Some of the documents are indeed associated with a JSON schema, in which case we do rely on JSON schema validation. However, many JSON documents are schema-less. This is were additional functions such as error would be useful. I would say more generally, it would be extremely helpful to add support for extensibility, e.g. provide the ability to define custom functions.

[sebastien-rosset]

I have updated the JEP. We've tried JSON schema validation and it works in some cases. However, schema validation does incur significant runtime cost, especially for use cases to extract a small amount of data from complex JSON documents.

[springcomp]

Moved to a discussion for now.