Skip to main content

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

Revision differences

Document history

Date Rev. By Action
2014-10-13
07 (System) RFC Editor state changed to AUTH48-DONE from AUTH48
2014-10-06
07 (System) RFC Editor state changed to AUTH48 from RFC-EDITOR
2014-09-26
07 (System) RFC Editor state changed to RFC-EDITOR from EDIT
2014-08-28
07 Tero Kivinen Closed request for Last Call review by SECDIR with state 'No Response'
2014-08-28
07 (System) IANA Action state changed to RFC-Ed-Ack from Waiting on RFC Editor
2014-08-27
07 Barry Leiba Notification list changed to : appsawg-chairs@tools.ietf.org, draft-ietf-appsawg-json-merge-patch@tools.ietf.org
2014-08-27
07 Cindy Morgan IESG state changed to RFC Ed Queue from Approved-announcement sent
2014-08-27
07 (System) RFC Editor state changed to EDIT
2014-08-27
07 (System) Announcement was received by RFC Editor
2014-08-26
07 (System) IANA Action state changed to Waiting on RFC Editor from Waiting on Authors
2014-08-25
07 (System) IANA Action state changed to Waiting on Authors from In Progress
2014-08-25
07 (System) IANA Action state changed to In Progress
2014-08-25
07 Gunter Van de Velde Request for Telechat review by OPSDIR Completed. Reviewer: Benoit Claise.
2014-08-25
07 Gunter Van de Velde Request for Telechat review by OPSDIR is assigned to Benoit Claise
2014-08-25
07 Gunter Van de Velde Request for Telechat review by OPSDIR is assigned to Benoit Claise
2014-08-25
07 Cindy Morgan IESG state changed to Approved-announcement sent from Approved-announcement to be sent
2014-08-25
07 Cindy Morgan IESG has approved the document
2014-08-25
07 Cindy Morgan Closed "Approve" ballot
2014-08-25
07 Cindy Morgan Ballot approval text was generated
2014-08-21
07 Barry Leiba IESG state changed to Approved-announcement to be sent from Approved-announcement to be sent::Point Raised - writeup needed
2014-08-21
07 Paul Hoffman IANA Review state changed to Version Changed - Review Needed from IANA OK - Actions Needed
2014-08-21
07 Paul Hoffman New version available: draft-ietf-appsawg-json-merge-patch-07.txt
2014-08-21
06 Cindy Morgan IESG state changed to Approved-announcement to be sent::Point Raised - writeup needed from IESG Evaluation
2014-08-21
06 Pete Resnick
[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 …
[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.
2014-08-21
06 Pete Resnick [Ballot Position Update] Position for Pete Resnick has been changed to Yes from Discuss
2014-08-21
06 Kathleen Moriarty [Ballot comment]
Thanks for the discussion on checking the integrity of received patches, it was helpful.
2014-08-21
06 Kathleen Moriarty [Ballot Position Update] Position for Kathleen Moriarty has been changed to No Objection from Discuss
2014-08-21
06 Ted Lemon [Ballot Position Update] New position, No Objection, has been recorded for Ted Lemon
2014-08-20
06 Stephen Farrell [Ballot comment]

I didn't get why if Patch is not an object then
MergePatch(foo, Patch) returns Patch.
2014-08-20
06 Stephen Farrell [Ballot Position Update] New position, No Objection, has been recorded for Stephen Farrell
2014-08-20
06 Richard Barnes
[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 …
[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.
2014-08-20
06 Richard Barnes [Ballot Position Update] New position, No Objection, has been recorded for Richard Barnes
2014-08-20
06 Joel Jaeggli [Ballot Position Update] New position, No Objection, has been recorded for Joel Jaeggli
2014-08-20
06 Pete Resnick
[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 …
[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.
2014-08-20
06 Pete Resnick [Ballot Position Update] New position, Discuss, has been recorded for Pete Resnick
2014-08-20
06 Jari Arkko [Ballot Position Update] New position, No Objection, has been recorded for Jari Arkko
2014-08-18
06 Alia Atlas [Ballot Position Update] New position, No Objection, has been recorded for Alia Atlas
2014-08-18
06 Kathleen Moriarty
[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 …
[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.
2014-08-18
06 Kathleen Moriarty [Ballot Position Update] New position, Discuss, has been recorded for Kathleen Moriarty
2014-08-18
06 Adrian Farrel [Ballot Position Update] New position, No Objection, has been recorded for Adrian Farrel
2014-08-18
06 Alissa Cooper [Ballot Position Update] New position, No Objection, has been recorded for Alissa Cooper
2014-08-18
06 Spencer Dawkins [Ballot Position Update] New position, No Objection, has been recorded for Spencer Dawkins
2014-08-18
06 Brian Haberman [Ballot Position Update] New position, No Objection, has been recorded for Brian Haberman
2014-08-15
06 Martin Stiemerling [Ballot comment]
no objection from my side and my checks where solely related to any Transport layer related issues.
2014-08-15
06 Martin Stiemerling [Ballot Position Update] New position, No Objection, has been recorded for Martin Stiemerling
2014-08-12
06 Barry Leiba Changed consensus to Yes from Unknown
2014-08-08
06 Barry Leiba Ballot has been issued
2014-08-08
06 Barry Leiba [Ballot Position Update] New position, Yes, has been recorded for Barry Leiba
2014-08-08
06 Barry Leiba Created "Approve" ballot
2014-08-08
06 Barry Leiba IESG state changed to IESG Evaluation from Waiting for AD Go-Ahead
2014-08-08
06 Gunter Van de Velde Closed request for Last Call review by OPSDIR with state 'Withdrawn'
2014-08-08
06 Gunter Van de Velde Request for Last Call review by OPSDIR is assigned to Carlos Pignataro
2014-08-08
06 Gunter Van de Velde Request for Last Call review by OPSDIR is assigned to Carlos Pignataro
2014-08-08
06 (System) IESG state changed to Waiting for AD Go-Ahead from In Last Call
2014-08-05
06 Gunter Van de Velde Request for Last Call review by OPSDIR Completed: Ready. Reviewer: Bert Wijnen.
2014-08-01
06 Tero Kivinen Request for Last Call review by SECDIR is assigned to Alan DeKok
2014-08-01
06 Tero Kivinen Request for Last Call review by SECDIR is assigned to Alan DeKok
2014-07-31
06 Jean Mahoney Request for Last Call review by GENART is assigned to Joel Halpern
2014-07-31
06 Jean Mahoney Request for Last Call review by GENART is assigned to Joel Halpern
2014-07-31
06 (System) IANA Review state changed to IANA OK - Actions Needed from IANA - Review Needed
2014-07-31
06 Amanda Baber
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 …
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.
2014-07-30
06 Gunter Van de Velde Request for Last Call review by OPSDIR is assigned to Bert Wijnen
2014-07-30
06 Gunter Van de Velde Request for Last Call review by OPSDIR is assigned to Bert Wijnen
2014-07-26
06 Barry Leiba Placed on agenda for telechat - 2014-08-21
2014-07-25
06 Cindy Morgan IANA Review state changed to IANA - Review Needed
2014-07-25
06 Cindy Morgan
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 …
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.


2014-07-25
06 Cindy Morgan IESG state changed to In Last Call from Last Call Requested
2014-07-25
06 Barry Leiba Last call was requested
2014-07-25
06 Barry Leiba Last call announcement was generated
2014-07-25
06 Barry Leiba Ballot approval text was generated
2014-07-25
06 Barry Leiba IESG state changed to Last Call Requested from AD Evaluation::AD Followup
2014-07-23
06 Paul Hoffman New version available: draft-ietf-appsawg-json-merge-patch-06.txt
2014-07-23
05 Barry Leiba IESG state changed to AD Evaluation::AD Followup from AD Evaluation
2014-07-23
05 Barry Leiba
1. Summary

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

From the Abstract:

  This specification defines the JSON merge …
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.
2014-07-23
05 Barry Leiba Ballot writeup was changed
2014-07-21
05 Barry Leiba Ballot writeup was changed
2014-07-21
05 Barry Leiba Ballot writeup was generated
2014-07-21
05 Barry Leiba Notification list changed to : appsawg-chairs@tools.ietf.org, draft-ietf-appsawg-json-merge-patch@tools.ietf.org, apps-discuss@ietf.org
2014-07-21
05 Barry Leiba IESG state changed to AD Evaluation from Publication Requested
2014-07-21
05 Murray Kucherawy
1. Summary

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

From the Abstract:

  This specification defines the JSON merge …
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.
2014-07-21
05 Murray Kucherawy State Change Notice email list changed to appsawg-chairs@tools.ietf.org, draft-ietf-appsawg-json-merge-patch@tools.ietf.org
2014-07-21
05 Murray Kucherawy Responsible AD changed to Barry Leiba
2014-07-21
05 Murray Kucherawy IETF WG state changed to Submitted to IESG for Publication from Waiting for WG Chair Go-Ahead
2014-07-21
05 Murray Kucherawy IESG state changed to Publication Requested
2014-07-21
05 Murray Kucherawy IESG process started in state Publication Requested
2014-07-21
05 Murray Kucherawy Tag Revised I-D Needed - Issue raised by WG cleared.
2014-07-21
05 Paul Hoffman New version available: draft-ietf-appsawg-json-merge-patch-05.txt
2014-07-20
04 Murray Kucherawy Tag Revised I-D Needed - Issue raised by WG set.
2014-07-20
04 Murray Kucherawy Tag Revised I-D Needed - Issue raised by WG cleared.
2014-07-20
04 Murray Kucherawy IETF WG state changed to Waiting for WG Chair Go-Ahead from WG Document
2014-07-04
04 Paul Hoffman New version available: draft-ietf-appsawg-json-merge-patch-04.txt
2014-07-02
03 Murray Kucherawy Changed document writeup
2014-07-02
03 Murray Kucherawy Changed document writeup
2014-07-02
03 Murray Kucherawy Tag Revised I-D Needed - Issue raised by WG set.
2014-06-30
03 Murray Kucherawy Intended Status changed to Proposed Standard from None
2014-06-30
03 Murray Kucherawy Tag Author or Editor Needed cleared.
2014-06-30
03 Murray Kucherawy IETF WG state changed to WG Document from Parked WG Document
2014-06-30
03 Paul Hoffman New version available: draft-ietf-appsawg-json-merge-patch-03.txt
2014-03-02
02 Murray Kucherawy
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 …
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.
2014-03-02
02 Murray Kucherawy Tag Author or Editor Needed set.
2014-03-02
02 Murray Kucherawy IETF WG state changed to Parked WG Document from WG Document
2013-12-05
02 Murray Kucherawy IETF WG state changed to WG Document from Waiting for WG Chair Go-Ahead
2013-12-05
02 Murray Kucherawy Annotation tag Doc Shepherd Follow-up Underway cleared.
2013-11-18
02 James Snell New version available: draft-ietf-appsawg-json-merge-patch-02.txt
2013-10-06
01 Murray Kucherawy Only one review received during WGLC.
2013-10-06
01 Murray Kucherawy IETF WG state changed to Waiting for WG Chair Go-Ahead from In WG Last Call
2013-10-06
01 Murray Kucherawy Annotation tag Doc Shepherd Follow-up Underway set.
2013-09-17
01 Murray Kucherawy WGLC ends October 4, 2013.
2013-09-17
01 Murray Kucherawy IETF WG state changed to In WG Last Call from WG Document
2013-09-17
01 James Snell New version available: draft-ietf-appsawg-json-merge-patch-01.txt
2013-05-20
00 Murray Kucherawy Document shepherd changed to Murray Kucherawy
2013-05-20
00 Murray Kucherawy Document shepherd changed to (None)
2013-05-20
00 Murray Kucherawy Document shepherd changed to (None)
2013-05-20
00 Murray Kucherawy Document shepherd changed to (None)
2013-05-20
00 James Snell New version available: draft-ietf-appsawg-json-merge-patch-00.txt