Subject: [apps-discuss] Why JRD?

From: Tim Bray <[email-masked]>
Date: Tue, 27 Nov 2012 23:13:48 -0800

I’m thinking the WebFinger spec should be self-contained. Why should I
have to go off to RFC6415 and look at Appendix A, which explains JRD
by giving an XML example and its JSON translation?

And anyhow, what does “RD” stand for in the acronym?

Why shouldn’t the WebFinger spec just contain a complete specification
of the JSON returned? It’s not as though it’s complicated. I would
propose that it contain:

A required "subject" field; it’s generally good for a resource’s
representation to have an opinion about its name.

A required "links" field, a list of zero or more objects, each of which has:

- a required "rel" field
- a required "href" field
- an optional "type" field
- an optional "titles" field

It should be stated that if there are any fields in the JSON that are
not defined above, receiving software MUST NOT report an error or fail
to function because of their presence.

I volunteer to draft spec language for the above if nobody else wants
to.  It’ll fit on a page with lots of whitespace.

 -T

---

From: "Paul E. Jones" <[email-masked]>
Date: Wed, 28 Nov 2012 03:44:54 -0500

Tim,

The JRD format is extremely simple.  I'd really prefer to not change the
format in any way.

We did have a discussion before about more-or-less documenting all of JRD
inside the WF spec, but people preferred to just make the reference to RFC
6415 Appendix A and provide some examples so people didn't really even need
to read it.

I'm certainly not opposed to documenting everything inside the WF spec and
I'm more than happy if you want to contribute that section.  But, I'd really
like to not deviate away from the JSON Resource Descriptor (RD) format.  If
there was the slighted simplification we can make to it, it would be that --
the slightest.  Leaving out things like "properties" is unfortunate, too,
since I can see utility in those.

Paul

> -----Original Message-----
> From: [email-masked] [mailto:apps-discuss-
> [email-masked]] On Behalf Of Tim Bray
> Sent: Wednesday, November 28, 2012 2:14 AM
> To: [email-masked]; [email-masked]
> Subject: [apps-discuss] Why JRD?
> 
> I'm thinking the WebFinger spec should be self-contained. Why should I
> have to go off to RFC6415 and look at Appendix A, which explains JRD by
> giving an XML example and its JSON translation?
> 
> And anyhow, what does "RD" stand for in the acronym?
> 
> Why shouldn't the WebFinger spec just contain a complete specification
> of the JSON returned? It's not as though it's complicated. I would
> propose that it contain:
> 
> A required "subject" field; it's generally good for a resource's
> I volunteer to draft spec language for the above if nobody else wants to.
> It'll fit on a page with lots of whitespace.
> 
>  -T
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Joe Gregorio <[email-masked]>
Date: Wed, 28 Nov 2012 09:02:17 -0500

> to function because of their presence.

+1 to having a completely contained description of the format within
the spec, and to cleaning
up the syntax. Tying this in any way to XRD is just confusing.
Reserializing XML as JSON
is also painful and unproductive. I can speak from experience on this
as we tried this at Google
with offering dual support of XML and JSON for feeds and APIs:

  https://developers.google.com/gdata/docs/json

That strategy failed and we've since abandoned it, with new APIs being
JSON first.

  -joe

--
Joe Gregorio        http://bitworking.org

---

From: Dick Hardt <[email-masked]>
Date: Wed, 28 Nov 2012 06:45:16 -0800

+1 to Tim writing the section!

---

From: Tim Bray <[email-masked]>
Date: Wed, 28 Nov 2012 10:46:54 -0800

Here's a draft of how I think the WebFinger payload should be specified.
 First, a base principle: I don’t think it’s OK for Internet protocols to
contain features that are there because they might be useful in the future.
I think having an easily-located bundle of link relations meets this bar.
Put in a MUST_UNDERSTAND and that leaves the world free to devise
extensions which, after they’ve proven to be useful, can be standardized
appropriately without breaking anything.

- I went and looked at the "subject" definition from 6415 and it led to a
pointer to "context IRI" in 5988 and I decided I had no idea what it was
for. Is it designed to be the equivalent of <link rel="self"> in RFC4287?
If so, I wouldn’t be against having it if people really want it.
- I couldn’t see why "expires" is necessary, given that this is served over
HTTP, which has rich and well-debugged caching features.
- Even though the payload is just an array, the top level is still an
object to allow for extensibility

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
X. Representation of WebFinger resources

A WebFinger resource is represented by a JSON text [RFC4627], identified by
Internet media type "application/json". In this section, "member",
"object", "array", and "string" have the meanings defined in RFC4627.

A WebFinger resource representation is an object which MUST contain one
member whose name is "links" and whose value is an array, containing one or
more Link Objects.

A Link Object is an object as follows:

