JSON Merge Patch
draft-ietf-appsawg-json-merge-patch-07

[Ballot comment]
My previous DISCUSS asked for some textual description of the pseudocode. It turns out that the WG attempted that and was unable to come up with something clear enough to produce interoperable implementations. That's a bummer, but I am willing to take the WG's word that they tried.

I will only suggest adding some text after the pseudocode to assist folks in noticing some of the "interesting" aspects of the patch procedure:

  Note: This algorithm has some results that might not be immediately
  obvious to the implementer:

  - If the Patch is not itself an object, the Patch replaces the entire
    contents of the Target.

  - The Patch can only affect the entire value of a member of a Target
    object. In particular, a Patch cannot change members of an array;
    it can only replace or delete the entire array.

If the WG thinks there are other things worth mentioning, it might help the implementer. As I said previously, it did take me re-reading the pseudocode several times to truly understand the semantics, and if an implementer needs to structure their code differently than the pseudocode, it would be nice to point out some possibly tricky bits.

[Ballot comment]
One major note and a couple of minor notes:

(0) In line 7 of the pseudocode, s/Key/Name/

(1) Is there any concern about confusion due to the fact that patches are syntactically indistinguishable from JSON?  Presumably this is mitigated by the use of the media type, but it might be worth a mention, e.g., in the Security Considerations.

(2) Thanks for the note about the fact that this document assumes that an attribute being absent and an attribute being null are equivalent.  This might be worth reprising in the Security Considerations, in case there are usages of JSON that use this distinction to express security-relevant information.  For example, if presence of an element is used to signal support for a feature, but null is allowed as a value.

[Ballot discuss]
I am certainly willing to be talked out of this, but I am concerned about the implementability and would like to DISCUSS it a bit.

In section 2:

  To apply the merge patch document to a target resource, the system
  realizes the effect of the following function, described in
  pseudocode.  For this description, the function is called MergePatch,
  and it takes two arguments: the target resource document and the
  merge patch document.  The Target argument can be any JSON value, or
  undefined.  The Patch argument can be any JSON value.

It took me repeated reading of the pseudocode (and may I mention that I *hate* languages which rely on indentation ;-) ) to figure out that:

- If the Patch if not an object, the result *is* the Patch
- The Patch can't act on the internals of an array; it can only replace the whole thing
- The Patch cannot replace objects with new objects.

Can't we *please* have a textual description of this protocol in addition to a (recursive!) pseudocode function? I am not convinced that an implementer will get their implementation right just from the pseudocode.

[Ballot discuss]
The draft looks very good and the security considerations in RFC5789 cover most of the bases I would be concerned with.  I do have a question I'd like to discuss to see if it applies or not.

