Subject: [apps-discuss] feedback draft-nottingham-json-home

From: Nick Lombard <[email-masked]>
Date: Fri, 17 Aug 2012 20:11:00 +0200

Good evening from a starry-skied South-Africa this be my maiden ietf
post so n00b alert, please mind your toes, no special treatment
required all std disclaimers apply.

With reference to I-D[2] of json-home from github.com/mnot/I-D since
commit Aug 06, 2012

Example JSON document completed, up to date, auth-req inclusive, plus
additional ideas can be found at https://github.com/mnot/I-D/issues/3
To serve as visual aid in support of these suggestions.

1. relation type URIs
There appears to be an initial resistance accepting the foreign usage
of URLs as rel values, prompting explanation. Partly due to the
additional presence of links or endpoints expressed in the same
notation.
May I suggest a less ambiguous approach utilizing URNs (RFC 2141) instead.
Motivation :
 a. URNs are generally understood to not have endpoints as apposed to URLs
 b. to make a clear distinction cognitively between links and relations
 c. to decrease the initial "What The?" factor, ease understanding
based on common usage and hopefully expedite acceptance.

2. Instead of a new relation type "docs" (sec 5.8) won't using
existing relation "help" serve the same purpose?
[W3C.REC-html401-19991224](http://www.w3.org/TR/html5/links.html#link-type-help)

3. prepend resources collection with host || api information a la
host-meta RFC 6415
ie. expires, title, copyright, version, license, property, author, etc

4. Additional RFCs to consider
a. Paging and Archiving RFC 5005 also RFC 5988
b. Simple Version Navigation RFC 5829
c. Subscribing to Changes RFC 5989
d. Disclosure RFC 6579
e. License Extension RFC 4946

5. Reference implementation.
I will be implementing an interpreter in php - Pretty JSON Home Page
or PJHP to facilitate a html representation of a home document for
nose to the ground API exploration and purposes of documentation. I
know there has been requests for for an example implementation may I
use this opportunity to announce my intentions and invite everyone
interested to join forces.

A project has beet registered at https://github.com/nickl-/pjhp and
the issue queue is open for suggestion, requests and pledges. Everyone
is welcome.

Typo: s/type\stype/type/ at line 356 in draft-nottingham-json-home-02.xml
Would it help if I submit pull requests on github for these?

On that note if you notice anything I need to improve on please don't
hesitate to let me know so I may learn the ropes. @Mark, thank you for
this initiative if this post only serve to as indication that there is
interest and we appreciate your effort. Please don't feel obliged to
consider anything I've listed if it even has the slightest chance to
slow the process that would be worse.

Regards,
nickl-

---

From: Erik Wilde <[email-masked]>
Date: Fri, 17 Aug 2012 18:09:24 -0700

hello nick.

> based on common usage and hopefully expedite acceptance.

for the link relation types that will be registered once the draft is 
approved, they will show up as regular names because they will then be 
well-known relation types in the IANA registry 
(http://www.iana.org/assignments/link-relations/link-relations.xml). so 
no URIs there.

for all other link relation types used in a home document, it is up to 
the document's publisher to decide how to identify them. if people 
prefer URNs, they're free to do so, but since RFC 5988 does define link 
relation types to be identified by URI (and not URN), there really is no 
option to change that retroactively.

> [W3C.REC-html401-19991224](http://www.w3.org/TR/html5/links.html#link-type-help)

interesting point. there's always a bit of leeway in interpreting link 
relation type semantics, but personally, i would "help" expect to be a 
little different than "docs", maybe more providing a helpful collection 
of resources, rather than just a list of reference materials.

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: Nick Lombard <[email-masked]>
Date: Sat, 18 Aug 2012 20:45:23 +0200

Hi Erik.

Thank you for the explanation apologies for any confusion. I just have
a few questions if I may:

On 18 August 2012 03:09, Erik Wilde <[email-masked]> wrote:
> for all other link relation types used in a home document, it is up to the
> document's publisher to decide how to identify them. if people prefer URNs,
> they're free to do so, but since RFC 5988 does define link relation types to
> be identified by URI (and not URN), there really is no option to change that
> retroactively.

I was only referring to these relation type occurrences and came from
the assumption:

RFC 3986 1.1.3 URI, URL and URN concludes with
Future specifications and related documentation should use the general
term "URI" rather than the more restrictive terms "URL" and "URN" `

Which lead me to believe that URNs and URLs are collectively URIs, now
I may be wrong but since the provisions laid out in RFC 5988 for
Extension Relation Types (4.2) does not indicate a preference for any
specific URI notation therefor any notation should be allowed.

Are you saying that URI and URN are mutually exclusive or that URLs
are URIs but URNs are not? I am confused now and I thought this was
cleared up by RFC 3986, please can you explain.

Based on RFC 3986 the minimum required for a valid URI is a scheme and I quote:

RFC 3986: 3. Syntax Components
The scheme and path components are required, though the path may be empty

You may agree that relation types are nothing more than special URI
schemes registered with IANA under a different banner and since
there's several precedence of unregistered schemes in use, users may
use any word they want, as a valid custom URI scheme with empty path
representation. I also cant find any mention that new relation types
defined in I-D are compelled to be register with IANA which pose no
restriction to use URN, URL or both nor anything else you may prefer
as examples. Where did I go wrong?

Is this a general practice to allow anything to be used as the
implementer sees fit while the RFC is unable to specify nor even hint
towards the desired scope appropriately?

I found more motivations why the use of URN is more appropriate here:
 * the main reason we employ this is to have a URI that will stay
unique and not be influenced by specifics like location or transport
so that these may change without loss of integrity. URNs have none of
these influences and are immutable which makes them perfect.
 * URN has the unique ability to indicate a relation with other URNs
as can be seen in the example on the URN employed for href-vars. This
relation is not self evident when using an URL.

Although I also found something else which may pose a bigger concern in general.
How does the following excerpt affect our use of relation types here:

RFC 5988
Relation types SHOULD NOT infer any additional semantics based upon
the presence or absence of another link relation type, or its own
cardinality of occurrence.

> little different than "docs", maybe more providing a helpful collection of
> resources, rather than just a list of reference materials.

RFC 5988 explains in section 4.1. "Registered Relation Types" that the
"types can be registered as tokens for convenience and/or to promote
reuse" it goes on to say the name "SHOULD be appropriate to the
specificity of the relation type; [..] so that more general names are
available for less specific use.". Why would you suggest that help is
not sufficiently general enough that we would require docs as well?
What about other distinctions then, I may require tutorial, guide,
lesson, advice, assist, etc. which neither doc nor help would then
satisfy hence, are you suggesting we should registered all of these as
well?

Humbly yours...
---
nickl-

---

From: Erik Wilde <[email-masked]>
Date: Sat, 18 Aug 2012 14:20:25 -0700

hello nick.

> cleared up by RFC 3986, please can you explain.

it's actually rather simple, the most general concept is that of a URI, 
and RFC 3986 defines this concept. URIs have schemes registered with 
IANA (the list is avilable at 
http://www.iana.org/assignments/uri-schemes.html), and one of them is 
the urn: scheme, defined and (retroactively) registered by RFC 2141. RFC 
3406 adds a registry of URN namespaces managed by IANA (available at 
http://www.iana.org/assignments/urn-namespaces/urn-namespaces.xml), 
meaning that the space of URNs how is a managed subtree of the entire 
URI tree. all of this means that a URN is nothing but a URI using the 
urn: URI scheme.

coming back to the starting point: whether a URI is considered to be 
just an identifier or something that dereferences is just a question of 
context. it's perfectly fine for URIs to not be dereferencable, and 
specs are even free (such as RFC 5988) to say that for URIs in certain 
places of the data model, no assumption about being dereferencable 
should be made. people creating identities for such a URI have the 
freedom to still use a URI that *may* be dereferencable, such as an HTTP 
URI, or they can use a URI that by definition is not dereferencable, 
such as a URN. both are valid choices, and if i were making such a 
choice, i would go with an HTTP URI and try to provide useful 
information at that URI, just in case somebody is actually typing it 
into a browser, and if i cannot do this anymore because i for example 
lost control over the DNS domain, then i could still put up an 
information page somewhere else and allow people to find it through a 
search engine.

in short, home documents will contain to classes of link relation types:

- the relation types defined by the draft/RFC will be registered with 
IANA (added to 
http://www.iana.org/assignments/link-relations/link-relations.xml once 
the RFC is published) and then will be simple keywords (i.e., no URIs).

- the relation types specific for some home document are picked by the 
publisher of the home document. two things can happen:

-- if it's just an application-specific link relation, the relation type 
MUST be a URI, but whether the publisher chooses to use HTTP URIs or 
URNs is up to the publisher. i would recommend HTTP URIs and making some 
attempt to provide information at those URIs.

-- if some concepts solidify and people are relating the same things 
over and over again, maybe some later RFC will add relation types for 
those concepts, and then those would be registered with IANA as well and 
thus would show up as simple keywords (once registered).

i hope this clarifies things a little. cheers,

dret.

---

From: Nick Lombard <[email-masked]>
Date: Mon, 20 Aug 2012 22:00:46 +0200

Hi Erik,

The way you manage to explain things is truly inspiring. Thank you again.

Although these concepts may come easy for us its not like that for
Everyman though. There seems to be an emergent pattern of misgiving,
as can be seen in the following example, for HTTP URI as link
relations, you may have noticed this as well. Several equally valid
examples exist, by no means should this be considered unique or
exceptional.

http://bill.burkecentral.com/2012/05/11/json-home-format-resource-discovery/

The original motivation behind my post is still to raise awareness of
this anomaly and to discuss plausible strategies for breaching the
gap.

> no assumption about being dereferencable should be made.

Delusion to deny that a preconceived notion exist of what http://,
ftp:// or mailto:// means to Everyman. We've heard the saying "What
does it do?" or "What application can I use to open it?" about less
known URI like rtsp:// for example. So strong an expectation it should
do something that unresolvable is considered broken.

I am not suggesting we change the design or adopt the popular fallacy,
only that we recognise the memes and make every effort to facilitate
comprehension. I believe through slightly more elaborate example
represented by the most adaptable forms available  would go a long way
to avoid confusion, embarrassment or worst, incorrect adoption, when
attempting to contradict establishment.

Comparing the following two examples:

1. HTTP URI
{
    "resources": {
      "http://example.org/rel/widgets": {
        "href": "/widgets/"
      },
      "http://example.org/rel/widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "http://example.org/param/widget"
        }
}

2. URN
{
    "resources": {
      "urn:exampleorg:widgets": {
        "href": "/widgets/"
      },
      "urn:exampleorg:widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "urn:exampleorg:param@widgets"
        }
}

Would you agree that the 1st example poses more cognitive resistance
than the 2nd. After smoothing the transition by presenting #2 first we
may have more success explaining the purpose of URI, that it may or
may not be dereferencable and that we actually recommend the use of an
HTTP URI instead, but don't avoid elaborating why. Maybe a suggestion
of what an appropriate response lookup may produce. Avoidance would
only risk anxiety but alleviate the uncertainty and we may just foster
the creativity we were after in the first place. Following this up
with a more elaborate example may even employ HTTP URI without
bewildering the audience.

To conclude: I am only referring to what Erik so skilfully dubbed "the
relation types specific for some home document" and not any other link
relation types referenced by this I-D. I am only suggesting the use of
the most appropriate medium to get the correct message across not that
we change the message. I am asking that we be conscious of the
established understanding and to take extra precautions when trying to
influence them.

The goal: To get the desired message across with the least amount of
resistance or room for misinterpretation.

Keep up the good work, your legacy is shaping our futures and we owe
you a debt of gratitude. Much appreciated.

Regards,
nickl-