Original text:
3.8. <del> A Normalized Path is a JSONPath with restricted syntax that identifies a node by providing a query that results in exactly that node.  For example, the JSONPath expression "$.book[?(@.price<10)]" could select two values with Normalized Paths "$['book'][3]" and "$['book'][5]".  For a given JSON value, there is a one to one correspondence between the value's nodes and the Normalized Paths that identify these nodes.  Note that there is precisely one Normalized Path that identifies each node. A JSONPath implementation may output Normalized Paths instead of, or in addition to, the values identified by these paths. Since bracket notation is more general than dot notation, it is used to construct Normalized Paths.  Single quotes are used to delimit string member names.  This reduces the number of characters that need escaping when Normalized Paths appear as strings (which are delimited with double quotes) in JSON texts. </del>  Certain characters are escaped, in one and only one way; all other characters are unescaped. <del> Normalized Paths are Singular Paths.  Not all Singular Paths are Normalized Paths: "$[-3]", for example, is a Singular Path, but not a Normalized Path.  The Normalized Path equivalent to "$[-3]" would have an index equal to the array length minus "3".  (The array length must be at least "3" if "$[-3]" is to identify a node.) </del>  Since there can only be one Normalized Path identifying a given node, the syntax stipulates which characters are escaped and which are not. So the definition of "normal-hexchar" is designed for hex escaping of characters which are not straightforwardly-printable, for example <del> U+000B LINE TABULATION, but for which no standard JSON escape such as "n" is available. </del>  3.8.1.

