Subject: [apps-discuss] I-D Action: draft-ietf-appsawg-json-patch-05.txt

From: [email-masked]
Date: Wed, 26 Sep 2012 20:37:03 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories.
 This draft is a work item of the Applications Area Working Group Working Group of the IETF.

	Title           : JSON Patch
	Author(s)       : Paul C. Bryan
                          Mark Nottingham
	Filename        : draft-ietf-appsawg-json-patch-05.txt
	Pages           : 15
	Date            : 2012-09-26

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.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-appsawg-json-patch

There's also a htmlized version available at:
http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-05

A diff from the previous version is available at:
http://www.ietf.org/rfcdiff?url2=draft-ietf-appsawg-json-patch-05

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 26 Sep 2012 23:40:42 -0400

FYI - this incorporates the discussions we've had to date (including "op"), and it also changes the language around error handling.

Feedback / corrections appreciated.

Regards,

On 26/09/2012, at 11:37 PM, [email-masked] wrote:

> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

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

---

From: "Paul C. Bryan" <[email-masked]>
Date: Thu, 27 Sep 2012 09:19:05 -0700

Looks great!

Paul

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 1 Oct 2012 15:22:08 +1000

RE: draft-ietf-appsawg-json-patch-05

Suggestion: replace the "add" and "replace" operations with "insert" and "put" operations that work without needing to know (ie be in sync with) the old state of the JSON doc being changed. New text:

  4.1. insert

    The "insert" operation adds a new value to an array. The operation
    object MUST include "path" and "value" members, and MAY include an
    "i" member. "path" holds a JSON pointer that identifies an array.
    "value" holds the value to add, which can be any JSON value.
    "i" holds a number that is rounded to the nearest integer to give
    the array index of the new value when inserted. If "i" is absent the
    value is appended to the array. Any items in the array at an index
    equal to or greater than "i" are moved to the next higher index to
    make room for the new value.

    It is an error if "i" (rounded to the nearest integer) is less than
    0 or greater than the length of the array.

    Example:
    Old:   {"n":[1,2,3]}
    Patch: [{"op":"insert", "path":"/n", "value":4},
            {"op":"insert", "path":"/n", "value":5, "i":5},
            {"op":"insert", "path":"/n", "value":1.5, "i":1}]
    New:   {"n":[1,1.5,2,3,4,5]}

  4.2. put

    The "put" operation puts a new value at the target location,
    replacing any existing value if there is one. The operation object
    MUST include "path" and "value" members. "path" holds a JSON pointer
    that identifies the target location, which can be an object member
    (that is or isn't present), an array index (that must exist), or
    the whole target. "value" holds the value to add, which can be any
    JSON value.

    Example:
    Old:   {"n":[1,2,3]}
    Patch: [{"op":"put", "path":"", "value":[true, {"a":1}]},
            {"op":"put", "path":"/0", "value":false},
            {"op":"put", "path":"/1/b", "value":2},
            {"op":"put", "path":"/1/a", "value":3}]
    New:   [false, {"a":3, "b":2}]

--
James Manger

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 1 Oct 2012 15:41:24 +1000

Suggestion: define a "tree" operation for grouping operations that apply to part of the JSON doc being changed. It avoids repeating a path prefix in lots of operations; it simplifies writing a patch that can be applied at different points; its easier to separate the patch for changing a value from where that value is in a larger JSO structure. New text:

  4.7. tree

    The "tree" operation applies other operations to a subset of
    the target. The operation object MUST include "path" and "ops"
    members. "path" holds a JSON pointer that identifies the value
    to which the other operations apply. "ops" holds an array of
    operation objects. JSON pointers within "ops" are relative
    to the value identified by "path".

    Example:
    Old:   {"a":{"b":{"c":{"d":{"e":{"name":"Alice"}}}}}}
    Patch: [{"op":"tree", "path":"/a/b/c/d/e", "ops":[
              {"op":"add", "path":"/age", "value":20},
              {"op":"add", "path":"/email", "value":"[email-masked]"}]}]
    New:   {"a":{"b":{"c":{"d":{"e":{
            "name":"Alice", "age":20, "email":"[email-masked]"}}}}}}

--
James Manger