Subject: [apps-discuss] JSON Patch name

From: Mark Nottingham <[email-masked]>
Date: Fri, 18 Jan 2013 18:24:11 +1100

It's becoming apparent that there are likely to be a few different flavours of JSON Patch out there, so it may make sense to give the one we're working on now a bit more of a distinctive name.

I'd suggest Simple JSON Patch, with the media type application/simple-json-patch.

I've talked to Murray and Barry about it, but wanted to make sure people here (especially those who might already be using it) a heads-up. Make sense? Any concerns?

Cheers,

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

---

From: "Martin J. Dürst" <[email-masked]>
Date: Fri, 18 Jan 2013 19:56:45 +0900

Shouldn't the name end in +json, because the patch data itself is JSON?

And couldn't the simple one just have a simple name (as simple as 
leaving out the "simple")? Others can then still invent their own names, 
there's no shortage of them.

Regards,   Martin.

On 2013/01/18 16:24, Mark Nottingham wrote:
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 18 Jan 2013 21:59:42 +1100

> Shouldn't the name end in +json, because the patch data itself is JSON?

The answer we've come to is that it isn't, because the important bit is that this is a patch format *for* JSON; the fact that it's encoded in JSON is (relatively) insignificant.

> And couldn't the simple one just have a simple name (as simple as leaving out the "simple")? Others can then still invent their own names, there's no shortage of them.

I think that's reasonable. To be clear -- I'm not pushing this *at all*; if we think the name is fine as-is, that's great by me (because a bunch of existing implementations won't feel the need to re-name).

If no one shouts and says "this needs a new name!", I'll leave it as-is; I just wanted to make sure we double-checked it before shipping.

Cheers,

---

From: Conal Tuohy <[email-masked]>
Date: Fri, 18 Jan 2013 22:36:08 +1000

On 18/01/13 20:59, Mark Nottingham wrote:
> On 18/01/2013, at 9:56 PM, "Martin J. Dürst"<[email-masked]>  wrote:
>
I agree with Martin, that the Internet Media Type name should end in 
"+json".

It's true that in an obvious sense the semantics of JSON Patch documents 
are more significant that their syntax, but I don't think that has any 
bearing on whether to use the "+json" suffix or not.

The point of the "+json" suffix is that a media type can declare that it 
follows JSON syntax, _independently_ of its particular semantics. The 
"+json" suffix is to allow generic JSON processors to recognise JSON 
documents of whatever sub-type, so as to perform generic processing at 
the JSON syntax level; syntax highlighting, XML conversion, etc.

If there's any value at all in a "+json" suffix, even if only for 
browsers to do JSON syntax highlighting, why not allow it? Is there any 
cost to having the suffix?

-- 
Conal Tuohy
HuNI <http://huni.net.au/> Technical Coordinator 
<http://apidictor.huni.net.au/trac/wiki/ConalSpace>
Victorian eResearch Strategic Initiative 
<http://versi.edu.au/about-us/versi-team#Con>
Skype: conal.tuohy
Twitter: @conal_tuohy <https://twitter.com/conal_tuohy>
Mobile: +61-466324297 <tel:+61-466324297>

---

From: Erik Wilde <[email-masked]>
Date: Fri, 18 Jan 2013 13:43:37 +0100

hello.

> bearing on whether to use the "+json" suffix or not.

+1, and fwiw, http://tools.ietf.org/html/draft-wilde-xml-patch-01 now 
has changed from application/xml-patch to application/xml-patch+xml, 
because according to 
http://tools.ietf.org/id/draft-ietf-appsawg-media-type-suffix-regs-08.txt, 
media types should use the suffix, unless there's a good reason not to.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Julian Reschke <[email-masked]>
Date: Fri, 18 Jan 2013 14:24:00 +0100

On 2013-01-18 13:36, Conal Tuohy wrote:
> ...

+1

---

From: Ben Longden <[email-masked]>
Date: Fri, 18 Jan 2013 13:24:06 +0000

> I'd suggest Simple JSON Patch, with the media type application/simple-json-patch.

I'm also in the +json camp…

application/simple-patch+json

or just application/patch+json

Ben

---

From: Cyrus Daboo <[email-masked]>
Date: Fri, 18 Jan 2013 09:50:35 -0500

Hi Ben,

> or just application/patch+json

The trouble with those is that they do not explicitly indicate what type of 
data is being patched, only that the patch format itself is in JSON. Not 
sure if that is a big deal or not...

Someone else had suggested that there ought to be a regular syntax for 
patch media types. One suggestion was a new top-level type, e.g. 
patch/json+json, patch/xml+xml. Another option is to define something like 
'application/patch-xxx+yyy' as the appropriate regular form.

-- 
Cyrus Daboo

---

From: James M Snell <[email-masked]>
Date: Fri, 18 Jan 2013 07:46:12 -0800

