Subject: [Gen-art] Gen-ART Telechat review of draft-ietf-appsawg-json-pointer-08.txt

From: Suresh Krishnan <[email-masked]>
Date: Tue, 8 Jan 2013 00:51:40 -0500

I have been selected as the General Area Review Team (Gen-ART)
reviewer for this draft (for background on Gen-ART, please see
http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html).

Please wait for direction from your document shepherd
or AD before posting a new version of the draft.

Document: draft-ietfdraft-ietf-appsawg-json-pointer-08.txt
Reviewer: Suresh Krishnan
Review Date: 2013/01/07
IESG Telechat date: 2013/01/10

Summary: This document is almost ready for publication as a Proposed
Standard. I do have a minor comment that you may wish to address and a
procedural point for the GEN AD to consider.

Minor
=====

* Section 4

The following two pieces of text seem contradictory to me. It is
possible that I am just misunderstanding something. If this is the case,
please let me know.

"If the currently referenced value is a JSON array, the reference token
MUST contain either:
...
*  exactly the single character "-", making the new referenced     value
the (non-existant) member after the last array element."

Which seems to indicate that the character "-" is valid for use and this
is followed by the following text at the end of the section

"  Note that the use of the "-" character to index an array will always
   result in such an error; applications of JSON Pointer thus need to
   specify how it is to be handled, if it is to be useful."

which seems to indicate that this is an error condition. Can you please
clarify?

Procedural
==========

* There is a downref to RFC4627 that has not been called out. I looked
up the shepherd writeup at

http://datatracker.ietf.org/wg/appsawg/management/shepherds/draft-ietf-appsawg-json-pointer/writeup/

and it curiously seems to be incomplete. Has there been an update to the
shepherd writeup since Feb 2012. The last one I know of is at

http://www.ietf.org/iesg/template/doc-writeup.html

Thanks
Suresh

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 7 Jan 2013 22:30:42 -0800

HI Suresh,

RFC4627 is already in the downref registry.  See
http://trac.tools.ietf.org/group/iesg/trac/wiki/DownrefRegistry.

The template used is a simplified one being tested by request of the IESG.

I'll let the editors comment on the first question.

-MSK

---

From: Barry Leiba <[email-masked]>
Date: Tue, 8 Jan 2013 08:46:20 -0500

Murray is exactly right.  And, for what it's worth, the App Area has
discussed moving 4627 to Standards Track.

The experimental shepherd writeup template is here:
http://trac.tools.ietf.org/group/iesg/trac/wiki/DraftShepherdWriteupWgAlternate
...and I encourage shepherds to talk with your ADs about trying it out.

On the other item, the point is that the "-" is syntactically correct and
has the semantics specified in the first excerpt.  But, as the second
excerpt says, it references a non-existant array element, and so creates an
"error" from the point of view of the JSON Pointer.

It is, therefore, up to the use of the Pointer to say what this means.
 Some future uses might proceed to handle it as an error condition.  JSON
Patch defines it as a valid situation for the "add" operation, but an error
for all other operations.

Barry

On Tuesday, January 8, 2013, Murray S. Kucherawy wrote:

> [email-masked] <javascript:_e({}, 'cvml',
> [email-masked]');>> wrote:
>

---

From: Barry Leiba <[email-masked]>
Date: Tue, 8 Jan 2013 09:17:37 -0500

Thinking further:

> the point is that the "-" is syntactically correct and
> It is, therefore, up to the use of the Pointer to say what this means.  Some
> future uses might proceed to handle it as an error condition.  JSON Patch
> defines it as a valid situation for the "add" operation, but an error for
> all other operations.

To be fair, I tripped over the same issue when I did my AD review,
then figured it out and didn't mention it in my review comments.  I do
think it could be clearer.

Perhaps something like this would make more sense (and also fixes the
"implementations... it" problem)?:

OLD
   Implementations will evaluate each reference token against the
   document's contents, and terminate evaluation with an error condition
   if it fails to resolve a concrete value for any of the JSON pointer's
   reference tokens.  For example, if an array is referenced with a non-
   numeric token, it will fail.  See Section 7 for details.

   Note that the use of the "-" character to index an array will always
   result in such an error; applications of JSON Pointer thus need to
   specify how it is to be handled, if it is to be useful.

NEW
   The implementations will evaluate each reference token against the
   document's contents, and will raise an error condition if it fails
   to resolve a concrete value for any of the JSON pointer's reference
   tokens.  For example, if an array is referenced with a non-numeric
   token, an error condition will be raised.  See Section 7 for details.

   Note that the use of the "-" character to index an array will always
   result in such an error condition because by definition it refers to a
   non-existent array element.  Applications of JSON Pointer thus
   need to specify how it is to be handled, if it is to be useful.

   Any error condition that does not have a specific action defined
   for it by the JSON Pointer application results in termination of
   evaluation.

END

Mark, what do you think?  Some wordsmithing, perhaps, but I think
something along this line will make the point clearer.

Barry

---

From: Suresh Krishnan <[email-masked]>
Date: Tue, 8 Jan 2013 16:16:07 -0500

Hi Murray,

> The template used is a simplified one being tested by request of the IESG.

Thanks for that info. I did locate the trial template.

Regards
Suresh

---

From: Suresh Krishnan <[email-masked]>
Date: Tue, 8 Jan 2013 16:18:02 -0500

Hi Barry,

> think it could be clearer.

Great.

> something along this line will make the point clearer.

The replacement text looks good. It does make things easier to
understand. Conside this a +1 on my side.

Thanks
Suresh

---

From: Russ Housley <[email-masked]>
Date: Wed, 9 Jan 2013 18:13:41 -0500

Barry:

Are you going to have to draft updated or use RFC Ed notes?

Russ

On Jan 8, 2013, at 4:18 PM, Suresh Krishnan wrote:

> _______________________________________________
> Gen-art mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/gen-art

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 14 Jan 2013 21:55:50 +1100

Works for me.

--
Mark Nottingham   http://www.mnot.net/