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

From: Mark Nottingham <[email-masked]>
Date: Mon, 10 Jun 2013 12:38:21 +0900

FYI.

Begin forwarded message:

> From: [email-masked]
> Subject: New Version Notification for draft-nottingham-link-hint-00.txt
> Date: 10 June 2013 12:38:04 PM GMT+09:00
> To: Mark Nottingham <[email-masked]>
> 
> 
> A new version of I-D, draft-nottingham-link-hint-00.txt
> has been successfully submitted by Mark Nottingham and posted to the
> IETF repository.
> 
> Filename:	 draft-nottingham-link-hint
> Revision:	 00
> Title:		 HTTP Link Hints
> Creation date:	 2013-06-10
> Group:		 Individual Submission
> Number of pages: 12
> URL:             http://www.ietf.org/internet-drafts/draft-nottingham-link-hint-00.txt
> Status:          http://datatracker.ietf.org/doc/draft-nottingham-link-hint
> Htmlized:        http://tools.ietf.org/html/draft-nottingham-link-hint-00
> 
> 
> Abstract:
>   This memo specifies "HTTP Link Hints", a mechanism for annotating Web
>   links to HTTP(S) resources with information that otherwise might be
>   discovered by interacting with them.
> 
> Note to Readers
> 
>   This draft should be discussed on the apps-discuss mailing list; see
>   [apps-discuss].
> 
> 
> 
> 
> The IETF Secretariat
> 

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

---

From: Erik Wilde <[email-masked]>
Date: Tue, 11 Jun 2013 16:11:43 -0700

>>    discovered by interacting with them.

generally speaking, i think this might become a very useful way how 
various services can expose more helpful links to clients, if they 
choose to do so, and if the clients are interesting in taking that 
information into account.

but i have one question about the general registry model: the current 
draft says that hints MUST have a name (very reasonable, of course), but 
also that hints MUST have their data model being defined in JSON.

http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-5.1

living in a world where we have JSON services, XML services, and RDF 
services, it seems that hard-coding a specific language data model into 
such a spec (without constraining it in any way) will limit the utility 
of such a registry. for example, in the Home Document draft, which is 
the original source of the link hint idea, the hints were hard-coded 
with very constrained data models. this made it relatively easy to 
expose them in a different syntax (in the XML Home Document draft):

http://tools.ietf.org/html/draft-wilde-home-xml-01#page-4

without getting too much into the details of this specific registry: 
what are the best practices about allowing/controlling language 
dependencies in registries? personally, i would feel more comfortable 
with having a registry that is of equal value to people regardless of 
their implementation language, but then again that means that the 
registry itself must define a "mini-language" of its own.

any pointers to similar situations and how they were resolved would be 
greatly appreciated. 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: Mark Nottingham <[email-masked]>
Date: Tue, 25 Jun 2013 14:17:59 +1000

Hi Erik, 

Sorry for the delay - just back home now.

> but i have one question about the general registry model: the current draft says that hints MUST have a name (very reasonable, of course), but also that hints MUST have their data model being defined in JSON.
> 
> living in a world where we have JSON services, XML services, and RDF services, it seems that hard-coding a specific language data model into such a spec (without constraining it in any way) will limit the utility of such a registry.

It needs *a* data model.

> for example, in the Home Document draft, which is the original source of the link hint idea, the hints were hard-coded with very constrained data models. this made it relatively easy to expose them in a different syntax (in the XML Home Document draft):
> 
> without getting too much into the details of this specific registry: what are the best practices about allowing/controlling language dependencies in registries?

Whoa, hold on - who said anything about a language? This is just the underlying data model; you can express it in a document however makes sense.

> personally, i would feel more comfortable with having a registry that is of equal value to people regardless of their implementation language

You're using "language" quite loosely here. 

> , but then again that means that the registry itself must define a "mini-language" of its own.

-1. Defining Yet Another Data Model as a political solution to avoid picking an existing one is sub-optimal at best.

Cheers,

---

From: Erik Wilde <[email-masked]>
Date: Mon, 24 Jun 2013 21:49:10 -0700

hello mark.

>> living in a world where we have JSON services, XML services, and RDF services, it seems that hard-coding a specific language data model into such a spec (without constraining it in any way) will l…

yes, that's definitely true. i think what i'm trying to figure out a 
first is whether there is any precedence of a registry requiring a JSON 
data model, or any other specific language for that matter, for a 
structured values. it seems it's mostly specific micro-syntaxes (if any 
structure beyond identifiers is required), but i am really wondering 
about what people have usually done in similar situations.