- It MUST contain a string member whose name is "rel" and whose value is
either an IANA-registered link relation type [REF] or a URI.
- It MUST contain a string member whose name is "href" and whose value is a
URI reference. [RFC3986]
- It MAY contain a string member whose name is "type" and whose value is an
Internet Media type.  This value is advisory, conveying a hint as to the
type of the representation that would be retrieved by dereferencing the
"href" URI.
- It MAY an object member whose name is "titles"
-- A "titles" object MAY have a string member whose name is "default".
-- A "titles" object MAY have any number of string members whose names are
a language identifiers [RFC3066]

Software which is processing a WebFinger representation and encounters
members which are not specified in this document MUST NOT consider this an
error condition.  If it is not designed to process such members, it MUST
NOT change its behavior because of their presence.

---

From: James M Snell <[email-masked]>
Date: Wed, 28 Nov 2012 12:06:20 -0800

> appropriately without breaking anything.

MUST_UNDERSTAND or MUST_IGNORE?

> - I couldn’t see why "expires" is necessary, given that this is served
> over HTTP, which has rich and well-debugged caching features.
+1 ...

> A WebFinger resource is represented by a JSON text [RFC4627], identified
> by Internet media type "application/json". In this section, "member",
> - It MUST contain a string member whose name is "href" and whose value is
> a URI reference. [RFC3986]
> - It MAY contain a string member whose name is "type" and whose value is
> an Internet Media type.  This value is advisory, conveying a hint as to the

s/RFC3066/RFC4647 ... language identifiers would best be specified as
language ranges to provide the best flexibility.. in fact, "default" can be
replaced with the range "*" to make things consistent. Nice and simple
really.

  { "*": "Foo", "fr-*": "le Foo" }

> NOT change its behavior because of their presence.
+1

- James

---

From: Martin Thomson <[email-masked]>
Date: Wed, 28 Nov 2012 12:10:04 -0800

> MUST_UNDERSTAND or MUST_IGNORE?

I inferred MUST_UNDERSTAND_IF_YOU_DO_ANYTHING_ABOUT_IT_OTHERWISE_MUST_IGNORE,
so ... yes.

---

From: Tim Bray <[email-masked]>
Date: Wed, 28 Nov 2012 12:14:46 -0800

Eek, I meant MUST_IGNORE of course.  I have never ever written a
MUST_UNDERSTAND clause and hope to carry that record into my grave. -T

On Wed, Nov 28, 2012 at 12:06 PM, James M Snell <[email-masked]> wrote:

>> Put in a MUST_UNDERSTAND and that leaves the world free to devise extensions
>> which, after they’ve proven to be useful, can be standardized appropriately
>> without breaking anything.
>
>
>> for. Is it designed to be the equivalent of <link rel="self"> in RFC4287? If
>> so, I wouldn’t be against having it if people really want it.
>> error condition.  If it is not designed to process such members, it MUST NOT
>> change its behavior because of their presence.
>>
>
> +1
>
> - James
>
>>

---

From: Mike Kelly <[email-masked]>
Date: Wed, 28 Nov 2012 22:54:59 +0000

I'm wondering about the reasons you have used an array for the links
property instead of an object within which link relations are used as
a key, i.e:

{
  links: {
    self: { href: "/" }
  }
}

I read the background doc in the other thread and it said that easing
client consumption was important. Surely the above is easier for
clients to consume because it makes the most of the JSON object model,
rather than they array approach which forces clients to iterate and
select what they need?

Cheers,
M

On Wed, Nov 28, 2012 at 6:46 PM, Tim Bray <[email-masked]> wrote:
> - Even though the payload is just an array, the top level is still an object
> to allow for extensibility
>
> Internet media type "application/json". In this section, "member", "object",
> "array", and "string" have the meanings defined in RFC4627.
>
> -- A "titles" object MAY have any number of string members whose names are a
> language identifiers [RFC3066]
>

-- 
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 29 Nov 2012 00:36:55 -0500

Joe,

But, the JRD syntax is already defined.  Just pretend XRD never existed.
Look at JRD on its own.  It's simple.  Why go make a bunch of changes to it
now?

I can appreciate documenting all of JRD fully in the spec.  Who wants to do
that?  I don't want to write that.  Was Tim volunteering?

Paul

> [email-masked]] On Behalf Of Joe Gregorio
> Sent: Wednesday, November 28, 2012 9:02 AM
> To: [email-masked]
> Cc: [email-masked]
> Subject: Re: [apps-discuss] Why JRD?
> 
> is also painful and unproductive. I can speak from experience on this as
> we tried this at Google with offering dual support of XML and JSON for
> feeds and APIs:
> 
> > to.  It'll fit on a page with lots of whitespace.
> >
> >  -T
> 
> 
> 
> --

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 29 Nov 2012 01:45:31 -0500

Tim,

