Re: Patch: Improve Boolean Predicate JSON Path Docs

On Jan 24, 2024, at 16:32, Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "David E. Wheeler" <david@justatheory.com> writes:
>
>> In any event, something to do with @@, perhaps to have some compatibility with `jsonb @> jsonb`? I don’t know why @@
wasimportant to have. 
>
> Yeah, that's certainly under-explained.  But it seems like I'm not
> getting traction for the idea of changing the behavior, so let's
> go back to just documenting it.

Curious about those discussions. On the one hand I find the distinction between the two behaviors to be odd, and to
produceunexpected results when they’re not used in the proper context. 

It’s reminds me of the Perl idea of context, where functions behave differently in scalar and list context, and if you
expectlist behavior on scalar context you’re gonna get a surprise. This is a bit of a challenge for those new to the
language,as they’re not necessarily aware of the context. 

> I spent some time going over your
> text and also cleaning up nearby shaky English, and ended with v8
> attached.  I'd be content to commit this if it looks good to you.

This looks very nice, thank you. A couple of comments.

> +      <para>
> +       Predicate check expressions are required in the
> +       <literal>@@</literal> operator (and the
> +       <function>jsonb_path_match</function> function), and should not be used
> +       with the <literal>@?</literal> operator (or the
> +       <function>jsonb_path_exists</function> function).
> +      </para>
> +     </note>
> +    </sect4>

I had this bit here:

      <para>
       Conversely, non-predicate <type>jsonpath</type> expressions should not be
       used with the <literal>@@</literal> operator (or the
       <function>jsonb_path_match</function> function).
      </para>

I think it’s important to let people know what the difference is in the behavior of the two forms, in every spot it’s
likelyto come up. SQL-standard JSON Path expressions should never be used in contexts (functions, operators) only
designedto work with predicate check expressions, and the docs should say so IMO. 

>    <para>
> -    The lax mode facilitates matching of a JSON document structure and path
> -    expression if the JSON data does not conform to the expected schema.
> +    The lax mode facilitates matching of a JSON document and path
> +    expression when the JSON data does not conform to the expected schema.


What do you think of also dropping the article from all the references to “the strict mode” or “the lax mode”, to make
them“strict mode” and “lax mode”, respectively? 

Thanks for the review!

Best,

David