This is part of a series or minor issues that aim to enable support for flexible styling and theming of the JMESPath site.

The table cells that illustrate function usage all share the same td HTML tag.
Please, consider adding a CSS-class to allow to format the cells from the Given, Expression and Result columns differently than those from the Presence and Description columns.

Only function tests that use the input data should reference it. Some effort should be made to go through and clean up these tests.

example:

Some functions are defined as taking arguments of a specific type, but are still allowed to return null when given invalid types.

For instance the ceil() function returns null on invalid input in the original implementations.
This seems to contradict the blanket statement from the specification that:

“Function arguments have types. If an argument for a function has the wrong type, an invalid-type error will occur.”

JMESPath Community implementations enforce strict type checking as much as possible, unless a compliance test exists.
Please, consider reviewing type-checking and make it more consistent.

Maybe this should be documented in the compatibility section of the compliance test suite?

This is part of a series or minor issues that aim to enable support for flexible styling and theming of the JMESPath site.

Multiple semantically distinct captions all share the same HTML h1 tag.

Please, consider adding a CSS class to differentiate those semantic usages of the captions.

For instance, each website section – like the Tutorial section shown in the screenshot above – has both an h1 tag with the section heading (i.e 'Tutorial') and a h1 tag with chapter headings (i.e 'Basic Expressions').

I think we may need to distinguish between:

• The website welcome header
• Each website main section (Tutorial, Examples, Libraries, Syntax and Functions)
• Each website section’s HTML tags like h2, h3 and so on might also need to be mapped to the same CSS class.

The unescaped-literal rule is one possibility to express the contents of a JSON string literal.
The grammar currently considers this syntax invalid:

`"{"`

Is this an error?

See this issue for more details.

See this issue for more details.

I am finding the existing markdown files have line terminators that break markdowns autowrapping.

PRs should trigger a autoformatter and linter to ensure correct document structure.

See this discussion for more details.

In light of this comment, is appears clarification is needed.

In fact, @jamesls was aware of potential confusions. and @mtdowling talked him out of moving the JEP forward.

[@jamesls] In this scenario we're evaluating foo.qux. foo evaluates to {"bar": "baz"}. So far so good. Next we evaluate the RHS of the sub expression, qux. We see the qux is not defined in the current object {"bar": "baz"} so we look in the scope object and see it's defined as "qux", so we use that value. I can see how some people might find that confusing. Maybe not.

[@mtdowling] We've spoken about this in person, but I wanted to leave feedback here to hopefully help drive this proposal forward. I stated this earlier, but I think that the current behavior of this JEP would be confusing.

I still think this feature brings more benefits as is as it brings confusions but I agree clarification is needed and changes may be made if necessary.

Sub Expressions

It appears the most common source for confusion is trying to use the scope when evaluating the RHS of a sub-expression.
The current implementations of the specification behave is unconditionnally simple:

• When evaluating an identifier, first lookup the current context.
• If not found in the context, lookup the call chain.

The confusion arises when trying such expressions:

• search( let({bar: 'bar'}, &foo.bar ) , {"foo": "foo"} ) -> "bar"

Whereas intuition would dictate that expression to evaluate to null instead, as bar is not a property of the "foo" string.

Pipe Expressions

It’s worth mentioning that JEP-19 standardized a small difference between evaluating a sub-expression vs a pipe-expression.

Thoughts must be applied when clarifying this JEP-11 in this context.
For the record, assuming we closed the confusion with sub-expression, I would still be comfortable with the following evaluations:

• search( let({bar: 'bar'}, &foo.bar ) , {"foo": "foo"} ) -> null
• search( let({bar: 'bar'}, &foo | bar ) , {"foo": "foo"} ) -> "bar"

The README.md file has a link to https://jmespath.site/specification.html, and currently this link is broken. I'm not sure if it's a temporary issue or not.
That links returns "We are sorry, but that page could not be found."

