Subject: [core] link hierarchies and RFC 5785

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 26 Jan 2011 19:23:17 -0700

After today's meeting I thought some more about the well-known URIs
we're using. Some of them (the "hierarchical" URIs) are not in
conformance with RFC 5785 (BTW I think that RFC needs to be a normative
reference because one needs to understand its concepts in order to
understand the link-format spec).

RFC 5785 states:

   A well-known URI is a URI [RFC3986] whose path component begins with
   the characters "/.well-known/", and whose scheme is "HTTP", "HTTPS",
   or another scheme that has explicitly been specified to use well-
   known URIs.

   Applications that wish to mint new well-known URIs MUST register
   them, following the procedures in Section 5.1.

   For example, if an application registers the name 'example', the
   corresponding well-known URI on 'http://www.example.com/' would be
   'http://www.example.com/.well-known/example'.

   Registered names MUST conform to the segment-nz production in
   [RFC3986].

There are two things to note here:

1. We might need to explicitly state somewhere that the 'coap:' scheme
uses well-known URIs.

2. More significantly, the segment-nz production from RFC 3986 is:

      segment-nz    = 1*pchar
      pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
      unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
      pct-encoded   = "%" HEXDIG HEXDIG
      sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                    / "*" / "+" / "," / ";" / "="

Because "/" is not allowed in segment-nz, the following is not a legal
name for a registered well-known URI:

   core/sensors

Thus the following example in the link-format draft is problematic or
plain illegal:

   REQ: GET /.well-known/core/sensors

As a result, I think we might need to reconsider how we are handling
hierarchies.

Peter

--
Peter Saint-Andre
https://stpeter.im/

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 27 Jan 2011 07:31:12 +0100

Indeed.  Thanks, Peter, for correcting my misconception in the call.

So, what is the purpose of the /.well-known registry?
Registering single path components (segment-nz) that then are used to form URIs from authorities (host/port pairs).
The motivating example given is the well-known "robots.txt" that crawlers expect at http://authority/robots.txt -- .well-known was meant as a jail to stop more of these (e.g., we now have "cross-domain.xml") from polluting the URI space and essentially restricting the server's choice of how to name their URIs.

And that's really the point -- servers MUST have free reign on their URI space.

I'm not sure why 5785 is mute on what servers may do with the /.well-known path prefix and continuations other than a single segment-nz.
It says

(So we indeed need to point out in core-coap that we are among the latter.)

But it also says:

So, /.well-known/core/foo can neither be registered nor is it really available for us because of the definition of a well-known URI.
I read the intention as "servers are not free to allocate random stuff here".  I would be uncomfortable with a server deciding to offer a nested link-format resource under "/.well-known/core/foo", even if "core/foo" cannot be registered under 5785.

I don't think we should incite server implementers to do so.
There is no gain from using /.well-known/core/sensors instead of /sensors/index.links or some such.
Instead, we should point out that /.well-known is *not* meant for unregistered URIs.
Let the server organize its space (and maybe choose a short URI if desired).  And let's keep /.well-known clean.

That also makes 5785 non-normative again, as it only tells *us* spec-writers how to do our work, not the server implementers.

Gruesse, Carsten

PS.: By the way, maybe we should define a file extension for link-format resources.
(And having a common expectation on how something like this is named, such as we expect to find an index.html on many HTTP servers that serve HTML, is helpful for debugging.)

---

From: [email-masked]
Date: Thu, 27 Jan 2011 10:03:40 +0100

Hi Carsten

>Let the server organize its space (and maybe choose a short URI if 
desired).  And let's keep /.well-known clean.

+1

>(And having a common expectation on how something like this is named, 
such as we expect to find an index.html on many HTTP servers that serve 
HTML, >is helpful for debugging.)

I don't understand why you need a sort of implicit name. Why not let the 
server explicitly name the index resource in /.well-known/core?
What option from the following ones do you have in mind? Personally I like 
3).

1)
REQ: GET /.well-known/core
RES: 200 OK
</gps>;n="GPS position",
</fnc>;rel="index";n="Geofence list";ct=40,
</alrm>;rel="index";n="Pending alarms";ct=40;obs,

REQ: GET /fnc/idx.lk
RES: 200 OK
</fnc/1>;ct=41,
</fnc/2>;ct=41;sz=200,

2)
REQ: GET /.well-known/core
RES: 200 OK
</gps>;n="GPS position",
</fnc/idx.lk>;rel="index";n="Geofence list";ct=40,
</alrm/idx.lk>;rel="index";n="Pending alarms";ct=40;obs,

REQ: GET /fnc/idx.lk
RES: 200 OK
</fnc/1>;ct=41,
</fnc/2>;ct=41;sz=200,

3)
REQ: GET /.well-known/core
RES: 200 OK
</gps>;n="GPS position",
</fnc>;rel="index";n="Geofence list";ct=40,
</alrm>;rel="index";n="Pending alarms";ct=40;obs,

REQ: GET /fnc
RES: 200 OK
</fnc/1>;ct=41,
</fnc/2>;ct=41;sz=200,

4)
REQ: GET /idx.lk
RES: 200 OK
</gps>;n="GPS position",
</fnc>;rel="index";n="Geofence list";ct=40,
</alrm>;rel="index";n="Pending alarms";ct=40;obs,

REQ: GET /fnc
RES: 200 OK
</fnc/1>;ct=41,
</fnc/2>;ct=41;sz=200,

Last question. How to structure a discovery repository without a 
/.well-known/core hierarchy?
1) A device can POST directly on /.well-known/core and the repository 
creates a new resource but not under /.well-known/core.
2) Or the device must start with a GET on /.well-known/core to learn the 
entry point of the repository service and then send a POST on that 
resource?