This really overly simplifies the JRD.  We actually do lose some utility
with this over simplification.  IMO, there is value in reuse of a simple
document format like XRD and JRD.  JRD was directly derived from XRD.  Each
element is clear, I think:

Expires:
http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.expires

Subject:
http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.subject

Aliases: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.alias

Properties:
http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.property

Link: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.link

Title: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html#element.title

(Boy, I sure which RFCs were as accessible as this. but I digress.)

Here's a document that uses every single thing defined above and I try to
present it to show how it might be utilized:

{

  "expires" : "2012-11-29T06:44:00Z",

  "subject" : "acct:[email-masked]",

  "aliases" :

 [

    "http://www.packetizer.com/people/paulej/",

    "mailto:[email-masked]"

 ],

  "properties" :

  {

    "http://webfinger.net/rel/name" : "Paul E. Jones"

  },

  "links" :

  [

    {

      "rel" : "http://webfinger.net/rel/avatar",

      "href" : "http://www.packetizer.com/people/paulej/images/paulej.jpg"

},

{

  "rel" : "blog",

  "type" : "text/html",

  "href" : "www.packetizer.com/people/paulej/blog/",

  "titles" :

  {

        "en-us" : "Paul E. Jones' Blog"

  }

},

{

  "rel" : "vcard",

  "href" : "http://www.packetizer.com/people/paulej/paulej.vcf"

},

    {

      "rel" : "http://example.net/rel/smtp-server",

      "properties" :

      {

        "host" : "smtp.example.com",

        "port" : "587",

        "login-required" : "yes",

        "transport" : "starttls"

      }

    },

    {

      "rel" : "http://example.net/rel/imap-server",

      "properties" :

      {

        "host" : "imap.example.com",

        "port" : "993",

        "transport" : "ssl"

      }

    }

  ]

}

There is some redundancy:

-          "Expires" could be replaced with the HTTP expires header, though
I personally think the date format defined in XML and carried over into JRD
is far easier to handle.

-          Subject is just "what you queried for", so no need to go off
looking at XRI documents.  While redundant, it might be useful if the
document is stored for some reason and accessed later.

The rest of the JRD document attribute/value pairs has utility.  Given that
XRD and JRD are defined, the number of elements we are looking at are
minimal, and there is utility in things like properties, why try to change
format?

I'm not opposed to documenting everything in the WF spec, but I see no
reason to change the format.  I'm not sure if my example above will provide
any persuasion, but I hope you can appreciate how those simple elements can
provide great utility.  I can provision my email client, for example, using
just the information that might come back in a query to
mailto:[email-masked], versus having a link relation that points to
yet another document format to do the same. 

Paul

From: [email-masked] [mailto:[email-masked]]
On Behalf Of Tim Bray
Sent: Wednesday, November 28, 2012 1:47 PM
To: Dick Hardt
Cc: [email-masked]; [email-masked]
Subject: Re: [apps-discuss] Why JRD?

Here's a draft of how I think the WebFinger payload should be specified.
First, a base principle: I don't think it's OK for Internet protocols to
contain features that are there because they might be useful in the future.
I think having an easily-located bundle of link relations meets this bar.
Put in a MUST_UNDERSTAND and that leaves the world free to devise extensions
which, after they've proven to be useful, can be standardized appropriately
without breaking anything.

- I went and looked at the "subject" definition from 6415 and it led to a
pointer to "context IRI" in 5988 and I decided I had no idea what it was
for. Is it designed to be the equivalent of <link rel="self"> in RFC4287? If
so, I wouldn't be against having it if people really want it.
- I couldn't see why "expires" is necessary, given that this is served over
HTTP, which has rich and well-debugged caching features.
- Even though the payload is just an array, the top level is still an object
to allow for extensibility

---

From: "Martin J. Dürst" <[email-masked]>
Date: Thu, 29 Nov 2012 16:01:15 +0900

> (Boy, I sure which RFCs were as accessible as this. but I digress.)

What about http://tools.ietf.org/html/rfc6415#section-3.1.1 ?

Regards,   Martin.

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 29 Nov 2012 02:19:07 -0500

That works only because tools.ietf.org processes the documents and turns the legacy ASCII text files into HTML.  But, the tools are not perfect and we still have to live with these 72 column pages and page numbers.

Fortunately, this is something the RFC editor is presently addressing.

Paul

> From: "Martin J. Dürst" [mailto:[email-masked]]
> Sent: Thursday, November 29, 2012 2:01 AM
> To: Paul E. Jones
> Cc: 'Tim Bray'; 'Dick Hardt'; [email-masked]; apps-
> [email-masked]

---

From: Joe Gregorio <[email-masked]>
Date: Thu, 29 Nov 2012 09:11:41 -0500

> Look at JRD on its own.  It's simple.  Why go make a bunch of changes to it