Reviewer comments:
I welcome this ... thanks.
From the side line: Do we need to add description of behavior (with a qualifier) to motivate the truly welcome attributes of the ?
A Normalized Path is just a particular kind of JSONPath query. Its only behaviour is to identify a node within the tree of nodes in a value. Or did you have some other behaviour in mind?
Oh, of course, but that formulation had never occurred to me, and it's useful. If it's not in the spec, it should be.
I meant the first of the two sentences: Here we describe the behavior of an implementation (output as response to an unspecified request that triggers the former). I just wonder if this section is a good place to describe a part of a protocol, when the topics are a) the "projection" itself and b) potential benefits (all from a data perspective).
Well, we describe the nature of what it is to implement JSONPath. Generally, in a protocol, you not only need to prescribe what is on the wire, but also what it means. That is only ever in the implementation. That doesn't mean that it describes the behavior of an implementation. E.g., in TCP, the byte stream that is transported by the protocol only ever happens in the implementation. Nothing on the wire reflects this byte stream. But describing that byte stream as the underlying model of TCP is rightly not criticized as "describing the behavior of an implementation".
The penny has just dropped: you are questioning the need for such a description rather than asking for more of the same! I agree with NAME response.
I think an important aspect that this is missing is that normalized paths are contexted to the JSON data that was queried; whereas singular paths exist independently, as does any other path. For example, the path (used in the text) is singular and can rightfully exist on its own. However it can't be normalized without querying JSON data. Once queried, the resulting normalized paths can be different based on the data. yields a normalized path of for the value yields a normalized path of for the value .
This text isn't getting into implementation behavior at all. It's specifying output and allowing for options.
Well, unforced ambiguous behavior then. Specifying output and allowing for (unrequested) options. For instance when the SomeTool processor outputs a number 42 and the options are that it represents any base in which the symbols are generally valid (per consensus) to me would rather raise questions than answer them. I would expect these complication (extra dimensions) less inside a format but more in a "processor" role or protocol description. The latter describing expected behavior within the dynamics of some interchange. I used the term without caution. Sorry for that. In my reading of the sentence we discuss about, the consumer of such a result has to look elsewhere to find out what the processor provides as result, right? That is our normal task as tool users. However, I think we better try to not bring in such ambiguities without noting the reason outside of our mandate to change. Maybe note, that existing processors (or however we like to call these providers of jsonpath responses) display mixed behaviors (what you call options). Makes sense? If not, sorry for the noise.
Well, we do say: I wouldn't go so far to say that the Normalized Path is "contexted". You need the value to compute the Normalized Path from the query, but after that, it doesn't require context to apply it (well, they are meant to be applied to that value, but they are regular JSONPath queries). With IETF 115 raging and Glyn being offline for a couple of days, we'll probably not respond very fast the next few days; I think good points are being made here even it is not always clear how to modify the text further to fully reflect them.
I believe the PR now makes this property of Normalized Paths clear. (I'd prefer not to labour the example.)
NAME I have attempted to address your concern by making the following general statement (suggested by NAME Normalized Paths. A nodelist is defined as follows (in the Terminology section): From this, it is clear that an implementation of JSONPath may output a nodelist as a JSON array of strings, where the strings are Normalized Paths. So I have deleted the following statements, which seemed to be causing confusion: Normalized Paths instead of, or in addition to, the values identified by these paths. For example, the JSONPath expression could select two values and an implementation could output the Normalized Paths and . (I'm not sure whether this will be acceptable to the other reviewers, so I'm going to leave the PR open until they have had a chance to review the latest version.)
Normalizing paths? What does that mean? There is no concept of "normalizing" arbitrary paths, it's pointless, there is no suggestion of that in Goessner's original article, or anywhere else that I'm aware of.
NAME Not sure if you've seen the final form of this PR, but I'm going to merge it to close off the discussion threads. We can adjust the section later if necessary.
URL begs the question of whether nodelists should have a normalized form. This would improve the interoperation, predictability, etc. of JSONPath implementations that output nodelists. Without this, JSONPath implementations which output nodelists would likely choose multiple different ways of representing nodelists. The proposal is for a Normalized Nodelist to consist of a possibly empty, whitespace separated list of Normalized Paths as in the following ABNF: Note: this proposal does not provide a normalized form for output from JSONPath implementations that output both nodelists and values.
good approach ... I would prefer a comma separated list, being able to be consumed as a JSON array without further modification ...
ohh ... and the URL as JSON strings, i.e.
I don't think we want to do this. This is not a JSONPath query, but a structure built from that. I'd like to leave structure building to JSON entirely. We are not defining the syntax of JSON, and we should avoid falling into the restatement antipattern trap. So yes, a nodelist might look like , but not because we say so, but because that is JSON syntax. We would simply say nodelists are canonically represented as JSON arrays of strings, where the strings are normatlizedpaths.
yes ... that's even better and pragmatical.
Why do they exist? The spec says nothing on the subject. If we don't have something convincing to say, why not remove them? I know we discussed this before, but as I was reading this with fresh eyes I was thinking "There's a lot of stuff here but why bother?"
The normalized path was to be used in the output. I don't think there was any other use for them. We wanted to ensure that the output was consistent (primarily for testing/comparison purposes), so we devised the "normalized path" to ensure that paths were output in a known format. After the refactor, it basically just means that the path doesn't use the shorthand notations; all of the segments are bracketed.
The following sentence in the Normalized Paths section provides some motivation: but maybe we need to expand it along the lines of NAME comment above.
Yes, that's my recollection. Yes, Normalized Paths use only bracket notation, but bracket notation can also produce paths which are not Normalized, such as and .
I repeat my basic question: What are these things for and what benefit do they offer, and to whom? I'm not sure what "used in the output" even means. It seems to me that more motivation is needed. I'd also be OK with just removing the whole section.
Here goes... A Normalized Path plays the same role as a JSON Pointer in situations where JSONPath syntax is required instead of JSON Pointer. A Normalized Path identifies a node in a given JSON value. Given a JSONPath expression which identifies a particular node in a given JSON value, there is a unique Normalized Path which identifies the same node in the given JSON value. Software (applications, libraries, JSONPath implementations, etc.) which outputs Singular Paths identifying nodes in a JSON value can output the equivalent Normalized Paths instead. A benefit of doing this is that the behaviour of the software is then more predictable and more easily tested (because the tests need to accommodate fewer possibilities). If there are multiple implementations of the software, sharing a single test suite is made more tractable. Who does this benefit? Human or programmatic users of the software observe more predictable behaviour. People writing tests have less work to do. Sharing a test suite avoids people duplicating effort.
Normalized paths are introduced in Stefan Goessners's , and are implemented in the two most important implementations, Goessner JavaScript JSONPath, and . I assume Stefan Goessner can speak to the original motivation, and if you want to know how they are used in practice, I suggest surveying users, perhaps starting on the Jayway site. Among other uses, they are helpful for diagnostics, for discovering what a perhaps non-obvious query resolves to in terms of the individual nodes selected. They have other uses for selecting specific nodes given a much larger query.
I think the spec needs a statement with a MUST/SHOULD/MAY about supporting these things and a clear suggestion as to what useful purpose they're designed to serve. Otherwise I seriously suggest removing them because to be honest I can't think of a single scenario where I'd use them.
I think they're intended not to be written but consumed. I agree in that I doubt anyone would write out except maybe in the context of a stackoverflow question or something. They'd just use . The point of this, though, is to be able to declare a preferred syntax that implementations should use to identify a known location in a document. It's just saying that we prefer over . (One advantage of using the bracketed syntax for normalization is that any location in a document can be written in this syntax, whereas there are restrictions on the dot syntax.) Again, I think this is most apparent in output when the implementation is returning paths to locations instead of / along with the values.
Another consideration is the spec's definition of nodelist as the output of applying a query: The following statement in the Normalized Paths section: steps into implementation detail. In the rest of the spec we studiously avoid prescribing implementation details. One way to reconcile these would be to put some non-normative text near the start of the spec which talks about implementation options for nodelist. This could then include language such as "If a nodelist is represented as a list JSONPath expressions, these SHOULD be Normalized Paths.". (But would it make sense to use "SHOULD" in non-normative text??)
I don't think that's implementation detail. It's defining what the output may be. We can talk about this in another issue if it concerns you, though.
I would say it's a statement about the representation of the abstract nodelist. A list of Normalized Paths is a string representation. Other possible representations are lists of JSON values in string form, a programming language list of nodes, etc. The choice of representation is an implementation decision. Feel free to raise a separate issue if you'd like to change the current text.
Normalized Paths ... are a concrete string presentation of nodelists (JSON text). are already used in the spec within every example table (Result Paths). are meant as an additional / alternative output of a JSONPath query. enhance predictability and testing. might (will) be used as input for subsequent analysis / actions (removing of duplicates?). Think of piping in Unix. Especially with the last point standardizing them is essential.
Could we include a bit of Stefan's argument somewhere in the introduction to the section?
Done - see URL
Definitely the right direction. Thank you!

Revised text:
3.8.  <ins> A Normalized Path is a canonical representation of the identity of a node in a value.  Specifically, a Normalized Path is a JSONPath query with restricted syntax (defined below), e.g., "$['book'][3]", which when applied to the value results in a nodelist consisting of just the node identified by the Normalized Path.  Note that a Normalized Path represents the identity of a node .  There is precisely one Normalized Path identifying any particular node in a value. A canonical representation of a nodelist is as a JSON arrays of strings, where the strings are Normalized Paths. Normalized Paths provide a predictable format that simplifies testing and post-processing of nodelists, e.g., to remove duplicate nodes. Normalized Paths are used in this document as result paths in examples. Normalized Paths use the canonical bracket notation, rather than dot notation. Single quotes are used to delimit string member names.  This reduces the number of characters that need escaping when Normalized Paths appear in double quote delimited strings, e.g., in JSON texts. </ins> Certain characters are escaped, in one and only one way; all other characters are unescaped.  <ins> Note: Normalized Paths are Singular Paths, but not all Singular Paths are Normalized Paths.  For example, "$[-3]" is a Singular Path, but is not a Normalized Path.  The Normalized Path equivalent to "$[-3]" would have an index equal to the array length minus "3".  (The array length must be at least "3" if "$[-3]" is to identify a node.) </ins> Since there can only be one Normalized Path identifying a given node, the syntax stipulates which characters are escaped and which are not. So the definition of "normal-hexchar" is designed for hex escaping of characters which are not straightforwardly-printable, for example  <ins> U+000B LINE TABULATION, but for which no standard JSON escape, such as "n", is available. </ins> 3.8.1.