"Well-Typedness of Function Expressions" function parameter organization

[gregsdennis]

The organization of the expansion of point 2 in "Well-Typedness of Function Expressions" can be improved.

Currently, it's grouped by the kind of argument, but it's much easier to consume if you group by function parameter type. (Also, I think we're missing some cases.)

I'm going to put it in a table so it's a bit easier to see.

Argument Kind	Parameter Types	Unlisted parameter types where this argument is valid
literal	ValueType
singular query	ValueType	LogicalType (kinda included via logical-expr below) NodesType (maybe included in logical-expr?)
general query	NodesType	LogicalType (kinda included via logical-expr below)
logical-expr (feels odd to reference ABNF here and not in the others)	LogicalType
function	type match or func:NodesType in param:LogicalType

The above answers the question

If I have an argument X, where can I use it?

I don't think that's going to be a very common question JSON Path authors will have. I think the more common question will be

What kinds of things can I use for arguments to this function?

To that end, we need to invert the grouping by using parameter type as the key. Doing this, we get

Parameter Type	Availble arguments
ValueType	literal, singular query, ValueType function
LogicalType	any logical-expr (including singular/general query, LogicalType function, NodesType function)
NodesType	singular/general query, NodesType function

This is a lot easier to consume and mentally digest. It also better serves as a reference for JSON Path authors.

(We lose the "function type matches parameter type" thing, but I don't think we need to explicitly say that.)

[danielaparker]

Questions:

(1) A nodelist is defined in the draft as a list of location-value pairs. Is there a distinction between nodelist and NodesType?

(2) If a function has a parameter that accepts arguments of NodesType, does it receive a list of location-value pairs?

[gregsdennis]

(1) A nodelist is defined in the draft as a list of location-value pairs. Is there a distinction between nodelist and NodesType?

Abstractly, yes. A nodelist is an instance (or member) of NodesType.

(2) If a function has a parameter that accepts arguments of NodesType, does it receive a list of location-value pairs?

Yes.

[danielaparker]

@gregsdennis, thanks.

Are the following statements correct?

• The JSONPath query in its entirety always evaluates to a nodelist (a list of location-value pairs)
• Within a filter, a JSONPath query evaluates to either a value of type ValueType or a nodelist of type NodesType. If the query satisfies the requirements of a Singular Query, it evaluates to a value of type ValueType, otherwise it evaluates to a nodelist of type NodesType.

[gregsdennis]

The JSONPath query in its entirety always evaluates to a nodelist (a list of location-value pairs)

Yes

• Within a filter, a JSONPath query evaluates to either a value of type ValueType or a nodelist of type NodesType. If the query satisfies the requirements of a Singular Query, it evaluates to a value of type ValueType, otherwise it evaluates to a nodelist of type NodesType.

A query always evaluates to a nodelist (NodesType). In the context of a filter expression, if it's a singular query, the resulting nodelist can be implicitly converted to a value (ValueType) by extracting the single node's value (or Nothing for an empty nodelist).

[cabo]

• The JSONPath query in its entirety always evaluates to a nodelist (a list of location-value pairs)

Yes.

• Within a filter, a JSONPath query evaluates to either a value of type ValueType or a nodelist of type NodesType. If the query satisfies the requirements of a Singular Query, it evaluates to a value of type ValueType, otherwise it evaluates to a nodelist of type NodesType.

Types only exist in the function interface. The declared type of the function you use a query for determines what the function gets.

[danielaparker]

@cabo, thanks.

Types only exist in the function interface. The declared type of the function you use a query for determines what the function gets.

What about the operator interface? Operators are much like functions.

Would it be correct to say that the comparison operators take arguments of type ValueType?

[glyn]

@cabo, thanks.

Types only exist in the function interface. The declared type of the function you use a query for determines what the function gets.

What about the operator interface? Operators are much like functions.

Would it be correct to say that the comparison operators take arguments of type ValueType?

The spec doesn't say that. It could, be we decided against rolling out the (function) type system across the whole spec as it didn't seem to add much value, it would impact readability, and it is not without its own complexity. If you'd like to explore that option, please could we do it on the mailing list so it gets appropriate visibility? I don't think that topic is so relevant to this particular issue.

[cabo]

Back to the issue as proposed.

(We lose the "function type matches parameter type" thing, but I don't think we need to explicitly say that.)

We definitely need to say that. We also have to transfer all the other information from what is there now to the transposed form.

I don't think the result would be an improvement.

[gregsdennis]

(We lose the "function type matches parameter type" thing, but I don't think we need to explicitly say that.)

We definitely need to say that.

We do say it, just not in those words. It's explicitly listed in the (new) table.

We also have to transfer all the other information from what is there now to the transposed form.

What other information is there? I've stated all of the possible arguments for each parameter type.

I don't think the result would be an improvement.

The improvement is the question that is answered.

• "Where can I put this argument?" vs
• "What kinds of things can I use for arguments to this function?"

Users are going to ask the second question, not the first.

[glyn]

I think part of the difficulty in comparing the approach in this issue with the draft is that it's not obvious (at least to me) how much of section 2.4.3 the table would be replacing. I think it would be just section (2). Right?

We also have to transfer all the other information from what is there now to the transposed form.

What other information is there? I've stated all of the possible arguments for each parameter type.

Even replacing just section (2), the following information is missing:

• What to do when a singular query is used as an argument for a parameter of type ValueType
• What to do when a query (including a singular query) is used as an argument for a parameter of type LogicalType
• What to do when a function expression with result type NodesType is used as an argument for a parameter of type LogicalType