Any changes to the JMESPath specification (https://jmespath.site/specification.html) must have a JEP (JMESPath

It would help to include a link to the source for the spec, not just the generated html page. Or maybe it's already there in the HTML page, but since the link is broken, I cannot see it right now.

While JEP-12 Raw String Literals has been accepted, it has subsequently fallen behind and no longer matches the official grammar.

For instance, this test/literal.json test is not compliant with JEP-12 that does not allow backslash characters explicitely. On the other hand, it is not compliant with the official grammar either because \\ is expected to be a valid escape sequence for a single \ character.

https://github.com/jmespath-community/jmespath.test/blob/aa6fb5f942e852af1781d1f208c4069a15794a80/tests/literal.json#L194-L196

Please, consider updating JEP-12 to align with the grammar and the updated tests.

In most implementations, the rhs of a sub-expression is implemented differently when the lhs is a projection.
Due to the shape of the AST, the lhs is actually evaluated on the lhs projection.

However, when slicing a string, the rhs should be treated as a regular sub-expression.

As a result, in most implementations, the following expression does not evaluate correctly:

• 'foo'[::-1].length(@) should evaluate to 3.

In some implementations, the result is ``"oof"ornull`.

Please, consider adding a compliance test.

The literal rule currently requires the contents inside `…` to be a JSON value, but it should instead allow any RFC 8259 JSON text, which allows leading and/or trailing whitespace. For example, an expression like `1 ` should be valid and result in 1 (as is in fact already the case in the live demo at the top of https://jmespath.site/ ).

With JEP-12, raw-string literals where introduced and json-value was tighten to more strictly adhere to the JSON specification.

As a result, syntax like `foo` was being deprecated in favor of `"foo`".

As JMESPath Community intends to fully deprecate legacy syntax, a few changes will be made.

Please, consider documenting legacy syntax, clarifying its deprecation policy.

Please, consider adding notes about supporting legacy syntax and its relationship with regards to standards compliance.

Implementations were free to support legacy syntax after JEP-12 was introduced. This may mean that expressions like `foo` were still successfully parsed automatically. The deprecation process SHOULD discourage automatic parsing and qualify that as non-compliant behaviour. Additionally, the deprecation process SHOULD promote explicit opt-in to the legacy syntax if at all desirable for an implementation.

Numbers are incorrectly wrapped with [].

diff --git a/Examples.md b/Examples.md
index 423ff84..ce19262 100644
--- a/Examples.md
+++ b/Examples.md
@@ -8,7 +8,7 @@ value is greater than 20, we're creating a sub list of the name and age
 values.

 ```jmespath
-people[?age > [20]].[name, age]
+people[?age > `20`].[name, age]
 {
   "people": [
     {
@@ -39,7 +39,7 @@ greater than `20`. If instead we want to create the same hash structure
 but only include the `age` and `name` key, we can instead say:

 ```jmespath
-people[?age > [20]].{name: name, age: age}
+people[?age > `20`].{name: name, age: age}
 {
   "people": [
     {

This is part of a series or minor issues that aim to enable support for flexible styling and theming of the JMESPath site.

It does not seem to be possible to style the entire width of the site header.
Please, consider enabling CSS styling for the site banner.

I think the spec should support simple arithmetic operations in the way of the +, -, * and / operators.

A few things to keep in mind:

• What happens in case of illegal or overflowing operations. Does that return null or does that raise an error ?
• Parentheses would need to be involved to override precedence.
• The geek in me would love to support proper symbols for arithmetic operators in addition to their ASCII approximations:
  • – (U+2212 MINUS SIGN)
  • ÷ (U+00F7 DIVISION SIGN)
  • × (U+00D7 MULTIPLY SIGN)

I think a strong consensus exists for accepting the JEP-01 Lexical Scoping proposal that specifies the let() function.

From the grammar:

literal           = "`" json-value "`"

; The ``json-value`` is any valid JSON value with the one exception that the
; ``%x60`` character must be escaped.  While it's encouraged that implementations
; use any existing JSON parser for this grammar rule (after handling the escaped
; literal characters), the grammar rule is shown below for completeness::

json-value =/ json-quoted-string
json-quoted-string = %x22 1*(unescaped-literal / escaped-literal) %x22

escaped-literal   = escaped-char / (escape %x60)
escaped-char      = escape (
                        %x22 /          ; "    quotation mark  U+0022
                        %x5C /          ; \    reverse solidus U+005C
                        %x2F /          ; /    solidus         U+002F
                        %x62 /          ; b    backspace       U+0008
                        %x66 /          ; f    form feed       U+000C
                        %x6E /          ; n    line feed       U+000A
                        %x72 /          ; r    carriage return U+000D
                        %x74 /          ; t    tab             U+0009
                        %x75 4HEXDIG )  ; uXXXX                U+XXXX

The / (U+002F SOLIDUS) character is included in the escaped-char rule but I cannot understand why.

To me the / character does not need escaping and thus should be removed from this list.

There seems to be some demand for supporting regular expressions.

• jmespath/go-jmespath#64
• jmespath/jmespath.jep#23

This presents some challenges as there are many different dialects of regexp, although there is an effort around
specifying an interoperable regex format.

Also, regular expressions uses cases fall into three main categories:

• Matching patterns, which could be useful in filter-expressions. It either matches, or it does not.
• Replacing substrings.
• Capturing and extracting substrings in named (or numbered) groups.

So a JEP would need to come up with intuitive syntax for those use cases that would be relevant.

The interoperable regex format proposal referred to above only supports the first scenario. So maybe that’s the only scenario that requires extending the JMESPath syntax.

The last two scenarios may be supported using dedicated functions.

The JMESPath documentation refers to JSON objects as hash or even multi-select-hash.

I suggest keeping the multi-select-hash grammar rule name but changing the wording to the plain text in the specification to refer to simpler objects.

This issue tracks the progress towards the next iteration of the JMESPath specification.
These are the planned current issues and proposals included in the next version.

• #13

I recommend we establish a structured format for JEPs that allows the markdown to be baked into html documentation to be included in the site. Only some elements would be included from the JEP and additionally some elements would only exist for the purpose of inclusion in the documentation and would not directly contribute to the language spec.

This will require a actions workflow to automatically bake the JEPs and commit it to the jmespath.site repo.

All existing specification should also be loaded into a JEP-0 to include in this pipeline

This is part of a series or minor issues that aim to enable support for flexible styling and theming of the JMESPath site.

I feel the JMESPath logo is part of the original branding and should not be changed,
Here is the original logo:

Here is the new logo:

In particular the "Path" portion of the logo used to be in all uppercase. Whereas the "JME" portion of the logo used to be formatted with a very thin font.

The quoted-string rule currently requires at least one character between the quotation marks ( quoted-string = quote 1*(unescaped-char / escaped-char) quote), but it should not because JSON object members can be named like "". For example, an expression like `{"": "foo"}` | "" should be valid and result in "foo" (as is in fact already the case in the live demo at the top of https://jmespath.site/ ).