Subject: [webfinger] Media type application/jrd+json

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

Folks,

Barry Leiba indicated that we should register the a media type for the
resource representation defined in
http://tools.ietf.org/html/draft-ietf-appsawg-webfinger called the JSON
Resource Descriptor (JRD).

I am sending this for your review and comments back as we are working to
finalize the draft.

I have not completed a template for application types before and I see there
are a few new things in the template, so please do let me know if there is
anything that needs clarification or should be changed.

Thanks,
Paul

================================================

Type name: application

Subtype name: jrd+json

Required parameters: N/A

Optional parameters: N/A
  "charset" - Indicates the character set used to encode the JSON Resource
  Descriptor.  If absent, UTF-8 is assumed.

Encoding considerations: 8bit

Security considerations:
  The JSON Resource Descriptor (JRD) is a JavaScript Object Notation (JSON)
  object.  It is a text format that must be parsed by entities that wish to
  utilize the format.  Depending on the language and mechanism used to parse
  a JSON object, it is possible for an attacker to inject behavior into a
running
  program.  Therefore, care must be taken to properly parse a received JRD
to
  ensure that only a valid JSON object is present and that no JavaScript
code is
  injected or executed unexpectedly.

Interoperability considerations:
  This media type is a JavaScript Object Notation (JSON) object and can be
  consumed by any software application that can consume JSON objects.

Published specification: RFC QQQ

Applications that use this media type: WebFinger

Fragment identifier considerations: N/A

Additional information:
  Deprecated alias names for this type: N/A
  Magic number(s): N/A
  File extension(s): jrd+json
  Macintosh file type code(s): N/A

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

Intended usage: COMMON

Restrictions on usage: N/A

Author: Paul E. Jones <[email-masked]>

Change controller: Paul E. Jones <[email-masked]>

Provisional registration? (standards tree only): N/A

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Fri, 08 Feb 2013 18:46:11 +0100

* Paul E. Jones wrote:
>http://tools.ietf.org/html/draft-ietf-appsawg-webfinger

This should say something like "Same as for application/json" or there
should be a reason given for why it's different.

>Encoding considerations: 8bit

This should probably say something like "See RFC 6839, section 3.1.".

>Published specification: RFC QQQ

(The convention is to use "RFC XXXX".)

>Applications that use this media type: WebFinger

(That's very brief, I would prefer a proper sentence.)

>Fragment identifier considerations: N/A

As above, given RFC 6839 it's not clear what this means.

>  File extension(s): jrd+json

Are you sure about having a `+` in file extensions?

>Change controller: Paul E. Jones <[email-masked]>

I haven't checked RFC 4288's successor, but I assume this should more
likely be "The IETF." or "The IESG".
-- 
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: Chris Newman <[email-masked]>
Date: Fri, 08 Feb 2013 10:53:24 -0800

The introduction of the "charset" parameter that is not present in the 
application/json media type makes this incompatible with application/json 
(since it implicitly allows use of character sets that are not permitted 
with application/json). As a result, this registration is not compatible 
with the "+json" suffix.

I recommend either removing the charset parameter or changing the name to 
omit the "+json" suffix. I note the former choice will result in a media 
type that is simpler to implement.

		- Chris

--On February 7, 2013 16:54:11 -0500 "Paul E. Jones" 
<[email-masked]> wrote:
> I have not completed a template for application types before and I see
> there are a few new things in the template, so please do let me know if
> there is anything that needs clarification or should be changed.
>
> Thanks,
> Paul
>
>   The JSON Resource Descriptor (JRD) is a JavaScript Object Notation
> (JSON)   object.  It is a text format that must be parsed by entities
> that wish to   utilize the format.  Depending on the language and
> mechanism used to parse   a JSON object, it is possible for an attacker
> to inject behavior into a running
> _______________________________________________
> media-types mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/media-types
>

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 14:14:32 -0500

Björn,

Thanks for the quick review.  I have a couple of questions.

> should be a reason given for why it's different.

Unfortunately, application/json just says "n/a".  I changed my text to say
the same, but a question I have is "should we specify 'charset'"?  Without
the character set being explicitly specified in the Content-Type header in
the HTTP response, it's not clear to me that we could guarantee proper
interpretation.  Perhaps it is possible because the only valid encodings are
UTF-8, -16, and -32?
 
> As above, given RFC 6839 it's not clear what this means.

I have no clue what to put here, honestly.  Can you suggest text or point me
to text I can borrow?  I'm not aware of a spec that defines how to use the
fragment syntax to dereference part of a JSON object, though some attempts
have been made to define that.  Is there something we should use?  We
certainly can define that within this document, as that is a whole problem
unto itself.
 
> Are you sure about having a `+` in file extensions?

I have absolutely no preference, though this extension would make it easier
for some using the Apache web server.  We could just call it "jrd".  I'm OK
with flipping a coin on this one.

I have modified the template per your advice, though we might need to adjust
it further based on the answers to the above.  I put the updated template
below.

Thanks!
Paul

------------------------

Type name: application

Subtype name: jrd+json

Required parameters: N/A

Optional parameters: N/A

Encoding considerations: See RFC 6839, section 3.1.

Security considerations:
  The JSON Resource Descriptor (JRD) is a JavaScript Object Notation (JSON)
  object.  It is a text format that must be parsed by entities that wish to
  utilize the format.  Depending on the language and mechanism used to parse
  a JSON object, it is possible for an attacker to inject behavior into a
  running program.  Therefore, care must be taken to properly parse a
  received JRD to ensure that only a valid JSON object is present and that
  no JavaScript or other code is injected or executed unexpectedly.

Published specification: RFC XXXX

Applications that use this media type:
  The JSON Resource Descriptor (JRD) is used by the WebFinger protocol
  (RFC XXXX) to enable the exchange of information between a client and
   a WebFinger resource over HTTPS.

Additional information:

Intended usage: COMMON

Change controller:
  IESG has change control over this registration.

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Feb 2013 14:16:21 -0500

> with application/json). As a result, this registration is not compatible

