Subject: [Uri-review] Request to review coap: scheme

From: Klaus Hartke <[email-masked]>
Date: Tue, 25 Jan 2011 21:07:08 +0100

Hi,
draft-ietf-core-coap [1] defines the coap: URI scheme. I would be
grateful if you could review sections 6 and 11.4.

Thanks,
Klaus

[1] http://tools.ietf.org/html/draft-ietf-core-coap-04

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Tue, 25 Jan 2011 21:31:25 +0100

>grateful if you could review sections 6 and 11.4.

Well, briefly:

It would be helpful if you could give some context for people who don't
want to read through all the 75 pages. For instance, what is the purpose
of section 6.3? How URIs are parsed is already defined in RFC 3986 and
the text is inconsistent with RFC 3986. For instance, RFC 3986 defines
that the host component is always UTF-8 encoded, but the result of the
algorithm in the draft is that the "Uri-Host Option" is a sequence of
bytes.

The draft does not seem to define how to handle the host when it is an
empty string, though I did not try hard to debug the algorithms.

The Encoding Considerations in the registration form should talk about
internationalization. I could not immediately find discussion of, say,
handling non-ascii query strings.

It seems that a URI scheme registration in a Standards Track document
would have to assign the IETF/IESG as change controller (RFC 4395, 5.3)
but I am not sure what the common practise there is.

It seems a bad idea to me to have the URI scheme syntax and semantics
discussion and the form this far apart in the document. At the least the
beginning of 11.4 should say something about the purpose of the scheme
and have a reference to the more elaborate discussion earlier in the
document.

As an aside, it might be a good idea to have [email-masked] review
the "Media Type Registry" defined in the document. I am also worried by
"Correct examples from Table 8 include application/link-format,
application/atom+xml and application/x-obix-binary" since one of these
types cannot by registered and another one isn't registered, though I
see there is a draft for the unregistered one.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: Klaus Hartke <[email-masked]>
Date: Tue, 25 Jan 2011 22:59:19 +0100

Hi Bjoern,

thanks for reviewing this so quickly.

Bjoern Hoehrmann wrote:
> of section 6.3?

Sure.

coap URIs are used to identify and locate resources that are
potentially accessible over the Constrained Application Protocol
(CoAP). The semantics of a coap URI are essentially the same as of an
http URI, the main difference being in how the resource is accessed
(using CoAP instead of HTTP). The syntax is identical apart from the
scheme component ("coap") and the userinfo subcomponent (which is
syntactically disallowed):

coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]

Like in HTTP, CoAP clients operate on resources identified by a coap
URI by sending a request (GET, POST, PUT, DELETE) to a server. The
request includes the request URI. HTTP uses the Request-Line and Host
header field for this. CoAP uses compact, binary options instead, and
the request URI is specified by combination of the Uri-Host, Uri-Port,
Uri-Path and Uri-Query Options.

A CoAP client needs to parse the request URI, create the list of Uri-*
Options to be included in the request, and convert the options to a
sequence of bytes to be sent across the wire. The goal is to minimize
the number of bytes required, so default values allow some of the
options to be omitted in the most common scenarios, and splitting the
URI into multiple options alleviates the need to escape delimiter
characters.

A CoAP server needs to be able to reconstruct the request URI from the
Uri-* Options in a request.

(Appendix C shows some examples of Uri-* Options and how they are
combined to a coap URI.)

> How URIs are parsed is already defined in RFC 3986 and
> the text is inconsistent with RFC 3986.

Maybe the term "parsing" is misleading here? The purpose of section
6.3 is to give an algorithm for how to create the list of Uri-*
options to be included in a CoAP request, given a coap URI.

> For instance, RFC 3986 defines

The intention is follows:

- The value of the Uri-Host, Uri-Path and Uri-Query Option is a
sequence of Unicode characters ("string"). When sent across the wire,
it is encoded using UTF-8.
- The value of the Uri-Port is a non-negative integer. When sent
across the wire, it is encoded using the binary format specified in
Appendix A.

The result of the algorithm should be that the value of the Uri-Host
Option is a string, which will be turned into a sequence of bytes.

Would it help if section 6.3 step 5 ended in
"...  and then converting all percent-encodings ("%" followed by two
hexadecimal digits) to the corresponding characters."
instead of
"... and then converting each percent-encoding ("%" followed by two
hexadecimal digits) to the corresponding byte."
to make the intention more clear?

> empty string, though I did not try hard to debug the algorithms.

When splitting the request URI into the Uri-* Options, the host cannot
empty, because section 6.1 requires that "The host MUST NOT be empty."

When combining the Uri-* Options back to a URI, the host will never be
empty, because in case the Uri-Host Option is absent a default value
will be used (namely the IP address of the server).

> handling non-ascii query strings.