I am currently working on what I imagine will be a fairly controversial
draft that introduces a new top level media type for patch documents...
examples:

patch/json
patch/json-merge
patch/xml
patch/text
patch/html
...

The draft ought to be published by early next week.
On Jan 18, 2013 6:50 AM, "Cyrus Daboo" <[email-masked]> wrote:

> The trouble with those is that they do not explicitly indicate what type
> of data is being patched, only that the patch format itself is in JSON. Not
> ______________________________**_________________
> https://www.ietf.org/mailman/**listinfo/apps-discuss<https://www.ietf.org/mailman/listinfo/apps-discuss>
>

---

From: Barry Leiba <[email-masked]>
Date: Fri, 18 Jan 2013 13:59:44 -0500

> draft that introduces a new top level media type for patch documents...

Ned Freed is on this list, but it would be a good idea to explicitly
call his attention to this proposal -- perhaps sending it to him
before you post it as a -00 I-D.  It'll help you cross "i"s and dot
"t"s before he comes after you with a shotgun or a twibil.

Barry

---

From: "Martin J. Dürst" <[email-masked]>
Date: Sat, 19 Jan 2013 17:19:31 +0900

> of data is being patched, only that the patch format itself is in JSON.
> Not sure if that is a big deal or not...

Well, what about just assuming that a patch format in json is for json, 
and so on. I'm sure there are exceptions to that, but for these, we can 
use longer names when they come up.

Regards,   Martin.

---

From: Erik Wilde <[email-masked]>
Date: Sat, 19 Jan 2013 09:31:56 +0100

hello martin.

On Jan 19, 2013, at 9:19, "Martin J. Dürst" <[email-masked]> wrote:
> Well, what about just assuming that a patch format in json is for json, and so on. I'm sure there are exceptions to that, but for these, we can use longer names when they come up.

the first exception that comes to mind is a patch format for RDF, which (at a lower syntax level) will be in XML, but actually is in RDF/XML. the best fix for this might be to have suffixes for all RDF syntaxes (something along the lines of ...+rdfxml), but right now RDF/XML uses application/rdf+xml.

cheers,

dret.

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 20 Jan 2013 11:02:27 +1100

Wow, are we really going to boil this ocean?

I mean, go ahead, but let's not block publication on the question of "what opaque string of characters should we use to identify this format", OK?  This is the ultimate bikeshed issue. 

[ regarding the thread, not James' proposal ]

On 19/01/2013, at 2:46 AM, James M Snell <[email-masked]> wrote:

> I am currently working on what I imagine will be a fairly controversial draft that introduces a new top level media type for patch documents... examples:
> 
> patch/json
> patch/json-merge
> patch/xml
> patch/text
> patch/html 
> ...
> 
> --On January 18, 2013 1:24:06 PM +0000 Ben Longden <[email-masked]> wrote:
> 
> The trouble with those is that they do not explicitly indicate what type of data is being patched, only that the patch format itself is in JSON. Not sure if that is a big deal or not...
> 
> Someone else had suggested that there ought to be a regular syntax for patch media types. One suggestion was a new top-level type, e.g. patch/json+json, patch/xml+xml. Another option is to define something like 'application/patch-xxx+yyy' as the appropriate regular form.
> 
> -- 
> Cyrus Daboo
>

---

From: Conal Tuohy <[email-masked]>
Date: Sun, 20 Jan 2013 23:19:36 +1000

> the first exception that comes to mind is a patch format for RDF, which (at a lower syntax level) will be in XML, but actually is in RDF/XML. the best fix for this might be to have suffixes for all…
If you had access to an RDF/XML file on the web you could patch it with 
XML Patch. And I guess you could patch JSON-LD using JSON Patch. But 
IMHO if you are patching RDF graphs you would really want to treat them 
at a different level of abstraction; as RDF graphs, rather than RDF/XML 
documents or JSON-LD documents. Personally, I would use a SPARQL graph 
store, and I'd patch graphs using a SPARQL query (which of course 
already has a media type defined), as suggested in 
http://www.w3.org/TR/sparql11-http-rdf-update/#http-patch

---

From: Erik Wilde <[email-masked]>
Date: Sun, 20 Jan 2013 17:05:23 +0100

hello conal.

On 2013-01-20 14:19 , Conal Tuohy wrote:
> XML Patch.

you could, yes, but that would be like trying to PATCH XML with a 
text-based diff method: Not A Good Idea.

> And I guess you could patch JSON-LD using JSON Patch. But

yes, i've seen SPARQL being suggested for RDF patch. to me it feels a 
bit like patching XML with XQuery: possible, but pulling in a lot of 
machinery that may be overkill. 
http://semanticweb.com/http-patch-and-tracking-rdf-changes_b15382 
suggests that SPARQL is one way to, but there are less complex 
possibilities as well (ChangeSets).