I don't think Tim's proposal is a large number of changes, his
proposal drops expires which
doesn't belong in the file, and it drops properties.

I don't think properties, at the links level, are a good thing and the
sample from the spec
for configuring a printer is a perfect example:

    {

That really should be:

    {
      "rel" : "http://example.net/rel/smtp-server",
      "href": "https://smtp.packetizer.com/config.dat"
    },

Where https://smtp.packetizer.com/config.dat is a file format that contains
the information in the properties, such as host, port, transport, etc.

I think that keeps the WebFinger story simple, the file format is basic
information about the entity you queried about (subject, alias, properties),
and then links related to that entity.

I don't believe WebFinger won't get wide adoption if you can't put
SMTP configuration
info directly into the WF response.

I don't believe WebFinger won't get wide adoption if you have to do
two requests to
find that SMTP configuration info.

I do believe WebFinger will get wide adoption if the format is as
simple as possible.

I would be fine with keeping the top level properties object.

> that?  I don't want to write that.  Was Tim volunteering?

Yes, I believe Tim was volunteering to do that, but he can answer for himself.

  -joe

---

From: Nat Sakimura <[email-masked]>
Date: Fri, 30 Nov 2012 00:11:54 +0900

Because otherwise you cannot have multiple rels of the same value.

On the other hand, I agree that it is easier to parse the way you
suggested.
In fact, the array ways of doing it is found in JSON Schema and
object way of doing it is found in HAL.

Cheers,

Nat

On Thu, Nov 29, 2012 at 7:54 AM, Mike Kelly <[email-masked]> wrote:

> extensions
> over
> by
> "object",
> an
> NOT

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en

---

From: Mike Kelly <[email-masked]>
Date: Thu, 29 Nov 2012 15:20:28 +0000

On Thu, Nov 29, 2012 at 3:11 PM, Nat Sakimura <[email-masked]> wrote:
> On the other hand, I agree that it is easier to parse the way you suggested.

Hi Nat,

The object way can accomodate multiple links with the same rel using
an array for rels that have multiple links. HAL works this way, i.e:

{
  links: {
    self: { href: "/" },
    widgets: [{
      href: "/widgets/1"
    },{
      href: "/widgets/2"
    }]
  }
}

Cheers,
M

---

From: Nat Sakimura <[email-masked]>
Date: Fri, 30 Nov 2012 00:30:53 +0900

Yes, and you know I like HAL (I emailed you a while ago to your
stateless.coemail address but did not get any response :-)

The problem I have though with the HAL way of doing it compared to JSON
Schema way is that in the later case, it is always the same way of doing it
while in the former case, the value of the rel will either be an object or
array depending on whether you have multiple hrefs.

Nat

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Nov 2012 07:50:41 -0800

+1 to everything Tim and Joe have said. Simpler is better.

Fwiw, the approach I took with JSON activity streams [1] was to use rel
values as member names to make client code more efficient, and have the
values be arrays of link objects to allow multiple links...

E.g....

{
  "blog": [
    {"href": "http://...", ...},
    {"href": "http://...", ...}
  ]
}

I know this part mostly comes down to a style choice, but this structure
ends up being very efficient when it comes to picking out just the link
relations you want while ignoring everything else.

- james

---

From: Melvin Carvalho <[email-masked]>
Date: Thu, 29 Nov 2012 17:02:17 +0100

> relations you want while ignoring everything else.
You may find this reference page valuable

http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples

It contains various json serialization standards

   - 1.2.1 Shared Example for Serialization Lineup
(Turtle)<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#Shared_Example_for_Serialization_Lineup_.28Turtle.29>
   - 1.2.2 Linked Data
API<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#Linked_Data_API>
   - 1.2.3 JRON<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#JRON>
   - 1.2.4 JSN3<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#JSN3>
   - 1.2.5 JSON-LD
(CURIEs)<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#JSON-LD_.28CURIEs.29>
   - 1.2.6 JSON-LD
(terms)<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#JSON-LD_.28terms.29>
   - 1.2.7 JTriples<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#JTriples>
   - 1.2.8 RDF/JSON<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#RDF.2FJSON>
   - 1.2.9 RDFj<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#RDFj>
   - 1.2.10 SPARQL Query Results in
JSON<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#SPARQL_Query_Results_in_JSON>
   - 1.2.11 Flat triples approach to RDF graphs in
JSON<http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples#Flat_triples_approach_to_RDF_graphs_in_JSON>

Essentially the common parts are part of the Entity Attribute Value model
(aka subject predicate object)
Activity streams is also a neat serialization with its own content type.

Personally I think JRD is one of the weaker serializations out there.
Though it seems incredibly tightly coupled to webfinger, for historical,
and perhaps some social, reasons.  I've yet to hear the full rationale for
this, articulated.