> Whoa, hold on - who said anything about a language? This is just the underlying data model; you can express it in a document however makes sense.

that's kind of true, but not really. since the draft allows *any* kind 
of JSON, if i had a non-JSON document format (let's say XML ;-) that 
wanted to be able to represent registry values in general, it needs to 
define a generic mapping from *any* kind of JSON to XML. that's 
technically possible, but not really what works well for any non-JSON 
document model.

i think this is my main argument: if you have a micro-syntax for the 
registry, you can map that much easier to something that maps reasonably 
well into a variety of document models. if you require JSON, and allow 
arbitrary JSON, the JSON bias translates into rather inconvenient models 
for any non-JSON language.

> You're using "language" quite loosely here.

maybe. and like i said above, apart from having implementation concerns 
about non-JSON formats, i am also really interested to learn about prior 
art: how was this problem approached/solved in other situations like this?

> -1. Defining Yet Another Data Model as a political solution to avoid picking an existing one is sub-optimal at best.

not sure. if JSON is #1 on the requirement list, then maybe define a 
well-defined subset of JSON, so that mappings into other languages don't 
need to be able to handle *any* JSON?

more specifically, what do the current hints actually need? it seems 
that the set of possibilities is actually rather small. for example, 
http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3.2 
says "Content MUST be an object, whose keys are media types, and values 
are objects", but what are the objects containing? maybe a simple array 
of media type strings would suffice? and then, if we can boil down the 
needs to "hints are strings or arrays of strings", then we can create 
good mappings for a variety of document models, and not just for JSON.

cheers,

dret.

---

From: Stephen Farrell <[email-masked]>
Date: Tue, 25 Jun 2013 10:36:38 +0100

Just had a a quick peek at this since we've seen a case where stuff went wrong because a registry contained structured data. Roughly: 1) can we have an early allocation to work with IEEE; 2) oops that bit there should've been a 1; 3) can we mark (1) as reserved and redo stuff? 

I think it's a mistake to ask IANA to handle structured data of any sort and this does that in spades.

As a question: what makes you think this wouldn't be very likely to result in erroneous registrations? (Damaging the effectiveness of this registry but also possibly the IANA function, a bit)

S

On 25 Jun 2013, at 05:17, Mark Nottingham <[email-masked]> wrote:

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

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 25 Jun 2013 19:46:10 +1000

Please have a look at the draft; the level of detail in the registrations is "a number" or "a list" or (infrequently) "an object" -- roughly on par with saying that a field in a registry is "an integer," which is quite common in IANA-land.

---

From: Stephen Farrell <[email-masked]>
Date: Tue, 25 Jun 2013 11:28:56 +0100

> Please have a look at the draft; the level of detail in the registrations is "a number" or "a list" or (infrequently) "an object" -- roughly on par with saying that a field in a registry is "an int…

Ah fair enough. (Serves me right for reading & replying via phone
from a bus:-)

I misread it as you wanting the registry to contain [ "foo": "bar" ]
but you just want the registry to contain "array". Given you'd need
to read the spec I'm not sure its that much use to have that in the
registry, but I agree its not harmful.

Sorry for the distraction,
S.

---

From: Erik Wilde <[email-masked]>
Date: Tue, 25 Jun 2013 09:45:17 -0700

hello mark.

>> As a question: what makes you think this wouldn't be very likely to result in erroneous registrations? (Damaging the effectiveness of this registry but also possibly the IANA function, a bit)

i really like the places where it says "a number" and "a list", because 
these concepts can be easily mapped into pretty much any representation. 
when it says "an object", however, that's an entirely different matter. 
it would be great for the registry to really be clear about what kind of 
structures to expect for hints (single values, value lists, and maybe 
lists of key/value pairs or something along those lines), and then the 
registry would not depend on a specific language.

cheers,

dret.

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 26 Jun 2013 16:51:32 +1000

On 26/06/2013, at 2:45 AM, Erik Wilde <[email-masked]> wrote:

> i really like the places where it says "a number" and "a list", because these concepts can be easily mapped into pretty much any representation. when it says "an object", however, that's an entirely different matter. it would be great for the registry to really be clear about what kind of structures to expect for hints (single values, value lists, and maybe lists of key/value pairs or something along those lines), and then the registry would not depend on a specific language.

It's certainly possible to map the JSON data model into XML; it just won't make XML people happy, because it'll have lots of elements named "object" and "array" (although I see a fair amount of "native" XML like this anyway!).

