JavaScript Object Notation (JSON) Patch
draft-ietf-appsawg-json-patch-10

[Ballot comment]
The discussion of JSON parsers that hide duplicate elements in the example in A.13 raises a question.

What makes "last" special in this case? Why would we encourage the use of a parser that hid duplicate elements returning
the last value over one that always returned the first? Is there a normative requirement somewhere else you can point to that explains that choice?

(btw, why did RFC4627 only say "The names within an object SHOULD be unique."?)

[Ballot comment]
Section 4:

  Additionally, operation objects MUST have exactly one "path" member,
  whose value MUST be a string containing a [JSON-Pointer] value that
  references a location within the target document to perform the
  operation (the "target location").

First MUST is fine. On the second, are you saying "MUST be a string" or "MUST be a JSON-Pointer value" or "MUST reference a location within the target document" or some combination? And why not just "...whose value is a string..."? What is that MUST adding besides confusion? What might I think is a good idea to do that this MUST is reminding me I MUST NOT do?

  Members that are not
  explicitly defined for the operation in question MUST be ignored.

You mean, "The operation must complete as if the undefined member did not appear in the object."? Might be worth adding that. Also, as per Stephen's comment, you should probably mention explicitly, "other than op and path".

Section 4.3:

  The operation object MUST contain a "value" member
  that specifies the replacement value.

What else could it contain? How could I get this wrong? Or did you instead mean "The operation object MUST contain a "value" member, which specifies the replacement value."? (See also section 4.6.)

Section 4.5: Perhaps there should be more explanation or a more explicit back-pointer to the "add" section, assuming that this has the same "array insert/other object replace or add" behavior that "add" does.

[Ballot comment]
Is there going to be a time when you're going to want to test other ways like greater than or less than?  Wouldn't "equality" be better name instead of test?

[Ballot comment]
Just to make sure I'm following along...In A.1, "baz": "qux" is added before "foo": "bar" but in A.11  "baz": "qux" is added after "foo": "bar".  Shouldn't the two result in the same output with the only difference being in A.11 that the unrecognized bit is ignored?

Is there going to be a time when you're going to want to test other ways like greater than or less than?  Wouldn't "equality" be better name instead of test?

[Ballot comment]

- The abstract is a tiny bit misleading, since this is mostly
defining mechanisms and not the media type. I'd just move the
mention of the media type to the end of the abstract.

- Would it be useful to have an example of an HTTP PATCH method
invocation with this media type?

- Section 4: I'm not 100% clear on whether or not I MUST ignore
an unknown operation. You say that the value of the "op" member
MUST be one of those listed, but then you say members that are
not explicitly defined for the operation MUST be ignored. I
think you mean that an unknown op value is an error, but its
not quite crystal clear.

- 4.1: This bit isn't very clear to me: 'For example, "add"ing
to the path "/a/b" to this document:' Too many to's maybe.

- 4.1: This doesn't say there MUST be a value member, but 4.3
does. Maybe better to be consistent.

- 4.6: Just checking - is false==null in this context or not? Its
fine if that's clear enough already to JSON folks, but its not
clear to me. (I assume you want false!=null)

- A.2: Just checking - I guess its clear that array indices
start at 0? If not maybe good to say that, since its only here
that that becomes apparent, if you didn't already know.

- A.10: The value of value surprised me here, but makes sense I
guess. Would it be worth highlighting this in section 4 too?

- A.12: Thanks for that - I was wondering about it:-)

IANA has reviewed draft-ietf-appsawg-json-patch-08 and has the following Comments:

IANA understands that, upon approval of this document, there is a single IANA action which needs to be completed.

This document requests adding a single media type to the applications media type registry located at:

http://www.iana.org/assignments/media-types/application/index.html

The media type to be added is:

json-patch

IANA understands that the addition of the media type is the only action required of IANA upon approval of this document.

Note: The actions requested in this document will not be completed
until the document has been approved for publication as an RFC.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Subject: Last Call:  (JSON Patch) to Proposed Standard


The IESG has received a request from the Applications Area Working Group
WG (appsawg) to consider the following document:
- 'JSON Patch'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2012-12-25. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  JSON Patch defines the media type "application/json-patch", a JSON
  document structure for expressing a sequence of operations to apply
  to a JSON document, suitable for use with the HTTP PATCH method.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-appsawg-json-patch/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-appsawg-json-patch/ballot/


No IPR declarations have been submitted directly on this I-D.