Subject: Re: [apps-discuss] New Version Notification for draft-nottingham-link-hint-00.txt

From: Mark Nottingham <[email-masked]>
Date: Thu, 4 Jul 2013 11:30:14 +1000

On 27/06/2013, at 10:24 AM, Erik Wilde <[email-masked]> wrote:
>>> 
>>> so my suggestion is not so much your (b) but my (c) ;-) fwiw, it seems that thew current draft uses overly complicated structures, for example, "formats" maybe just could be an array of formats?
>> Could you spell out an example?
> 
> afaict, "formats" (http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3.2) right now says says it's an object with the keys being media types, but the values are not specified. but maybe i am reading it wrong and where it says "The object" in the second and third paragraph it actually refers to the object that's a value of one of the keys?

Yes, I need to spell that out more completely. Thanks.

> hmmm, i guess that's what it means... i had been reading it wrong so far. but for a minute, let's just assume it's only media types, which is how i am using it in an example using link hints here: https://github.com/dret/I-D/blob/master/link-desc/ld-atompub-00.xml
> 
> so let's assume for a minute that this is just a list. then i would suggest is the following: the hint is defined as follows (stealing your structure here):
> 
> o  Hint Name: formats
> o  Description: Hints the representation type(s) that the target resource can produce and consume, using the GET and PUT (if allowed) methods respectively.
> o  Content Model: list
> o  Specification: [this document]
> Content MUST be a list, whose values are media types.
> 
> then, the term "list" in the content model must be defined somewhere. like i said, maybe we could say there are three "content models" hints support: single values, lists, key/value pairs. how a particular hint value would be serialized then would be up to the format where it's being represented.
> 
> - in JSON, you might represent them as string, array, something else.
> 
> - in XML, you might choose a mix of element/attribute designs. or you could go text-based such as my example (which is text-based because it uses JSON syntax right now)
> 
> none of these representations would be binding, they would just be one way of mapping the abstract link hint model into some concrete model. i guess the only exception for this would be how to represent links outside of media types, i.e. in HTTP. http://tools.ietf.org/html/draft-nottingham-link-hint-00#appendix-A could be changed then to map the abstract moden into a concrete JSON syntax (or whatever else looks like a good syntax choice to go into a Link header).

I'm all for that, IF we can be reasonably sure that the current data can fit comfortably into that simplified model.

The current hints that use "complex" objects are (keeping in mind that we've just started):
 - formats
 - links
 - accept-post (same format as formats)
 - auth-schemes

Formats and accept-post COULD specify a list of strings, and state that it's either a media type OR a profile URI. This means we'd need a separate representation format for profiles, which would need to convey a media type.

This is certainly possible, but the downsides I see are:
  - It's baking in profiles in at a pretty high level. I like some aspects of profiles, but they certainly haven't taken off in mindshare yet.
  - Parsing the string to check which it is is nasty.

For auth-schemes, we'd need to specify a tuple, probably. Not great, but OK. Extensibility would be right out the window, though, which may be significant for some schemes.

Links are fundamentally not possible without some really ugly mapping to a string, I think.

My concern is that this is starting not to meet my use cases for json-home, which is where link-hints comes from. 

While I could address this by making those things NOT link hints, but other "bumps" on json-home, it would make it significantly more complex. That seems like a poor tradeoff, considering that it's *possible* to map generic hints into XML, it's just not "pretty."

> as i see it, when i design media types that use link hints, it would be nice if i could expose them in a way that is as useful as possible for consumers of that media type. my example from above is from an XML design for link descriptions that i plan to base on link hints. if that means that the XML-oriented clients using this format need to include a general-purpose JSON parser, then that's certainly doable, but i don't think the link hints design has to be like that.

To be brutally frank (and I'm sure this isn't going to surprise you too much, dret ;) I don't see a lot of value in catering to the XML API market; it's dying, and introducing constraints on the JSON APIs seems like a bad tradeoff.

I absolutely acknowledge that JSON will one day face its own demise, and will be in a similar situation, but planning for that seems like premature optimisation to me.

> but again, of course my option (c) means that link hints have a predefined and probably small set of structures that hints can use to expose whatever they want to expose, and if they want to go beyond that, that's not covered by the link hint framework anymore.

Yes. That's what I'm struggling with. We're already seeing a number of places that chafe against these constraints, and we're just getting started.

What do other folks think?

Cheers,

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

---

From: Erik Wilde <[email-masked]>
Date: Fri, 05 Jul 2013 17:00:21 +0200

hello mark.

> Links are fundamentally not possible without some really ugly mapping to a string, I think.

i guess that's true. but i have to admit that i am struggling a bit with 
that specific hint anyway. it can hint at links you might find at the 
target resource. it may contain hints, so it can also contain link 
hints. so in theory, you could build a multi-level structure of links to 
be expected several link traversals away, right?

more generally speaking, i am having troubles rationalizing hints that 
give me some "preview" of the target resource. my personal mental model 
of link hints is that they constrain interactions with the target 
resource, but really don't tell you what to expect.

is http://tools.ietf.org/html/draft-nottingham-json-home-03#section-9 
(the separation into "resource" and "representation" hints in the home 
draft, where the link hint idea started) what might make te difference 
between hints talking about interactions, and hints talking about the 
result of an interaction?

> My concern is that this is starting not to meet my use cases for json-home, which is where link-hints comes from.

that would be bad, but again, i am struggling a bit with the hints that 
tell you what to expect, and not just what to do. my thoughts were that 
hints should just be about what to do; do you have a different model in 
mind?

> To be brutally frank (and I'm sure this isn't going to surprise you too much, dret ;) I don't see a lot of value in catering to the XML API market; it's dying, and introducing constraints on the JS…

yes, i am not overly surprised ;) but i am not really trying to optimize 
this for XML, i just try to make it more workable for non-JSON consumers 
in general. and i am still hoping that somebody will be able to point to 
prior decisions that were made in similar situations: are there IANA 
registries that are using JSON as a data model for their entries, and 
which other approaches were taken in cases where registries attempted to 
register structured entries? maybe we should just use ASN.1... ;-)