Likewise for (most any, since JSON is pretty basic) other data models.

I very much agree that it would be good to not have a dependency upon the JSON data model here. However, I don't see a way to avoid that, without either a) using another data model with exactly the same problem, or b) prohibiting any structured information.

AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?

Regards,

---

From: Erik Wilde <[email-masked]>
Date: Wed, 26 Jun 2013 10:25:32 -0700

hello mark.

> It's certainly possible to map the JSON data model into XML; it just won't make XML people happy, because it'll have lots of elements named "object" and "array" (although I see a fair amount of "na…

sure, with enough effort, anything can be mapped to anything. my point 
was to have something for the link hints that can be mapped into more 
useful structures for any target mapping, and not just for JSON.

> AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?

i think there are three possibilities:

- pick a generic format (such as JSON) as allow anything it allows. this 
makes things great for JSON and not so great for non-JSON.

- be structure agnostic (hints are strings) and then hints will probably 
define their own mappings into string-based structures (using regexes 
and usual patterns such as whitespace- or comma-separated lists). this 
might be bad because then parsing a hint's value needs to be done on a 
per-hint basis.

- pick a small set of structures allowed such as the ones i suggested 
above (single values, value lists, and maybe lists of key/value pairs) 
and require that any hint is defined in terms of this more restricted 
model. this maps better to many formats, but you're stuck with the 
choices you make.

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?

it's clearly a trade-off between allowing arbitrarily structured hints 
(in which case you need some generic metamodel) or predefining the kinds 
of structures that hints can use (in which case you can remove the 
dependency on a particular generic metamodel). i am still trying to 
understand how that problem has been solved in similar cases. i assume 
this is not the first (proposed) IANA registry that has to deal with 
this tradeoff; does anybody have pointers to this has been handled in 
similar cases?

thanks and cheers,

dret.

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 27 Jun 2013 09:40:08 +1000

On 27/06/2013, at 3:25 AM, Erik Wilde <[email-masked]> wrote:

> sure, with enough effort, anything can be mapped to anything. my point was to have something for the link hints that can be mapped into more useful structures for any target mapping, and not just for JSON.
> 
> - pick a generic format (such as JSON) as allow anything it allows. this makes things great for JSON and not so great for non-JSON.

Yep, this is where we're at.

> - be structure agnostic (hints are strings) and then hints will probably define their own mappings into string-based structures (using regexes and usual patterns such as whitespace- or comma-separated lists). this might be bad because then parsing a hint's value needs to be done on a per-hint basis.

I'm -1 on this; it hasn't worked out so well for HTTP headers (and in fact a significant number of people are agitating to just define new headers in JSON) nor for media type parameters.

> - pick a small set of structures allowed such as the ones i suggested above (single values, value lists, and maybe lists of key/value pairs) and require that any hint is defined in terms of this more restricted model. this maps better to many formats, but you're stuck with the choices you make.
> 
> 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?

> it's clearly a trade-off between allowing arbitrarily structured hints (in which case you need some generic metamodel) or predefining the kinds of structures that hints can use (in which case you can remove the dependency on a particular generic metamodel). i am still trying to understand how that problem has been solved in similar cases. i assume this is not the first (proposed) IANA registry that has to deal with this tradeoff; does anybody have pointers to this has been handled in similar cases?
> 
> thanks and cheers,

Cheers,

---

From: Erik Wilde <[email-masked]>
Date: Wed, 26 Jun 2013 17:24:38 -0700

hello mark.

> I'm -1 on this; it hasn't worked out so well for HTTP headers (and in fact a significant number of people are agitating to just define new headers in JSON) nor for media type parameters.

i agree that this is not such a great way to go. it makes things easy in 
the short run, but harder in the long run. in particular, it means that 
the same concepts ("a list") may be serialized differently in different 
hints (a "comma-separated" one, a "space-separated" one), which makes it 
harder to build general facilities for hints.

> 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? 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).

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.

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.

cheers,

dret.

---

From: Matt McClure <[email-masked]>
Date: Wed, 26 Jun 2013 08:04:16 -0400

On Jun 26, 2013, at 2:51 AM, Mark Nottingham <[email-masked]> wrote:
> Can you suggest how to convey the information without using structured data?
> 
Is it just an issue of terminology? If so, using the name of an abstract data type instead of the JSON name for it is an option. Something like associative array, map, or dictionary.

-- 
http://matthewlmcclure.com
http://about.mapmyfitness.com__,_._,___