That's a good point: JSON already specifies the encoding, so a charset
parameter is not only not necessary, but is actively bad.

I agree that eliminating "charset" is best, and I suggest actively
noting that it's not allowed, to avoid any question.  Perhaps
something like this:

NEW
  Optional parameters: None
  In particular, because RFC 4627 already defines the character encoding
  for JSON, no "charset" parameter is permitted.
END

Barry

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 14:17:00 -0500

OK.  I changed it to N/A in the update (to match application/json).

Still feels wrong somehow... but, I'll not belabor the point.

Paul

> -----Original Message-----
> From: Chris Newman [mailto:[email-masked]]
> Sent: Friday, February 08, 2013 1:53 PM
> To: Paul E. Jones; [email-masked]
> Cc: [email-masked]; Barry Leiba
> Subject: Re: [media-types] Media type application/jrd+json
> 
> application/json media type makes this incompatible with
> application/json (since it implicitly allows use of character sets that
> are not permitted with application/json). As a result, this registration
> is not compatible with the "+json" suffix.
> 
> I recommend either removing the charset parameter or changing the name
> to omit the "+json" suffix. I note the former choice will result in a
> media type that is simpler to implement.
> 
> 		- Chris
> 
> > http://tools.ietf.org/html/draft-ietf-appsawg-webfinger called the
> > JSON Resource Descriptor (JRD).
> >
> > I am sending this for your review and comments back as we are working
> > to finalize the draft.
> >
> > there are a few new things in the template, so please do let me know
> > if there is anything that needs clarification or should be changed.
> >
> > Thanks,
> > Paul
> >
> >   program.  Therefore, care must be taken to properly parse a received
> > JRD to
> >   ensure that only a valid JSON object is present and that no
> > JavaScript code is

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 14:21:57 -0500

I wrote:
> Unfortunately, application/json just says "n/a".  I changed my text to
> say the same, but a question I have is "should we specify 'charset'"?
> Without the character set being explicitly specified in the Content-Type
> header in the HTTP response, it's not clear to me that we could
> guarantee proper interpretation.  Perhaps it is possible because the
> only valid encodings are UTF-8, -16, and -32?

Scratch that one... Section 3 of RFC 4627 specifies how to guarantee proper
interpretation.

Paul

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 14:26:08 -0500

Barry,

>   Optional parameters: None

Per RFC 6838, I must put "N/A", not "none".

>   for JSON, no "charset" parameter is permitted.

Do we want to say that the parameter is not permitted or just say that it is
not necessary?  My web server might make an attempt to add a charset
parameter in the Content-Type if I don't explicitly insert one.  I've not
tested that, but I have seen odd behavior like that before, so I get in the
habit of being explicit about it.

Paul

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Feb 2013 14:36:51 -0500

> Per RFC 6838, I must put "N/A", not "none".

OK.

> habit of being explicit about it.

Well, RFC 6657 explains the problems with conflicting charset
information.  Even though this isn't a "text/*" media type, the issues
apply here as well, as, I think, do the conclusions: that media type
registrations should either (quoting from 6657 here)

   a.  specify that the "charset" parameter is not used for the defined
       subtype, because the charset information is transported inside
       the payload (such as in "text/xml"), or

   b.  require explicit unconditional inclusion of the "charset"
       parameter, eliminating the need for a default value.

