You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@couchdb.apache.org by "Paul C. Bryan" <pa...@forgerock.com> on 2011/06/09 20:09:24 UTC
JSON Patch Internet Draft 01
The second draft of the JSON Patch proposal has been published:
http://tools.ietf.org/html/draft-pbryan-json-patch-01
Feedback would be most appreciated. The mailing list for this proposal
is:
https://groups.google.com/group/json-patch
Paul
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
Per JSON specification, emphasis mine:
“An object is an unordered collection of zero or more name/value pairs…”
Any ordering difference the xdelta approach would catch would therefore
be spurious.
Paul
On Fri, 2011-06-10 at 14:06 -0400, Dave Bender wrote:
> This may be a stupid question, but how does the RFC account for the order in
> which JSON map elements appear? Are these two JSON docs considered
> equivalent:
>
> A: {"a":1,"b":2}
>
> B: {"b":2,"a":1}
>
> The xdelta approach would catch a difference in ordering whereas the RFC
> version would not.
>
>
> On Fri, Jun 10, 2011 at 1:45 PM, Paul C. Bryan <pa...@forgerock.com>wrote:
>
> > On Thu, 2011-06-09 at 18:03 -0700, Jens Alfke wrote:
> >
> > > To play devil’s advocate: Is this format really necessary? From the
> > draft:
> > >
> > > > The HTTP PATCH [RFC5789] specification extends HTTP with a new
> > method
> > > > to perform partial modifications to resources. A JSON-based patch
> > > > document type is required to modify JSON documents using this
> > method.
> > >
> > > That’s not strictly true. A generic delta format such as xdelta3 or
> > zdelta can be used to patch any type of resource at all (and frequently is,
> > in apps like software updaters.)
> > >
> > > I can see that an advantage of JSON Patch is that, since it describes
> > structural changes rather than byte-level changes, it works even if the
> > physical representation of the JSON changes (i.e. modifications to
> > whitespace or Unicode character encoding.)
> >
> > As you point-out the challenge in using these generic formats is the
> > requirement of a byte-identical document representation. This implies
> > that the document either be stored in this serialized format, or there
> > is some normalization scheme that ensures that the document is always
> > formatted consistently before taking a patch.
> >
> >
> > > I’m just unsure whether that’s a significant enough advantage to outweigh
> > the drawbacks, including:
> >
> > I expect in some cases, it would not. In our application, we can't make
> > assumptions of the serialized expression of a JSON document, and hence
> > such a format is justifiable.
> >
> >
> > > - Much more verbose than xdelta3 or zdelta
> > > - More CPU-expensive to patch
> > > - Requires new software to generate and apply patches, rather than using
> > existing delta libraries
> > > - Has no error checking, so version mismatches could result in uncaught
> > document corruption
> >
> > Are HTTP conditions not sufficient to resolve this?
> >
> >
> > > —Jens
> >
> >
> >
Re: JSON Patch Internet Draft 01
Posted by Dave Bender <co...@gmail.com>.
This may be a stupid question, but how does the RFC account for the order in
which JSON map elements appear? Are these two JSON docs considered
equivalent:
A: {"a":1,"b":2}
B: {"b":2,"a":1}
The xdelta approach would catch a difference in ordering whereas the RFC
version would not.
On Fri, Jun 10, 2011 at 1:45 PM, Paul C. Bryan <pa...@forgerock.com>wrote:
> On Thu, 2011-06-09 at 18:03 -0700, Jens Alfke wrote:
>
> > To play devil’s advocate: Is this format really necessary? From the
> draft:
> >
> > > The HTTP PATCH [RFC5789] specification extends HTTP with a new
> method
> > > to perform partial modifications to resources. A JSON-based patch
> > > document type is required to modify JSON documents using this
> method.
> >
> > That’s not strictly true. A generic delta format such as xdelta3 or
> zdelta can be used to patch any type of resource at all (and frequently is,
> in apps like software updaters.)
> >
> > I can see that an advantage of JSON Patch is that, since it describes
> structural changes rather than byte-level changes, it works even if the
> physical representation of the JSON changes (i.e. modifications to
> whitespace or Unicode character encoding.)
>
> As you point-out the challenge in using these generic formats is the
> requirement of a byte-identical document representation. This implies
> that the document either be stored in this serialized format, or there
> is some normalization scheme that ensures that the document is always
> formatted consistently before taking a patch.
>
>
> > I’m just unsure whether that’s a significant enough advantage to outweigh
> the drawbacks, including:
>
> I expect in some cases, it would not. In our application, we can't make
> assumptions of the serialized expression of a JSON document, and hence
> such a format is justifiable.
>
>
> > - Much more verbose than xdelta3 or zdelta
> > - More CPU-expensive to patch
> > - Requires new software to generate and apply patches, rather than using
> existing delta libraries
> > - Has no error checking, so version mismatches could result in uncaught
> document corruption
>
> Are HTTP conditions not sufficient to resolve this?
>
>
> > —Jens
>
>
>
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
On Thu, 2011-06-09 at 18:03 -0700, Jens Alfke wrote:
> To play devil’s advocate: Is this format really necessary? From the draft:
>
> > The HTTP PATCH [RFC5789] specification extends HTTP with a new method
> > to perform partial modifications to resources. A JSON-based patch
> > document type is required to modify JSON documents using this method.
>
> That’s not strictly true. A generic delta format such as xdelta3 or zdelta can be used to patch any type of resource at all (and frequently is, in apps like software updaters.)
>
> I can see that an advantage of JSON Patch is that, since it describes structural changes rather than byte-level changes, it works even if the physical representation of the JSON changes (i.e. modifications to whitespace or Unicode character encoding.)
As you point-out the challenge in using these generic formats is the
requirement of a byte-identical document representation. This implies
that the document either be stored in this serialized format, or there
is some normalization scheme that ensures that the document is always
formatted consistently before taking a patch.
> I’m just unsure whether that’s a significant enough advantage to outweigh the drawbacks, including:
I expect in some cases, it would not. In our application, we can't make
assumptions of the serialized expression of a JSON document, and hence
such a format is justifiable.
> - Much more verbose than xdelta3 or zdelta
> - More CPU-expensive to patch
> - Requires new software to generate and apply patches, rather than using existing delta libraries
> - Has no error checking, so version mismatches could result in uncaught document corruption
Are HTTP conditions not sufficient to resolve this?
> —Jens
Re: JSON Patch Internet Draft 01
Posted by Jens Alfke <je...@mooseyard.com>.
To play devil’s advocate: Is this format really necessary? From the draft:
> The HTTP PATCH [RFC5789] specification extends HTTP with a new method
> to perform partial modifications to resources. A JSON-based patch
> document type is required to modify JSON documents using this method.
That’s not strictly true. A generic delta format such as xdelta3 or zdelta can be used to patch any type of resource at all (and frequently is, in apps like software updaters.)
I can see that an advantage of JSON Patch is that, since it describes structural changes rather than byte-level changes, it works even if the physical representation of the JSON changes (i.e. modifications to whitespace or Unicode character encoding.)
I’m just unsure whether that’s a significant enough advantage to outweigh the drawbacks, including:
- Much more verbose than xdelta3 or zdelta
- More CPU-expensive to patch
- Requires new software to generate and apply patches, rather than using existing delta libraries
- Has no error checking, so version mismatches could result in uncaught document corruption
—Jens
Re: JSON Patch Internet Draft 01
Posted by Brian Mitchell <bi...@gmail.com>.
On 2011-06-09, at 15:47 , Daniel Itaboraí wrote:
> This is great stuff!
>
> It would be nice to have some more operations like "increment", "decrement",
> "push", "pop", "compare-and-swap", etc. I think error handling should be
> better addressed, possibly returning an array of "result" objects (or
> something similar).
>
> Also, I don´t think one should mention idempotency of patches, since they
> seem to me inherently state dependent.
>
> regards,
> Daniel
This sort of update seems to be better implemented with update handlers. Even simple cases like decrement can create lots of cases. What to do at 0? Do we support decrement other than one? Do we support decrement of non-integral values? How about the case where the value isn't a number or doesn't exist? All of these cases are easily taken care of by update handlers. We can even write an update handler that calls other update handlers thanks to code-sharing via common-js modules. Now there is debate as to how easy it is to write some of those and if CouchDB should make some of it easier but it's a start on the single document level. (Also, bulk update calls would be interesting but that's another thread.)
Now what I see PATCH being useful for is efficiency. It not only allows you to avoid large repetition in payload but could also have slightly better concurrency since one could check the current revision against the request's revision for just the given patches. One could approximate this with an update handler though this might have elegance since it could work out of the box if the specification of JSON PATCH is carefully crafted and implemented. For now it's just interesting though since I think we'll get more milage from update handler improvements. Maybe the future will include PATCH support, maybe not.
Brian.
Re: JSON Patch Internet Draft 01
Posted by Daniel Itaboraí <it...@gmail.com>.
This is great stuff!
It would be nice to have some more operations like "increment", "decrement",
"push", "pop", "compare-and-swap", etc. I think error handling should be
better addressed, possibly returning an array of "result" objects (or
something similar).
Also, I don´t think one should mention idempotency of patches, since they
seem to me inherently state dependent.
regards,
Daniel
On Thu, Jun 9, 2011 at 3:38 PM, Paul Davis <pa...@gmail.com>wrote:
> On Thu, Jun 9, 2011 at 2:09 PM, Paul C. Bryan <pa...@forgerock.com>
> wrote:
> > The second draft of the JSON Patch proposal has been published:
> > http://tools.ietf.org/html/draft-pbryan-json-patch-01
> >
> > Feedback would be most appreciated. The mailing list for this proposal
> > is:
> > https://groups.google.com/group/json-patch
> >
> > Paul
> >
>
> Paul,
>
> Thanks for the update. There are a few details I'm still not quite sure on.
>
> In the JSON Pointer RFC it states that path components SHOULD be URI
> encoded and that "/" MUST BE uri encoded but in the algorithm
> description for moving the reference pointer there's no language on
> URI-decoding the path component. Also I have no idea how this would
> play with utf-8 or other unicode representations. Perhaps just
> escaping any "/' characters would be enough here though that could get
> confusing as it'd be "\\/" in all the examples.
>
> This note on array mutations "It is an error condition if the addition
> would result in sparse allocation of any array elements." might read
> better as something like "It is an error condition is greater than the
> length of the array."
>
> The language in section 6 worries me a bit on its possible
> interpretations. I'd either opt for "behavior after an error occurs is
> undefined" or the other end of the spectrum "if a JSON diff can not be
> applied without error then it must not have any side effects".
>
> The interaction between JSON patch and JSON pointer confuses me a bit.
> The JSON patch doesn't mention it, but its implicitly saying that it
> must parse the path and strip a token before the JSON pointer
> algorithm is applied. For instance, the first example:
>
> An example target JSON document:
>
> {
> "foo": "bar"
> }
>
> A JSON Patch document:
>
> [
> { "add": "/baz", "value": "qux" }
> ]
>
> The resulting JSON document:
>
> {
> "baz": "qux",
> "foo": "bar"
> }
>
> As I read JSON pointer, if I attempted to retrieve "/baz" from {"foo":
> "bar"} it would result in an error because "baz" does not exist in
> that JSON doc. So what JSON patch is saying is that i have to strip
> the final JSON pointer path component before retrieving that JSON
> pointer. I'm not sure if that's not a big deal, or if the JSON patch
> operations might be better suited with a third parameter that lists
> the final component so we minimize implementations of JSON pointer
> parsing?
>
> Other than that it all looks promising.
>
> HTH,
> Paul Davis
>
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
On Thu, 2011-06-09 at 21:23 -0600, Kris Zyp wrote:
> I believe UTF-8 encoding for URLs is already mandated by RFC 3986.
Just re-read the RFC, and yep, it's mandated.
Paul
Re: JSON Patch Internet Draft 01
Posted by Kris Zyp <kr...@gmail.com>.
On 6/9/2011 5:28 PM, Paul C. Bryan wrote:
> On Thu, 2011-06-09 at 17:56 -0400, Paul Davis wrote:
>> > In the JSON Pointer RFC it states that path components SHOULD be URI
>> > encoded and that "/" MUST BE uri encoded but in the algorithm
>> > description for moving the reference pointer there's no language on
>> > URI-decoding the path component. Also I have no idea how this would
>> > play with utf-8 or other unicode representations. Perhaps just
>> > escaping any "/' characters would be enough here though that could get
>> > confusing as it'd be "\\/" in all the examples.
>> >
>> > Okay, I think I'll write-up process for encoding and decoding so as to
>> > clarify. In a nutshell, to decode, break into tokens using "/" separator,
>> > then URL-decode each fragment. Make sense?
>>
>> My bigger concern is what to do about unicode in JSON strings though.
>> URI encoding is specified at the byte level where as JSON strings are
>> specified as a list of "any unicode character". Plus this is affected
>> by internal representation of unicode. The issue is to figure out how
>> to make the JSON diff not have to do tricky things that would need to
>> extend some major definitions of JSON.
>>
>> This is why I was toying with the idea of using an escaped solidus
>> character at the application level. By not converting characters we
>> neatly avoid the issue of how to transform various types of unicode
>> representations into other types of unicode representations in this
>> spec. The only downfall of this method is that at the transport layer
>> (ie, as JSON) the application level escape reads as "\\/" or "\\//".
>>
>> Another method (though unatractively verbose) would be to list the
>> path as an array of strings and or integers. Which would also nicely
>> disambiguate for cases like {"1": "some stuff"}. Also that brings up
>> an error scenario that might need to be spec'd.
>>
>> Paul Davis
>
> Ah, I see. A couple of possibilities come to mind (which I note may be
> combined):
>
> 1. We specify URL encoding is on UTF-8 encoding of the token.
I believe UTF-8 encoding for URLs is already mandated by RFC 3986.
Thanks,
Kris
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
On Thu, 2011-06-09 at 17:56 -0400, Paul Davis wrote:
> > In the JSON Pointer RFC it states that path components SHOULD be URI
> > encoded and that "/" MUST BE uri encoded but in the algorithm
> > description for moving the reference pointer there's no language on
> > URI-decoding the path component. Also I have no idea how this would
> > play with utf-8 or other unicode representations. Perhaps just
> > escaping any "/' characters would be enough here though that could get
> > confusing as it'd be "\\/" in all the examples.
> >
> > Okay, I think I'll write-up process for encoding and decoding so as to
> > clarify. In a nutshell, to decode, break into tokens using "/" separator,
> > then URL-decode each fragment. Make sense?
>
> My bigger concern is what to do about unicode in JSON strings though.
> URI encoding is specified at the byte level where as JSON strings are
> specified as a list of "any unicode character". Plus this is affected
> by internal representation of unicode. The issue is to figure out how
> to make the JSON diff not have to do tricky things that would need to
> extend some major definitions of JSON.
>
> This is why I was toying with the idea of using an escaped solidus
> character at the application level. By not converting characters we
> neatly avoid the issue of how to transform various types of unicode
> representations into other types of unicode representations in this
> spec. The only downfall of this method is that at the transport layer
> (ie, as JSON) the application level escape reads as "\\/" or "\\//".
>
> Another method (though unatractively verbose) would be to list the
> path as an array of strings and or integers. Which would also nicely
> disambiguate for cases like {"1": "some stuff"}. Also that brings up
> an error scenario that might need to be spec'd.
>
> Paul Davis
Ah, I see. A couple of possibilities come to mind (which I note may be
combined):
1. We specify URL encoding is on UTF-8 encoding of the token.
2. We relax the URL encoding requirement in JSON Pointer (where it is
not used in the fragment) from SHOULD to MAY; encoding of "/" remains a
MUST.
I have to admit the unattractively verbose has its benefits as you
point-out, but will be killer if we try to use it in a fragment—which
remains a strong goal of JSON Pointer.
Thoughts?
Paul
Re: JSON Patch Internet Draft 01
Posted by Paul Davis <pa...@gmail.com>.
> In the JSON Pointer RFC it states that path components SHOULD be URI
> encoded and that "/" MUST BE uri encoded but in the algorithm
> description for moving the reference pointer there's no language on
> URI-decoding the path component. Also I have no idea how this would
> play with utf-8 or other unicode representations. Perhaps just
> escaping any "/' characters would be enough here though that could get
> confusing as it'd be "\\/" in all the examples.
>
> Okay, I think I'll write-up process for encoding and decoding so as to
> clarify. In a nutshell, to decode, break into tokens using "/" separator,
> then URL-decode each fragment. Make sense?
My bigger concern is what to do about unicode in JSON strings though.
URI encoding is specified at the byte level where as JSON strings are
specified as a list of "any unicode character". Plus this is affected
by internal representation of unicode. The issue is to figure out how
to make the JSON diff not have to do tricky things that would need to
extend some major definitions of JSON.
This is why I was toying with the idea of using an escaped solidus
character at the application level. By not converting characters we
neatly avoid the issue of how to transform various types of unicode
representations into other types of unicode representations in this
spec. The only downfall of this method is that at the transport layer
(ie, as JSON) the application level escape reads as "\\/" or "\\//".
Another method (though unatractively verbose) would be to list the
path as an array of strings and or integers. Which would also nicely
disambiguate for cases like {"1": "some stuff"}. Also that brings up
an error scenario that might need to be spec'd.
Paul Davis
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
Hi Paul:
Thanks for your feedback. My comments inline:
On Thu, 2011-06-09 at 14:38 -0400, Paul Davis wrote:
> In the JSON Pointer RFC it states that path components SHOULD be URI
> encoded and that "/" MUST BE uri encoded but in the algorithm
> description for moving the reference pointer there's no language on
> URI-decoding the path component. Also I have no idea how this would
> play with utf-8 or other unicode representations. Perhaps just
> escaping any "/' characters would be enough here though that could get
> confusing as it'd be "\\/" in all the examples.
Okay, I think I'll write-up process for encoding and decoding so as to
clarify. In a nutshell, to decode, break into tokens using "/"
separator, then URL-decode each fragment. Make sense?
> This note on array mutations "It is an error condition if the addition
> would result in sparse allocation of any array elements." might read
> better as something like "It is an error condition is greater than the
> length of the array."
Okay.
> The language in section 6 worries me a bit on its possible
> interpretations. I'd either opt for "behavior after an error occurs is
> undefined" or the other end of the spectrum "if a JSON diff can not be
> applied without error then it must not have any side effects".
Agreed. I should have stated the latter. Will incorporate into the next
draft.
> The interaction between JSON patch and JSON pointer confuses me a bit.
> The JSON patch doesn't mention it, but its implicitly saying that it
> must parse the path and strip a token before the JSON pointer
> algorithm is applied. For instance, the first example:
>
> An example target JSON document:
>
> {
> "foo": "bar"
> }
>
> A JSON Patch document:
>
> [
> { "add": "/baz", "value": "qux" }
> ]
>
> The resulting JSON document:
>
> {
> "baz": "qux",
> "foo": "bar"
> }
>
> As I read JSON pointer, if I attempted to retrieve "/baz" from {"foo":
> "bar"} it would result in an error because "baz" does not exist in
> that JSON doc. So what JSON patch is saying is that i have to strip
> the final JSON pointer path component before retrieving that JSON
> pointer. I'm not sure if that's not a big deal, or if the JSON patch
> operations might be better suited with a third parameter that lists
> the final component so we minimize implementations of JSON pointer
> parsing?
So, draft 00 contained an "element" property, which named the object
property or array element to add, allowing the path to reference the
parent—which would have worked with JSON Pointer. More than one person
suggested that this is too verbose and would ideally be in the pointer
itself, but—as you have noted—that spec causes "/baz" to be an error
condition according to JSON Pointer, which in this case is clearly not
the intent.
We could solve this in JSON Patch or JSON Pointer. I'm inclined to fix
JSON Pointer somehow to allow for this, as I expect JSON Patch will not
be the only example of a use where you're naming a new node to be
created. Any thoughts?
Again, thanks for the great feedback.
Paul
Re: JSON Patch Internet Draft 01
Posted by Patrick Barnes <mr...@gmail.com>.
On path components, I wonder why an inline delimiter was chosen?
Would it be sensible to use an array instead?
Document:
{
"a": {
"a1":"foo",
"a2":"foo2"
},
"b": "notappearinginthisfilm"
"c": [0,1,2,4,5]
}
Patch:
[
{ "replace": ["a","a2"], "value":"bar2" },
{ "remove": ["b"] },
{ "add": ["c", 3], "value":3 }
]
This way, there is no need to discuss string encoding or escape delimiters.
-Patrick
On 10/06/2011 4:38 AM, Paul Davis wrote:
> On Thu, Jun 9, 2011 at 2:09 PM, Paul C. Bryan<pa...@forgerock.com> wrote:
>> The second draft of the JSON Patch proposal has been published:
>> http://tools.ietf.org/html/draft-pbryan-json-patch-01
>>
>> Feedback would be most appreciated. The mailing list for this proposal
>> is:
>> https://groups.google.com/group/json-patch
>>
>> Paul
>>
>
> Paul,
>
> Thanks for the update. There are a few details I'm still not quite sure on.
>
> In the JSON Pointer RFC it states that path components SHOULD be URI
> encoded and that "/" MUST BE uri encoded but in the algorithm
> description for moving the reference pointer there's no language on
> URI-decoding the path component. Also I have no idea how this would
> play with utf-8 or other unicode representations. Perhaps just
> escaping any "/' characters would be enough here though that could get
> confusing as it'd be "\\/" in all the examples.
>
> This note on array mutations "It is an error condition if the addition
> would result in sparse allocation of any array elements." might read
> better as something like "It is an error condition is greater than the
> length of the array."
>
> The language in section 6 worries me a bit on its possible
> interpretations. I'd either opt for "behavior after an error occurs is
> undefined" or the other end of the spectrum "if a JSON diff can not be
> applied without error then it must not have any side effects".
>
> The interaction between JSON patch and JSON pointer confuses me a bit.
> The JSON patch doesn't mention it, but its implicitly saying that it
> must parse the path and strip a token before the JSON pointer
> algorithm is applied. For instance, the first example:
>
> An example target JSON document:
>
> {
> "foo": "bar"
> }
>
> A JSON Patch document:
>
> [
> { "add": "/baz", "value": "qux" }
> ]
>
> The resulting JSON document:
>
> {
> "baz": "qux",
> "foo": "bar"
> }
>
> As I read JSON pointer, if I attempted to retrieve "/baz" from {"foo":
> "bar"} it would result in an error because "baz" does not exist in
> that JSON doc. So what JSON patch is saying is that i have to strip
> the final JSON pointer path component before retrieving that JSON
> pointer. I'm not sure if that's not a big deal, or if the JSON patch
> operations might be better suited with a third parameter that lists
> the final component so we minimize implementations of JSON pointer
> parsing?
>
> Other than that it all looks promising.
>
> HTH,
> Paul Davis
>
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
On Fri, 2011-06-10 at 11:42 -0700, Eli Stevens (Gmail) wrote:
> Is it possible to use those outside of the context of an HTTP request?
Definitely, but then concurrency control would be something that the
alternate implementation would be required to provide. In our
application, we use a "rev" (similar to CouchDB) parameter in our
resource-oriented API, which provides equivalent functionality—something
we need for our update operations as well as patch.
Paul
Re: JSON Patch Internet Draft 01
Posted by "Eli Stevens (Gmail)" <wi...@gmail.com>.
On Fri, Jun 10, 2011 at 10:20 AM, Paul C. Bryan
<pa...@forgerock.com> wrote:
> I am inclined to leverage HTTP conditions (e.g. If-Match) to ensure
> resource state rather than try to build additional tests and concurrency
> mechanisms into the patch format.
Is it possible to use those outside of the context of an HTTP request?
Eli
Re: JSON Patch Internet Draft 01
Posted by "Paul C. Bryan" <pa...@forgerock.com>.
On Thu, 2011-06-09 at 16:39 -0700, Eli Stevens (Gmail) wrote:
[snip]
> I think that it should be possible to specify what value should be
> present when removing something. Text-based patches don't just say
> "remove line 42" they also spell out what content is expected to be
> there before removal. Similarly, I think that supporting context
> verification is important. Something like the following being applied
> to the resulting doc above:
I am inclined to leverage HTTP conditions (e.g. If-Match) to ensure
resource state rather than try to build additional tests and concurrency
mechanisms into the patch format.
[snip]
> For what it's worth, I don't think that using a list of strings for
> the pointer is bad at all. Why invent a new string sub-syntax when
> you can use an existing JSON structure? Having wasted more hours of
> my professional life lamenting trying to cram arbitrary user data into
> the path portion of a URL than I care to admit, I can't recommend the
> approach. Spelling the separator as "," instead of / isn't that big
> of a deal, esp. when for simple cases with a full JS interpreter
> handy, one could use "/a/b/c".split("/").
There is a clear need for a scheme to identify a JSON node within a URI
fragment—this is what JSON Schema uses; I would rather leverage that
scheme than deviate from it and invent yet another for JSON Patch.
Paul
Re: JSON Patch Internet Draft 01
Posted by "Eli Stevens (Gmail)" <wi...@gmail.com>.
On Thu, Jun 9, 2011 at 11:38 AM, Paul Davis <pa...@gmail.com> wrote:
> On Thu, Jun 9, 2011 at 2:09 PM, Paul C. Bryan <pa...@forgerock.com> wrote:
>> The second draft of the JSON Patch proposal has been published:
>> http://tools.ietf.org/html/draft-pbryan-json-patch-01
>>
>> Feedback would be most appreciated. The mailing list for this proposal
>> is:
>> https://groups.google.com/group/json-patch
...
> An example target JSON document:
>
> {
> "foo": "bar"
> }
>
> A JSON Patch document:
>
> [
> { "add": "/baz", "value": "qux" }
> ]
>
> The resulting JSON document:
>
> {
> "baz": "qux",
> "foo": "bar"
> }
I think that it should be possible to specify what value should be
present when removing something. Text-based patches don't just say
"remove line 42" they also spell out what content is expected to be
there before removal. Similarly, I think that supporting context
verification is important. Something like the following being applied
to the resulting doc above:
[
{ "verify": "/foo", "value": "bar" },
{ "replace": "/baz", "value": 42, "oldvalue": "qux" }
]
That might warrant a rename from "value" to "newvalue" but if
"oldvalue" is optional, maybe the asymmetry between the names isn't a
big deal.
For what it's worth, I don't think that using a list of strings for
the pointer is bad at all. Why invent a new string sub-syntax when
you can use an existing JSON structure? Having wasted more hours of
my professional life lamenting trying to cram arbitrary user data into
the path portion of a URL than I care to admit, I can't recommend the
approach. Spelling the separator as "," instead of / isn't that big
of a deal, esp. when for simple cases with a full JS interpreter
handy, one could use "/a/b/c".split("/").
Cheers,
Eli
Re: JSON Patch Internet Draft 01
Posted by Paul Davis <pa...@gmail.com>.
On Thu, Jun 9, 2011 at 2:09 PM, Paul C. Bryan <pa...@forgerock.com> wrote:
> The second draft of the JSON Patch proposal has been published:
> http://tools.ietf.org/html/draft-pbryan-json-patch-01
>
> Feedback would be most appreciated. The mailing list for this proposal
> is:
> https://groups.google.com/group/json-patch
>
> Paul
>
Paul,
Thanks for the update. There are a few details I'm still not quite sure on.
In the JSON Pointer RFC it states that path components SHOULD be URI
encoded and that "/" MUST BE uri encoded but in the algorithm
description for moving the reference pointer there's no language on
URI-decoding the path component. Also I have no idea how this would
play with utf-8 or other unicode representations. Perhaps just
escaping any "/' characters would be enough here though that could get
confusing as it'd be "\\/" in all the examples.
This note on array mutations "It is an error condition if the addition
would result in sparse allocation of any array elements." might read
better as something like "It is an error condition is greater than the
length of the array."
The language in section 6 worries me a bit on its possible
interpretations. I'd either opt for "behavior after an error occurs is
undefined" or the other end of the spectrum "if a JSON diff can not be
applied without error then it must not have any side effects".
The interaction between JSON patch and JSON pointer confuses me a bit.
The JSON patch doesn't mention it, but its implicitly saying that it
must parse the path and strip a token before the JSON pointer
algorithm is applied. For instance, the first example:
An example target JSON document:
{
"foo": "bar"
}
A JSON Patch document:
[
{ "add": "/baz", "value": "qux" }
]
The resulting JSON document:
{
"baz": "qux",
"foo": "bar"
}
As I read JSON pointer, if I attempted to retrieve "/baz" from {"foo":
"bar"} it would result in an error because "baz" does not exist in
that JSON doc. So what JSON patch is saying is that i have to strip
the final JSON pointer path component before retrieving that JSON
pointer. I'm not sure if that's not a big deal, or if the JSON patch
operations might be better suited with a third parameter that lists
the final component so we minimize implementations of JSON pointer
parsing?
Other than that it all looks promising.
HTH,
Paul Davis