If I understand RFC 3986 correctly (which I probably do not), then a
path segment and a query string can consist of any Unicode character.
Apart from a small set of characters (path segment: unreserved,
sub-delims, ":", "@"; query string: unreserved, sub-delims, ":", "@",
"/", "?") , these are all written in percent-encoded form. Should the
draft explicitly say that it makes no restrictions on path segments
and query strings beyond RFC 3986?

> but I am not sure what the common practise there is.

draft-ietf-core-coap isn't an IESG-approved document yet. Looking at
RFC 4395, Section 3 it looks like the authors/editors of a draft are a
good choice for change controller. But I'm not sure as well.

Klaus

---

From: Mykyta Yevstifeyev <[email-masked]>
Date: Wed, 26 Jan 2011 08:49:29 +0200

> grateful if you could review sections 6 and 11.4.
Klaus, all,

Firstly let me comment the URI registration template.

>   URI scheme name.
>        coap
>     Status.
>        Provisional.
I really wonder why did you put Provisional here.  The Intended status, 
as well as I know is Standards Track, so Permanent will be suitable here 
more.
>     URI scheme syntax.
>        Defined inSection 6.1  <http://tools.ietf.org/html/draft-ietf-core-coap-04#section-6.1>.
Section 6.1 contains the following:

However you may easily reuse the 'authority' rule from RFC 3986 here.  
Or there are some reasons you didn't do this?
>     URI scheme semantics.
>        The "coap" URI scheme provides a way to identify resources that
>        are potentially accessible over the Constrained Application
>        Protocol (CoAP).  This scheme can thus be compared to the "http"
>        URI scheme [RFC2616  <http://tools.ietf.org/html/rfc2616>].  SeeSection 6  <http://tools.ietf.org/html/draft-ietf-core-coap-04#section-6>  for the details of operation.
Looking only at the template, I cannot understand why RFC 2616 is 
referenced normatively.  I did not read the entire document, so if there 
are some other references that justify such action, thst is OK.
>     Encoding considerations.
>        The scheme encoding conforms to the encoding rules established for
>        URIs in [RFC3986  <http://tools.ietf.org/html/rfc3986>].
>
Internalization considerations should also be discussed here.  You may 
just put that non-ACSII chars are to be treated as described in RFC 3987 
or smth. more complicated - as you want.
>     Applications/protocols that use this URI scheme name.
>        The scheme is used by CoAP end-points to access CoAP resources.
>
>     Interoperability considerations.
>        None.
>
>     Security considerations.
>        See "Security considerations" section above.
You should clarify here, IMO.  Section you reference has 5 pages, and 
there is not clear what concern only the URI scheme.
>     Contact.
>        Zach Shelby<[email-masked]>
>
>     Author/Change controller.
>        Zach Shelby<[email-masked]>
If you decide to consider the scheme registration as permanent, the 
would be appropriate to put here IESG and IETF, respectively.
>     References.
>        This document.
As for the Section 6,

I really do not consider Section 6.3 and 6.4 not needed.  They just copy 
what is discussed in RFC 3986.  As for remainder of this Section, that 
is OK, except referencing it as description of scheme semantics.  It 
describes syntax, but not semantics.  So that would be good if you put 
brief description of the issues in the template rather then reference 
sections of your document.

I'd also like to comment the entire Section 11, but that is out of the 
scope of this mailing list, so I'll make it personally to you or to the 
WG mailing list.

All the best,
Mykyta Yevstifeyev
> _______________________________________________
> Uri-review mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/uri-review
>

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 27 Jan 2011 20:17:37 +0100

Mykyta,

thanks for your review as well. Comments inline below.

Mykyta Yevstifeyev wrote:
>    Status.
>       Provisional.
>
> I really wonder why did you put Provisional here.  The Intended status, as
> well as I know is Standards Track, so Permanent will be suitable here more.

The plan is to register the URI scheme before draft-ietf-core-coap
reaches RFC status. So 'Provisional' seems to be the right choice for
this, but I am not sure.

> However you may easily reuse the 'authority' rule from RFC 3986 here.  Or
> there are some reasons you didn't do this?

     authority = [ userinfo "@" ] host [ ":" port ]

The userinfo subcomponent isn't used in CoAP, so the reason is to
syntactically disallow userinfo.

>       URIs in [RFC3986].
> Internalization considerations should also be discussed here.  You may just
> put that non-ACSII chars are to be treated as described in RFC 3987 or smth.
> more complicated - as you want.

I've just looked at RFC 3986 again and found this:

"When a new URI scheme defines a component that represents textual
data consisting of characters from the Universal Character Set [UCS],
the data should first be encoded as octets according to the UTF-8
character encoding [STD63]; then only those octets that do not
correspond to characters in the unreserved set should be
percent-encoded."

So 'Encoding considerations' should specify which components represent
textual data consisting of characters from the Universal Character
Set, and everything should be fine, right?

(The draft defines URIs, not IRIs, so I don't see how RFC 3987 helps here.)

> what is discussed in RFC 3986.

Section 6.3. and 6.4 may not be relevant for the registration of the
URI scheme, but they are relevant to implementers of CoAP.

Section 6.3 provides the steps required from a CoAP client to create
the list of Uri-* Options from the components of a coap URI. Section
6.4 provides the steps required to combine the Uri-* in a request back
to a coap URI. RFC 3986 does not discuss CoAP Uri-* Options.

> As for remainder of this Section [Section 6], that is
> OK, except referencing it as description of scheme semantics.  It describes
> syntax, but not semantics.  So that would be good if you put brief
> description of the issues in the template rather then reference sections of
> your document.

I'm not sure I get what you have in mind. There are three references
from the template to other sections: syntax, semantics and security
considerations.

- Security considerations: I agree the reference to should be more
specific (namely pointing to 10.3.1)

- Syntax: Is your suggestion to move Section 6.1 to Section 11.4 and
reference it from Section 6?

- Semantics: Can you expand on this? I'm not sure how to define the
semantics of coap URIs more specifically beyond saying that (a) coap
URIs identify resources, (b) how these resources can be located (by
contacting the governing CoAP server) and (c) how these resources can
be operated on (by sending CoAP requests to the CoAP server). The text
in httpbis seems to be along the same lines [1,2].

Thanks,
Klaus

[1] http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-12#section-10.2
[2] http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-12#section-2.6.1

---

From: Graham Klyne <[email-masked]>
Date: Thu, 27 Jan 2011 22:00:27 +0000

> reaches RFC status. So 'Provisional' seems to be the right choice for

That is the view I'd take with my reviewer hat on; i.e. provisional for now and 
upgrade to permanent if/when a standard is agreed.

#g
--

---

From: Mykyta Yevstifeyev <[email-masked]>
Date: Fri, 28 Jan 2011 11:19:38 +0200

> reaches RFC status. So 'Provisional' seems to be the right choice for
IANA will provide provisional registration with a simple request as per 
the WG document, see BCP 100.  The draft should reflect what is intended 
to be in the final document.
> syntactically disallow userinfo.
Agreed.  I thought userinfo is used here.
> (The draft defines URIs, not IRIs, so I don't see how RFC 3987 helps here.)
I meant if you intended any sort of internalization of URIs?  If not, 
you may write 'No internalization is intended'.
> to a coap URI. RFC 3986 does not discuss CoAP Uri-* Options.
Agreed once more.  I did not consider this.
> reference it from Section 6?
Here I do not object referencing Section 6.1 in the template.
> in httpbis seems to be along the same lines [1,2].
I propose you should say this (a, b, c) in the template and saying 'See 
Section 6 for details'.

All the best,
Mykyta

---

From: Klaus Hartke <[email-masked]>
Date: Mon, 31 Jan 2011 16:03:52 +0100

Mykyta Yevstifeyev wrote:
> IANA will provide provisional registration with a simple request as per the
> WG document, see BCP 100.  The draft should reflect what is intended to be
> in the final document.

RFC 4395: "The URI registration process is described in the
terminology of [RFC2434]. The registration process is an optional
mailing list review, followed by 'Expert Review'."

BCP 100: "This memo only addresses the early allocation of code points
from spaces whose allocation policy is 'Standards Action' [RFC2434]
AND that have been amended to permit early allocation."

So BCP 100 does not seem to apply to URI schemes.

RFC 4395 "encourage[s] registration [of URI schemes] by setting a low
barrier for provisional registrations." The syntax and semantics of
the 'coap' scheme defined in I-D.ietf-core-coap-04 are pretty stable
and should meet the requirements in RFC 4395 Section 2, but they are
not finalized yet. So it makes sense to register the scheme
provisionally (RFC 4395 Section 3).

(a) Should the template for the provisional registration be in the
draft and the template be updated to 'Permanent' if/when a standard is
agreed; or
(b) should the draft reflect what is intended to be in the final
document and the template for the provisional registration be
submitted directly to IANA?

Please agree on one option :-)

> I meant if you intended any sort of internalization of URIs?
> If not, you may write 'No internalization is intended'.

Yes, it is intended that, e.g., paths in coap URIs may contain
(percent-encodings representing) non-ASCII characters, such as
<coap://example.org/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF>.
(If we defined IRIs instead of URIs, this would be written as
<coap://example.org/こんにちは>.)

Klaus

---

From: Mykyta Yevstifeyev <[email-masked]>
Date: Tue, 01 Feb 2011 07:44:06 +0200

Klaus,

> Please agree on one option :-)
OK, you have convinced me here :-).
> <coap://example.org/こんにちは>.)
Therefore, you should mention that in your draft.

Mykyta