Normally, in other spaces patches are validated and that might be as simple as making sure the hash of the patch provided by the source matches the value you calculated (not corrupted, *should* be from the source you think it's from).  I don't see any mention of this practice, is there a reason for that or should it be added?  Maybe it's not possible because of how the patch is delivered over HTTP, but I figured it was worth flagging to discuss quickly.

IESG/Authors/WG Chairs:

IANA has reviewed draft-ietf-appsawg-json-merge-patch-06.  Authors should review the comments and/or questions below.  Please report any inaccuracies and respond to any questions as soon as possible.

IANA's reviewer has the following comments/questions:

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

In the Application Media Types registry located at:

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

a new application type is to be registered as follows:

application/merge-patch+json

with a reference of [ RFC-to-be ]

IANA understands that this is the only action required to be completed 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. This message is only to confirm what actions will be performed.

The following Last Call announcement was sent out:

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


The IESG has received a request from the Applications Area Working Group
WG (appsawg) to consider the following document:
- 'JSON Merge 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 2014-08-08. 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


  This specification defines the JSON merge patch format and processing
  rules.  The merge patch format is primarily intended for use with the
  HTTP PATCH method as a means of describing a set of modifications to
  a target resource's content.




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

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


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

1. Summary

Murray Kucherawy is the document shepherd.
Barry Leiba is the responsible Area Director.

From the Abstract:

  This specification defines the JSON merge patch format and processing
  rules.  The merge patch format is primarily intended for use with the
  HTTP PATCH method as a means of describing a set of modifications to
  a subset of the target resource's content.

2. Review and Consensus

The document was adopted in May, 2013, and had some active development
on the apps-discuss list.  The author then reached a point where he could
no longer support the work, and the document was parked for several
months while a new author was saught.  Recently Paul Hoffman stepped forward
to complete the work.

The quality and quantity of reviews have been good, and include comments
from the media types Designated Expert.  WGLC was completed in October, 2013,
resulting in further changes.  The result appears to have consensus of the
working group (though see "Other Points" below).

3. Intellectual Property

The authors both affirm that they are submitting the document in full
compliance with BCP 78 and 79, and know of no outstanding IPR claims.

4. Other Points

IANA Considerations contained the following note, which was removed
in version -04:

  NOTE: There were a few notes that the charset media type parameter
  is unacceptable for a +json media type.

I asked the media types Designated Expert for his opinion, and he replied:

  If I understand the issue correctly, it's that the application/json type
  goes out of its way NOT to define a charset parameter, requiring instead
  that compliant implementation be able to distinguish and handle utf-8,
  utf-16, or utf-32, whereas this media type does define one.

  IMO the parameter is a bad idea since it duplicates information that's
  provided by the type itself, and thus is at best harmless and at worst
  could create a silly state.

  That said, I don't really see this as a registration issue. The suffix
  registration for +json doesn't say "thou shalt not use charset parameters
  for this type"  - it probably should given the language in the
  application/json registration, but it doesn't. And as a reviewer I try to
  stick with enforcing the rules that are there, as opposed to imposing my
  own tastes on the matter.  So what I'd do is ask why the parameter is there
  and recommend removing it absent a good reason for having it.  But if that
  suggestion was rejected, I'd approve the type, albeit reluctantly.

  But this is a standards-track type in an RFC, which means that it's up to
  the IESG to review and approve the type, not me. And the IESG's powers
  are considerably broader. If I were on the IESG, I would insist on either
  the removal of the parameter or the inclusion of a compelling explanation
  for why it is there.

  And if that explanation included "this type uses charsets other than the
  three allowed by application/json" I'd then insist on the removal of the
  suffix since this is not, properly speaking JSON as presently defined.

1. Summary

Murray Kucherawy is the document shepherd.
Barry Leiba is the responsible Area Director.

From the Abstract:

  This specification defines the JSON merge patch format and processing
  rules.  The merge patch format is primarily intended for use with the
  HTTP PATCH method as a means of describing a set of modifications to
  a subset of the target resource's content.

2. Review and Consensus

The document was adopted in May, 2013, and had some active development
on the apps-discuss list.  The author then reached a point where he could
no longer support the work, and the document was parked for several
months while a new author was saught.  Recently Paul Hoffman stepped forward
to complete the work.

The quality and quantity of reviews have been good, and include comments
from the media types Designated Expert.  WGLC was completed in October, 2013,
resulting in further changes.  The result appears to have consensus of the
working group (though see "Other Points" below).

3. Intellectual Property

The authors both affirm that they are submitting the document in full
compliance with BCP 78 and 79, and know of no outstanding IPR claims.

4. Other Points

IANA Considerations contains the following note:

  NOTE: There were a few notes that the charset media type parameter
  is unacceptable for a +json media type.

I asked the media types Designated Expert for his opinion, and he replied:

  If I understand the issue correctly, it's that the application/json type
  goes out of its way NOT to define a charset parameter, requiring instead
  that compliant implementation be able to distinguish and handle utf-8,
  utf-16, or utf-32, whereas this media type does define one.

  IMO the parameter is a bad idea since it duplicates information that's
  provided by the type itself, and thus is at best harmless and at worst
  could create a silly state.

  That said, I don't really see this as a registration issue. The suffix
  registration for +json doesn't say "thou shalt not use charset parameters
  for this type"  - it probably should given the language in the
  application/json registration, but it doesn't. And as a reviewer I try to
  stick with enforcing the rules that are there, as opposed to imposing my
  own tastes on the matter.  So what I'd do is ask why the parameter is there
  and recommend removing it absent a good reason for having it.  But if that
  suggestion was rejected, I'd approve the type, albeit reluctantly.

  But this is a standards-track type in an RFC, which means that it's up to
  the IESG to review and approve the type, not me. And the IESG's powers
  are considerably broader. If I were on the IESG, I would insist on either
  the removal of the parameter or the inclusion of a compelling explanation
  for why it is there.

  And if that explanation included "this type uses charsets other than the
  three allowed by application/json" I'd then insist on the removal of the
  suffix since this is not, properly speaking JSON as presently defined.

Author is unable to continue with the work due to a change in priorities.  No contact in over a month.  Parking until a new author/editor can be found.