> I absolutely acknowledge that JSON will one day face its own demise, and will be in a similar situation, but planning for that seems like premature optimisation to me.

sure, and if the consensus is that it's ok to have JSON-based 
registries, then this is how it is. personally, i think i will then use 
serialized JSON in XML representations, which are a little less horrible 
to look at than generic JSON serialized in JSON.

> What do other folks think?

good point, so far it's just mark and me. anybody who faced similar 
design issues who could share their considerations and decisions?

thanks and 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: Graham Klyne <[email-masked]>
Date: Mon, 08 Jul 2013 11:24:21 +0100

Hi Erik, and Mark,

On 05/07/2013 16:00, Erik Wilde wrote:
>>> but again, of course my option (c) means that link hints have a predefined
>>> and probably small set of structures that hints can use to expose whatever
>>> they want to expose, and if they want to go beyond that, that's not covered
>>> by the link hint framework anymore.
>> Yes. That's what I'm struggling with. We're already seeing a number of places
>> that chafe against these constraints, and we're just getting started.
> good point, so far it's just mark and me. anybody who faced similar design
> issues who could share their considerations and decisions?

I'm interested in the json-home work, and I've had discussions with both of you 
separately about using RDF for something similar.  That's the route we followed 
in PROV-AQ (http://www.w3.org/TR/prov-aq/#provenance-query-service-description).

I haven't really been following this link-hint discussion, though I can see it's 
related to the home document in light of discussions we had about the role of 
link relations ("why" vs "how", etc).  In this general context, having some idea 
of what types are available to content negotiate seems useful.

Beyond that, for applications that choose to use RDF (in one of its available 
media types), or a similar generic format, to describe services might benefit 
from some additional indication of whether there is likely to be anything of use 
to them ... but as you pointed out this tends to increase coupling, trading REST 
flexibility for possible more efficient discovery.  This leaves me wondering if 
link hints might not be a form of premature optimization that might be better 
achieved through caching of responses?  (Just a thought, not a claim.)

[Later]

I just (re)read the draft, and it occurs to me that most of these hints are 
things that can or might be provided by header fields in a server response. 
That suggests a possibility that a generic data model for representing hints 
might usefully be based closely based on the HTTP/MIME header field model.  In 
many respects, the proposal's use of key-value pairs does make it closely 
aligned.  It seems to me that the main thing missing may be a model for 
representing a header (i.e. multiple header fields) within a header field - 
which I think is where JSON objects are being used.

#g
--