Subject: [webfinger] Media type for WebFinger

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 7 Feb 2013 00:57:21 -0500

Folks,

Most of the comments received have been editorial.  I've tried to capture
all of them, though there is the possibility one slips through.  None seem
like showstoppers.

However, one comment that I've not taken action on is defining a media type
for WebFinger.  There are split views on this.  Some are arguing we need
something and others say we don't.  Some say it might be helpful if present,
but not everyone agrees.

Personally, I'm in the camp that we do not need anything more than
application/json.  A query to a WebFinger resource means one would get a WF
response and the application type is really not so important.  It is
important to know that it's application/json vs. XML or plain text or other,
but to introduce something like application/jrd+json or some such seems like
overkill to me.  I've not seen this done for the gazillion other web
services that use JSON.

So, is there truly a need to have an dedicated type?  If so, what should be
the name of this type?  And is WF going to be the first of a bunch of spec
that create a bunch of JSON media types like there were for +xml?

I prefer application/json, unless there is a technical reason someone can
bring to my attention to show why this is a bad idea.

Paul

---

From: Barry Leiba <[email-masked]>
Date: Thu, 7 Feb 2013 11:28:46 -0500

As I said in the other thread: the purpose of a media type is to tag
your payload for situations where you don't know <<a priori>> what it
is.  No, it's not sufficient to say whether it's plain text, XML, or
JSON (for that matter, XML and JSON are plain text, aren't they?).
You have to know the context.  It may be that in your use case, or
even in all the current use cases, you do know the context.  But you
can't guarantee that will always be true, and defined media types let
us plan ahea.

I can also assure you that you'll get pushback from the IESG on this
point (and not only from me).  This isn't just empty process: there's
value in having a specific media type to tag data that's used for a
specific purpose.

Now, it's not a difficult thing to define a media type, and it's
especially easy if you're already writing an RFC anyway.  And it's
also easy to use the media type -- why's it harder to tag something
as, say, application/webfinger+json than as application/json?

So, to two of your points, specifically:

> And is WF going to be the first of a bunch of spec

Probably yes.

> bring to my attention to show why this is a bad idea.

No, the question goes the other way 'round.  Creating appropriate
media types is how we do this, so it needs to be done unless you (or
someone else) have a technical reason that *it* is a bad idea.
Really: if it's just that you don't like it or think it's unnecessary,
I get that and I sympathise, but that's not a valid reason (others and
I have already said why we do think it's necessary).  If you *do* have
a reason that it's actively bad, state it and people will listen.

Barry, Applications AD

---

From: Dick Hardt <[email-masked]>
Date: Thu, 7 Feb 2013 09:02:16 -0800

Barry

To help the less knowledgeable such as myself, would you be kind enough to point out some examples of similar protocols that are widely deployed that defined a new media type?

Myself as a developer, I don't know why I would need anything more than JSON. That tells me how to parse the media. If the payload has a more specific media, I can't use my existing tool chain that automatically detects a JSON payload and parses it for me and hands my application an object.

-- Dick

On Feb 7, 2013, at 8:28 AM, Barry Leiba <[email-masked]> wrote:

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

---

From: Tim Bray <[email-masked]>
Date: Thu, 7 Feb 2013 09:17:50 -0800

On Thu, Feb 7, 2013 at 9:02 AM, Dick Hardt <[email-masked]> wrote:

> Barry
>
> To help the less knowledgeable such as myself, would you be kind enough to
> point out some examples of similar protocols that are widely deployed that
> defined a new media type?
>

I’ve got a better idea; why don’t we just stop arguing over this stupid
bikeshed issue and do what our AD just asked us to do.

 -Tim

>
> Myself as a developer, I don't know why I would need anything more than
> JSON. That tells me how to parse the media. If the payload has a more
> specific media, I can't use my existing tool chain that automatically
> detects a JSON payload and parses it for me and hands my application an
> object.
>
> -- Dick
>

---

From: Barry Leiba <[email-masked]>
Date: Thu, 7 Feb 2013 12:29:30 -0500

> To help the less knowledgeable such as myself, would you be kind enough to point
> out some examples of similar protocols that are widely deployed that defined a new
> media type?

Setting this aside for the moment (I'm on the IESG telechat right now)...

> Myself as a developer, I don't know why I would need anything more than JSON. That
> tells me how to parse the media.

It does, but, as I said before, it doesn't tell you what to do with
it.  You don't know whether to hand it to your webfinger handler, or
to some other thing that uses JSON objects.

> If the payload has a more specific media, I can't use my existing tool chain that
> automatically detects a JSON payload and parses it for me and hands my application
> an object.

This was the point of making the suffixes.  If your tools look for the
"+json" media type suffix, you know how to parse it.  And from the
rest of the media type, you know what handler to use once it's parsed.

Barry

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 7 Feb 2013 16:54:53 -0500

OK.. I started that process.  See my separated email.

Paul

> -----Original Message-----
> From: [email-masked]
> [mailto:[email-masked]] On Behalf Of Barry Leiba
> Sent: Thursday, February 07, 2013 11:29 AM
> To: Paul E. Jones
> Cc: [email-masked]
> Subject: Re: [webfinger] Media type for WebFinger
> 
> your payload for situations where you don't know <<a priori>> what it is.
> No, it's not sufficient to say whether it's plain text, XML, or JSON
> (for that matter, XML and JSON are plain text, aren't they?).
> You have to know the context.  It may be that in your use case, or even
> in all the current use cases, you do know the context.  But you can't
> guarantee that will always be true, and defined media types let us plan
> ahea.
> 
> especially easy if you're already writing an RFC anyway.  And it's also
> easy to use the media type -- why's it harder to tag something as, say,
> application/webfinger+json than as application/json?
> 
> > And is WF going to be the first of a bunch of spec that create a bunch
> > of JSON media types like there were for +xml?
> 
> Probably yes.
> 
> > I prefer application/json, unless there is a technical reason someone
> > can bring to my attention to show why this is a bad idea.
> 
> No, the question goes the other way 'round.  Creating appropriate media
> types is how we do this, so it needs to be done unless you (or someone
> else) have a technical reason that *it* is a bad idea.
> Really: if it's just that you don't like it or think it's unnecessary, I
> get that and I sympathise, but that's not a valid reason (others and I
> have already said why we do think it's necessary).  If you *do* have a
> reason that it's actively bad, state it and people will listen.
> 
> Barry, Applications AD
> 
> > Most of the comments received have been editorial.  I've tried to
> > capture all of them, though there is the possibility one slips
> > through.  None seem like showstoppers.
> >
> > However, one comment that I've not taken action on is defining a media
> > type for WebFinger.  There are split views on this.  Some are arguing
> > we need something and others say we don't.  Some say it might be
> > helpful if present, but not everyone agrees.
> >
> > application/json.  A query to a WebFinger resource means one would get
> > a WF response and the application type is really not so important.  It
> > is important to know that it's application/json vs. XML or plain text
> > or other, but to introduce something like application/jrd+json or some
> > such seems like overkill to me.  I've not seen this done for the
> > gazillion other web services that use JSON.
> >
> > So, is there truly a need to have an dedicated type?  If so, what
> > should be the name of this type?  And is WF going to be the first of a
> > bunch of spec that create a bunch of JSON media types like there were
> for +xml?
> >
> > I prefer application/json, unless there is a technical reason someone
> > can bring to my attention to show why this is a bad idea.
> >
> > Paul

---

From: Dick Hardt <[email-masked]>
Date: Thu, 7 Feb 2013 16:17:34 -0800

On Feb 7, 2013, at 9:17 AM, Tim Bray <[email-masked]> wrote:

> I’ve got a better idea; why don’t we just stop arguing over this stupid bikeshed issue and do what our AD just asked us to do.

I apologize for coming in late on this conversation and if it has been discussed significantly already.

Speaking as a developer, having a media type other than application/json looks to cause me a bunch of hassle. When writing a server, I would have to explicitly set the header rather than just writing a JSON object and letting my server to the right thing, and when writing a client, my libraries will give me a parsed object automatically if it is application/json. I already know if I am serving or requesting Web Finger data, so I am confused about the value I would get as a developer having a media type other than application/json.

-- Dick

---

From: Melvin Carvalho <[email-masked]>
Date: Fri, 8 Feb 2013 03:37:43 +0100

On 8 February 2013 01:17, Dick Hardt <[email-masked]> wrote:

>> To help the less knowledgeable such as myself, would you be kind enough
>> to point out some examples of similar protocols that are widely deployed
>> that defined a new media type?
>>
>
> Speaking as a developer, having a media type other than application/json
> looks to cause me a bunch of hassle. When writing a server, I would have to
> explicitly set the header rather than just writing a JSON object and
> letting my server to the right thing, and when writing a client, my
> libraries will give me a parsed object automatically if it is
> application/json. I already know if I am serving or requesting Web Finger
> data, so I am confused about the value I would get as a developer having a
> media type other than application/json.
>

Hi Dick, thanks for your comments, is this really big hassle, I would
expect maximum one line of code in most programming languages.  To my mind
the question lies with interop ... there are many serializations on the
internet, and giving a media type is way to tell a wider audience what then
can expect

---

From: Brad Fitzpatrick <[email-masked]>
Date: Thu, 7 Feb 2013 20:00:02 -0800

> media type other than application/json.

You should set it explicitly anyway so your server doesn't sniff
incorrectly on weird or malicious input.

Imagine the server also has a future CRUD API.  As a malicious peer server
OAuthing adding new links to a victim, I just have to get some HTML in the
first 512 bytes to trick your sniffer and then other links can have
JavaScript/XSS payloads.

---

From: Dick Hardt <[email-masked]>
Date: Fri, 8 Feb 2013 11:27:33 -0800

On Feb 7, 2013, at 8:00 PM, Brad Fitzpatrick <[email-masked]> wrote:

> You should set it explicitly anyway so your server doesn't sniff incorrectly on weird or malicious input.
> 
> Imagine the server also has a future CRUD API.  As a malicious peer server OAuthing adding new links to a victim, I just have to get some HTML in the first 512 bytes to trick your sniffer and then other links can have JavaScript/XSS payloads.

I agree the content type SHOULD be set explicitly and checked explicitly. Not having to explicitly set the content type lowers the barriers to people experimenting -> lower barrier to adoption.  

-- Dick

---

From: Dick Hardt <[email-masked]>
Date: Fri, 8 Feb 2013 11:28:42 -0800

On Feb 7, 2013, at 6:37 PM, Melvin Carvalho <[email-masked]> wrote:

> Hi Dick, thanks for your comments, is this really big hassle, I would expect maximum one line of code in most programming languages.  To my mind the question lies with interop ... there are many serializations on the internet, and giving a media type is way to tell a wider audience what then can expect

An extra line of code is another stumbling block for a less experienced programmer to trip over. 

JSON is the serialization is it not? I'm unclear on what value being more specific provides.

I'm going to write up some test code to see what  the node.js libraries do with application/jrd+json on the client side.

-- Dick