ietf-wg-jsonpath / draft-ietf-jsonpath-base

Development of a JSONPath internet draft
https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/
Other
58 stars 20 forks source link

Function Well-typedness section feels clunky #439

Closed gregsdennis closed 1 year ago

gregsdennis commented 1 year ago

The section in question (and subject to some change soon) is

https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/blob/7d016f14ecbde412dfdc2fd4476f0b20a27867bb/draft-ietf-jsonpath-base.md?plain=1#L1512-L1521

The part that feels clunky to me is the first line:

A function expression is well-typed if all of the following are true:

While not wrong, when you get into the bullet points, it feels odd that we're saying "all of the following are true" when only one things ever applies due to the conditions each item defines.

We're saying we have three options, A, B, and C and then we define rules:

(I know I made a big stink about changing "rules" to "scenarios" in a previous PR, but each of these statements conforms to the definition I gave for a "rule.")

The thing that feels weird is that we're saying they all must be true, which... is "correct" because the requirements are conditionally applied, but also it seems that (because of the conditions) only one ever actually applies, meaning that the other two are more "not applicable" than they are "true."

Maybe if we instead said:

A function expression is well-typed under the following rules:

Previous to the current text (before the type system was introduced), we had:

A function expression is syntactically valid if:

cabo commented 1 year ago

I was also thinking of turning this into a table.

gregsdennis commented 1 year ago

A table could be nice, too, but the "all of following must be true" language still needs adjustment.

glyn commented 1 year ago

I agree this section is rather tedious to read.

glyn commented 1 year ago

Oh, and regardless of whether a table could be crammed into the document, it would be good to somehow check that all the permutations have been covered correctly. It's too hard to hold the possibilities in my small head while reading the current text...