one way or the other, the point i was trying to make was actually that 
any kind of RDF patch format probably would be defined in RDF (SPARQL 
may be an exception here), and thus could be encoded in the various 
syntaxes that RDF has. the patch format would apply to RDF (the model), 
and would be serialized in some RDF syntax. both of these facts would 
need to be captured in a media type name.

cheers,

dret.

---

From: Barry Leiba <[email-masked]>
Date: Mon, 21 Jan 2013 17:34:51 -0500

> It's becoming apparent that there are likely to be a few different flavours of JSON
> Patch out there, so it may make sense to give the one we're working on now a bit
> more of a distinctive name.

It strikes me, on reading the responses to this, that we have no
consensus for any change.  While it's true that this should have been
developed with a "+json" suffix, and that perhaps we should have used
a different name in the first place, there are too many differing
opinons on what the right fix is, it's a very late stage to be trying
to make this change now, and it's not important enough for it to be
worth running the document back through any process at this point.

So I'm going to go ahead and give the final approval for the document
as it stands.

Barry, Applications AD

---

From: Conal Tuohy <[email-masked]>
Date: Tue, 22 Jan 2013 08:52:20 +1000

Hi Barry

It seemed to me, on the contrary, that there was a broad consensus at 
least that the +json should be used. I think it would be a shame if the 
differences of opinion about the name *as a whole* were an obstacle to 
accepting the suffix, because the usefulness of the suffix is generally 
accepted, and it applies regardless of what the rest of the name is. 
Given that, I'd suggest that it would make sense to append the suffix be 
appended to the current name. Is there any reason not to do that?

Con

---

From: "Martin J. Dürst" <[email-masked]>
Date: Tue, 22 Jan 2013 09:16:26 +0900

+1.   Regards,   Martin.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 22 Jan 2013 10:51:28 +0100

> appended to the current name. Is there any reason not to do that?

Indeed.

---

From: "Markus Lanthaler" <[email-masked]>
Date: Tue, 22 Jan 2013 11:43:06 +0100

+1

--
Markus Lanthaler
@markuslanthaler

---

From: Barry Leiba <[email-masked]>
Date: Tue, 22 Jan 2013 13:36:34 -0500

> It seemed to me, on the contrary, that there was a broad consensus at least
> that the +json should be used. I think it would be a shame if the
> accepted, and it applies regardless of what the rest of the name is. Given
> that, I'd suggest that it would make sense to append the suffix be appended
> to the current name. Is there any reason not to do that?

Given the agreement posted so far to this, it sounds like that's an
acceptable way to go.  Let me ask, then, for any objections to this
path, which will make the media type name
"application/json-patch+json".  If you *object* to that change, post
here very soon.  I will put it in as an editor note now.

Barry

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 23 Jan 2013 11:18:05 +1100

> ----------
> From: [email-masked] [mailto:apps-discuss-
> [email-masked]] On Behalf Of Barry Leiba
> Sent: Wednesday, 23 January 2013 5:37 AM
> 
> > least that the +json should be used. I think it would be a shame if
> > the differences of opinion about the name *as a whole* were an
> > obstacle to accepting the suffix, because the usefulness of the
> suffix
> > is generally accepted, and it applies regardless of what the rest of
> > the name is. Given that, I'd suggest that it would make sense to
> > append the suffix be appended to the current name. Is there any
> reason not to do that?
> 
> path, which will make the media type name "application/json-
> patch+json".  If you *object* to that change, post here very soon.  I
> will put it in as an editor note now.
> 
> Barry

If we really want a +json suffix, just make it:
  application/patch+json

Repeating "json" twice, with "-" and "+", just guarantees typos and confusion.

--
James Manger

---

From: Julian Reschke <[email-masked]>
Date: Wed, 23 Jan 2013 16:36:36 +0100

> Repeating "json" twice, with "-" and "+", just guarantees typos and confusion.

I agree that this simpler, but wouldn't object to Barry's choice.

Best regards, Julian

---

From: Barry Leiba <[email-masked]>
Date: Wed, 23 Jan 2013 10:45:44 -0500

> I agree that this simpler, but wouldn't object to Barry's choice.

Indeed, and what James wants is not an option -- it's exactly that
discussion that had me initially say that we don't have consensus on
where to go.  The only options on the table for now, because of the
late change, are these:

1. application/json-patch
2. application/json-patch+json

I see strong consensus for (2), and am *only* asking for objections to
that.  You might prefer something else, but do you *object* to (2)?
That's the only question.

James, are you OK with (2), given that it's not your preference?

[By the way: IANA made the registration for (2) yesterday:
http://www.iana.org/assignments/media-types/application
If we have to revert it because of objections here, we can.]

Barry