Subject: [ietf-types] Request for review: application/json-patch

From: "Paul C. Bryan" <[email-masked]>
Date: Mon, 24 Oct 2011 14:02:23 -0700

I'm preparing for possibly taking an informational Internet-Draft [1]
toward a proposed standard. I'm requesting review and feedback on the
"application/json-patch" media type. To wit:

-----

The Internet media type for a JSON Patch document is application/
json-patch.

Type name:  application

Subtype name:  json-patch

Required parameters:  none

Optional parameters:   none

Encoding considerations:
   Per JSON [RFC4627]: 8bit if UTF-8; binary if UTF-16 or UTF-32.

Security considerations:
   See Security Considerations in section 8.

Interoperability considerations:  N/A

Published specification:
   draft-pbryan-json-patch-02

Applications that use this media type:
   HTTP clients and servers.

Additional information:

   Magic number(s):  N/A

   File extension(s):  .json-patch

   Macintosh file type code(s):  TEXT

Person & email address to contact for further information:
   Paul C. Bryan <[email-masked]>

Intended usage:  COMMON

Restrictions on usage:  none

Author:  Paul C. Bryan <[email-masked]>

Change controller:  Paul C. Bryan <[email-masked]>

-----

Thank you for your consideration.

Paul C. Bryan
[email-masked]

[1] http://www.ietf.org/id/draft-pbryan-json-patch-02.txt

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Mon, 24 Oct 2011 23:11:59 +0200

>The Internet media type for a JSON Patch document is application/

What is your reasoning behind not using the "+json" convention?

>   Per JSON [RFC4627]: 8bit if UTF-8; binary if UTF-16 or UTF-32.

Either say something like "Same as for application/json." or "binary".
It would seem to me that RFC 4627 is mistaken in using "8bit" as that
is "The content of the media type consists solely of CRLF-delimited
8bit text." but JSON does not require CRLF.

>   HTTP clients and servers.

Well. Revision control systems for instance might use it.

>Change controller:  Paul C. Bryan <[email-masked]>

This would have to be some standards organization like "The IETF."
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: "Paul C. Bryan" <[email-masked]>
Date: Mon, 24 Oct 2011 14:24:21 -0700

> What is your reasoning behind not using the "+json" convention?

In a previous draft, it was "application/patch+json", but I was advised
that:

a) application/schema was possibly too basic a base type, and
b) there is no formalization around +json extension yet.

> 8bit text." but JSON does not require CRLF.

Okay, thanks.

> Well. Revision control systems for instance might use it.

True. Is there a way to just indicate general purpose usage instead of
trying to enumerate all the specific types of applications I could
imagine making use of this?

> This would have to be some standards organization like "The IETF."

Okay.

Thanks for the review.

Paul

---

From: "Paul C. Bryan" <[email-masked]>
Date: Mon, 24 Oct 2011 14:29:55 -0700

On Mon, 2011-10-24 at 14:24 -0700, Paul C. Bryan wrote:
> application/schema
And application/patch, even.

---

From: mike amundsen <[email-masked]>
Date: Mon, 24 Oct 2011 19:19:08 -0400

Paul:

checking the I-D document itself:

Sec #4 Operations:
"It is an error condition if an operation object contains more than
one operation member."

I am not clear on what this is telling me:
- the same JSON Pointer expression cannot appear more than once in a document
- something else?

possibly consider adding an example of a document that should be
rejected as it is malformed.

Sec #5 Error Handling
"In the event of an error condition, evaluation of the JSON Patch
document terminates and modification of the target document fails to
complete."

Does this mean the server should treat the document as an
"all-or-nothing" case? when an error occurs is the document left in a
"partial state" or left at the "initial state" before the request? is
this something you want to detail in the spec? if yes, you might want
to use RFC 2119 words here (MAY, SHOULD, MUST, etc.) .

It looks like your operations account for an error condition at the
individual "node" level:
"It is an error condition if the value to be replaced does not exist.", etc.

Are there error conditions that might occur at the "document" level
(or some other node above the target?

You do not indicate any use of 4xx codes here (i.e. mapping 4xx codes
to common error conditions in processing the patch); is this something
you want to include here or leave that up to the server to decide?

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

On Mon, Oct 24, 2011 at 17:02, Paul C. Bryan <[email-masked]> wrote:
> _______________________________________________
> ietf-types mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-types
>

---

From: "Paul C. Bryan" <[email-masked]>
Date: Mon, 24 Oct 2011 16:34:41 -0700

Hi Mike:

Thanks for the review and comments. My responses, inline...

> - the same JSON Pointer expression cannot appear more than once in a document

What I'm trying to say (evidently not very well yet!) is that you can't
have a operation object with "add" and "remove" at the same time. Only
one operation member per operation object.

> rejected as it is malformed.

Will do, thanks.

> to use RFC 2119 words here (MAY, SHOULD, MUST, etc.) .

HTTP PATCH is clear on the semantics, namely, "If the entire patch
document cannot be successfully applied, then the server MUST NOT apply
any of the changes." I've left this out of my spec, but I think there's
no good reason not to be clearer by saying application of a sequence of
patches SHOULD be atomic. Implementations are free to be even stricter
with a MUST of their own, as HTTP PATCH is. Thoughts?

> "It is an error condition if the value to be replaced does not exist.", etc.

Indeed.

> you want to include here or leave that up to the server to decide?

Since JSON Patch is not specific to HTTP, I'm content to defer to HTTP
PATCH and HTTP specifications, which amply document how to handle
situations such as when one attempts to apply an HTTP PATCH against a
resource that does not exist.

Thanks again!

Paul

---

From: mike amundsen <[email-masked]>
Date: Mon, 24 Oct 2011 21:01:51 -0400

responses inline....

> one operation member per operation object.

ok, so this is probably just a "vocabulary" detail. "operation",
"operation object", "operation member" maybe a glossary or just some
simple oneline definitions up front can help clear that up.

>> rejected as it is malformed.
cool.

> with a MUST of their own, as HTTP PATCH is. Thoughts?

yep, the PATCH semantics are clear on that and it's a good idea to
stick with them. I'd proly reference those semantics in the I-D then.
either in the error handling section or possibly in another area of
the I-D.

> resource that does not exist.

ok, i can see that. however, you've outline some error conditions in
your document. do you have any plans to indicate servers
[MUST|SHOULD|MAY] return the details of the errors encountered
("member to be added in the object already exists", "the specified
index is greater than the number of elements in the existing array",
etc.) and if yes, any suggestions on what the response would look
like? I'm not sure this is needed (maybe you want to leave all that to
implementors), but wanted to ask about it here.

Mike