I'm suggesting (a), but I'm also happy if you think it's safer to do
(b), as long as you make it clear that the only acceptable values are
UTF-8, UTF-16, and UTF-32, and that the one specified must match the
encoding used in the content.

b

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Fri, 08 Feb 2013 22:52:02 +0100

>certainly can define that within this document, as that is a whole problem

You could say something like "Same as for application/json" or "As per
RFC 6839" or say fragment identifier semantics are not defined for now
because the WebFinger community is still discussing this and it is un-
clear whether following the general +json conventions is suitable for
this type, as far as I am concerned. You just can't say nothing while
RFC 6839 says you SHOULD do something specific.

>with flipping a coin on this one.

A possible problem is that file extensions often end up in regular ex-
pressions of some form, or in query strings in URLs, where the `+` may
be interpreted in a surprising manner, but I do not really care either.

>it further based on the answers to the above.  I put the updated template

Looks better, thanks.

---

From: Mike Jones <[email-masked]>
Date: Fri, 8 Feb 2013 21:54:49 +0000

If a file extension is going to be defined for the media type, I believe that it should be "jrd".

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Bjoern Hoehrmann
Sent: Friday, February 08, 2013 1:52 PM
To: Paul E. Jones
Cc: [email-masked]; 'Barry Leiba'; [email-masked]
Subject: Re: [webfinger] [media-types] Media type application/jrd+json

* Paul E. Jones wrote:
>I have no clue what to put here, honestly.  Can you suggest text or 
>point me to text I can borrow?  I'm not aware of a spec that defines 
>how to use the fragment syntax to dereference part of a JSON object, 
>though some attempts have been made to define that.  Is there something 
>we should use?  We certainly can define that within this document, as 
>that is a whole problem unto itself.

You could say something like "Same as for application/json" or "As per RFC 6839" or say fragment identifier semantics are not defined for now because the WebFinger community is still discussing this and it is un- clear whether following the general +json conventions is suitable for this type, as far as I am concerned. You just can't say nothing while RFC 6839 says you SHOULD do something specific.

>I have absolutely no preference, though this extension would make it 
>easier for some using the Apache web server.  We could just call it 
>"jrd".  I'm OK with flipping a coin on this one.

A possible problem is that file extensions often end up in regular ex- pressions of some form, or in query strings in URLs, where the `+` may be interpreted in a surprising manner, but I do not really care either.

>I have modified the template per your advice, though we might need to 
>adjust it further based on the answers to the above.  I put the updated 
>template below.

Looks better, thanks.
--
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/ _______________________________________________
webfinger mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/webfinger

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Feb 2013 16:59:40 -0500

> If a file extension is going to be defined for the media type, I believe that it should be "jrd".

Да.

Barry

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 17:00:05 -0500

"not used" sounds reasonable.  Using your language (plus "not used")...

    In particular, because RFC 4627 already defines the character encoding
    for JSON, no "charset" parameter is used.

Paul

> From: [email-masked] [mailto:[email-masked]] On Behalf Of
> Barry Leiba
> Sent: Friday, February 08, 2013 2:37 PM
> To: Paul E. Jones
> Cc: Chris Newman; [email-masked]; [email-masked]
> > Do we want to say that the parameter is not permitted or just say that
> > it is not necessary?  My web server might make an attempt to add a
> > charset parameter in the Content-Type if I don't explicitly insert
> > one.  I've not tested that, but I have seen odd behavior like that
> > before, so I get in the habit of being explicit about it.
> 
> I'm suggesting (a), but I'm also happy if you think it's safer to do (b),
> as long as you make it clear that the only acceptable values are UTF-8,
> UTF-16, and UTF-32, and that the one specified must match the encoding
> used in the content.
> 
> b

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 17:26:47 -0500

Björn,

> RFC 6839 says you SHOULD do something specific.

We're not inventing anything new here: this format is just a JSON object.
So, perhaps the best solution is to just borrow words from RFC 6839:

    The syntax and semantics of fragment identifiers SHOULD be as specified
    for "application/json".  (At publication of this document, there is no
    fragment identification syntax defined for "application/json".)

That OK?
 
> be interpreted in a surprising manner, but I do not really care either.

I'll ask the WF group separately on this and see if I can get closure.

Thanks!
Paul

---

From: "Paul E. Jones" <[email-masked]>
Date: Fri, 8 Feb 2013 17:30:47 -0500

Thanks, Mike.

I didn't see your reply before sending the other email on this topic.

Paul

> From: Mike Jones [mailto:[email-masked]]
> Sent: Friday, February 08, 2013 4:55 PM
> To: Bjoern Hoehrmann; Paul E. Jones
> Subject: RE: [webfinger] [media-types] Media type application/jrd+json
>