Matthieu

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 27 Jan 2011 10:27:38 +0100

On Jan 27, 2011, at 10:03, [email-masked] wrote:

> I don't understand why you need a sort of implicit name.

That's not what I said.
We should do full HATEOAS as you proposed.

I just think it would *also* be useful to establish some conventions that might help in debugging.
But these are not for machine interpretation.

Gruesse, Carsten

---

From: Zach Shelby <[email-masked]>
Date: Thu, 27 Jan 2011 11:28:23 +0200

> (So we indeed need to point out in core-coap that we are among the latter.)

Yep, and there RFC5785 would be normative I would think. I will make a ticket.

> I read the intention as "servers are not free to allocate random stuff here".  I would be uncomfortable with a server deciding to offer a nested link-format resource under "/.well-known/core/foo",…

These sub-resources are dynamic, but I see the point.

> Let the server organize its space (and maybe choose a short URI if desired).  And let's keep /.well-known clean.

 OK, I can live with leaving out the hierarchy recommendation from link-format if we want to be careful with RFC5785. 

Does anyone have an issue with removing the hierarchy? At least I would have liked to be able to build up a resource directory under /.well-known/core on a proxy at least. 

> That also makes 5785 non-normative again, as it only tells *us* spec-writers how to do our work, not the server implementers.

We just need to be explicit that /.well-known/core is a single resource and the server MUST NOT create sub-resources there.

> (And having a common expectation on how something like this is named, such as we expect to find an index.html on many HTTP servers that serve HTML, is helpful for debugging.)

Interesting idea, but in my opinion we don't need a .link style suffix for those resources, I think it is enough that the content-type and relation is indicated for that resource in /.well-known/core as Matthieu pointed out.

Zach

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

-- 
Zach Shelby, Chief Nerd, Sensinode Ltd.
http://zachshelby.org  - My blog "On the Internet of Things"
http://6lowpan.net - My book "6LoWPAN: The Wireless Embedded Internet"
Mobile: +358 40 7796297

---

From: Zach Shelby <[email-masked]>
Date: Thu, 27 Jan 2011 11:34:59 +0200

Hi,

> What option from the following ones do you have in mind? Personally I like 

Sure, 2 and 3 would both be legal and really up to the server. You can name your index fcn.lk or fcn.link if you like. I agree that /.well-known/core is the right entry point. 1 is broken because /fcn/idx.lk is not listed in the link list.  

> entry point of the repository service and then send a POST on that 

That is an issue that bothers me too. I would probably do 1) in order to avoid forcing nodes to first discover where the directory entry point is. Or a resource directory could register its own well-known URI e.g. "/.well-known/core-rd". 

Zach

---

From: "Stok, Peter van der" <[email-masked]>
Date: Fri, 28 Jan 2011 09:28:25 +0100

Dear all,

The recent discussion on /.well-known/core creates a new point of view with respect to the handling of standards which describe the representations of the services and devices delivered by a CoAP host.

If I understand correctly /.well-known/core returns ALL resources of the host and nothing more, and cannot be used to reserve other names in a hierarchical fashion hanging on /well-known/core.

My personal wish is that CoAP can be used to transport service and device representations which are specified by existing and possibly future standardization bodies or alliances.
To support interoperability naming conventions should adhere to the same syntax and conventions, and I quite agree that these conventions are the responsibility of the organization describing them.
I also can imagine that such an organization specifies how this is handled in the name space of a CoAP host. However, too much freedom may give problems between different standardization bodies, assuming that more than one standard will be present.

So I like to encourage that the CoAP draft says something about how these different representation standards can be recognized to be present on the host.

Some suggestions are (given that XXX stands for BACnet, KNX, ZigBee, DALI, oBIX, etc....):
A path for a given standard is preceded by /representation/XXX/name
Or is preceded by /XXX/name (is shorter)
Or is given by /name but with d="XXX" as link extension to be returned by resource query.

I have no preference for any syntax, as long as there is a recommendation in the CoAP draft on how to introduce the representation type.

All these suggestions do not reserve any mnemonics, so no involvement by IANA. This may lead to name clashes, but I have no idea how likely that is. Anyone has a better suggestion while at the same time maintaining the possibility to reserve mnemonics?

Peter van der Stok

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Zach Shelby
Sent: Thursday 27 January 2011 10:35
To: [email-masked]
Cc: core WG; [email-masked]
Subject: Re: [core] link hierarchies and RFC 5785

Hi,

On Jan 27, 2011, at 11:03 AM, [email-masked] wrote:
>
>> PS.: By the way, maybe we should define a file extension for
>> link-format
> resources.
> such as we expect to find an index.html on many HTTP servers that
> serve HTML, >is helpful for debugging.)
>
> I don't understand why you need a sort of implicit name. Why not let
> the server explicitly name the index resource in /.well-known/core?
> What option from the following ones do you have in mind? Personally I
> like 3).

> 2) Or the device must start with a GET on /.well-known/core to learn
> the entry point of the repository service and then send a POST on that
> resource?

Zach

The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

---

From: Paul Duffy <[email-masked]>
Date: Fri, 28 Jan 2011 11:51:26 -0500

Would IANA assigned Private Enterprise Numbers suffice?

On 1/28/2011 3:28 AM, Stok, Peter van der wrote:
> ...

---

From: "Stok, Peter van der" <[email-masked]>
Date: Mon, 31 Jan 2011 09:05:46 +0100

thanks for the suggestion, but can you elaborate a bit?

peter