Subject: Last Call: <draft-ietf-appsawg-uri-scheme-reg-04.txt> (Guidelines and Registration Procedures for URI Schemes) to Best Current Practice

From: "Martin J. Dürst" <[email-masked]>
Date: Thu, 12 Mar 2015 19:05:17 +0900

Here are some last call comments on 
draft-ietf-appsawg-uri-scheme-reg-04. The review was started a while 
ago, and completed, but the writeup took a lot of time and is still not 
completed, sorry. I may be able to complete it tomorrow, but please 
don't hold your breath.

[Just in case this is necessary, as a process point, I have seen various 
tracker messages (such as the draft being placed on telechat, or that 
the last call has ended), but I'd like to note that the Last Call 
mentions an end date of 2015-03-12, and it's still 2015-03-12 here in 
Japan, which means that this date has barely started in some other 
locations around the world.]

My overall impression is that the overall direction of the draft is just 
fine, but that presentation and wording are quite rough in many places 
and would tremendously benefit from more careful wording.

Introduction: Overall, this felt too long, and it would benefit from 
better structuring, and/or moving some of the points out to their own 
sections/subsections. For example, adding subsection titles such as 
"URIs and IRIs" and "Generic Syntax and Scheme Specific Syntax" or some 
such would help quite a lot.

"  o  provide a central point of discovery for established URI scheme
       names, and easy location of defining documents for standard
       schemes;"
The use of the word "standard" in "standard scheme" is unclear. This use 
doesn't appear anywhere in the document. Do you mean permanently 
registered schemes? If there's some specific point to be made, please 
make it more clearly. Otherwise, I suggest to just drop the word "standard".

"o  discourage multiple separate uses of the same scheme name;"
I'd personally be happier if this said "strongly discourage", because I 
hope we all agree that it's really not a good idea. If the consensus is 
that it's obvious anyway that it's really not a good idea, and we don't 
need to be overly clear about that, then I'll keep quiet.

"o  encourage registration by setting a low barrier for registration."
What about making this "encourage early registration"?

"A URI scheme name is the same as the corresponding IRI scheme name."
At the minimum, I'd turn this around and say "An IRI scheme name is the 
same as the corresponding URI scheme name." But because the there isn't 
really anything like an "IRI scheme name", I'd actually prefer if this 
said "IRIs use the same scheme names as URIs." or something similar.

"For example, this means that fragment identifiers (#) cannot be re-used 
outside the generic syntax restrictions."
My 'best-guess' interpretation of this sentence is that this intended to 
say that a scheme definition cannot define fragments that contain 
characters (e.g. #) that RFC 3986 doesn't allow.

But this is bad advice, because scheme definitions cannot say anything 
about fragments at all. This isn't syntax, but semantics; the semantics 
of a fragment are defined by the media type, not the scheme. I haven't 
found any place anywhere in this doc that says this, it clearly should 
be added.

If you want to make an example re. syntax, I'd suggest to say something 
like "For example, the query part cannot contain literal '#' characters 
because they and anything after them would be interpreted as part of the 
fragment and not the query." or some such.

Also, the "(#)" in the text is completely superfluous; the '#' itself 
isn't the fragment, and a reader should be able to correlate the word in 
the text and the same word in the ABNF.

"A scheme definition must specify the scheme name and the syntax of the 
scheme-specific part, which is clarified as follows:"
Saying "clarified as follows" and then just giving some ABNF may be 
difficult to grok for some people. I propose to change the sentence to
"A scheme definition must specify the scheme name and the syntax of the 
scheme-specific part, which corresponds to the 'hier-part' and the 
optional query in the above definition. This can be clarified by 
rewriting the definition as follows:"

2. Terminology:

    Within this document, the key words MUST, MAY, SHOULD, REQUIRED,
    RECOMMENDED, and so forth are used within the general meanings
    established in [RFC2119], within the context that they are
    requirements on future registrations.
The double 'within' is confusing. I propose to replace "within the 
context that they are requirements on future registrations" with "as 
requirements on future registrations"

3.  Requirements for Permanent Scheme Definitions

                                                                      For
    IETF Standards-Track documents, Permanent registration status is
    REQUIRED.
Please change this to: "For URI Scheme definitions in IETF 
Standards-Track documents, Permanent registration status is REQUIRED."

3.2. Syntactic Compatibility

                                            Care must be taken to ensure
    that all strings matching their scheme-specific syntax will also
    match the <absolute-URI> grammar described in [RFC3986].

Pronouns like "their" don't usually work well in standard language. I 
suggest changing "their scheme-specific syntax" to "the syntactic 
restrictions of the scheme definition" or some such.

                                                    If there is a strong
    reason for a scheme not to use the hierarchical syntax, then the new
    scheme definition SHOULD follow the syntax of previously registered
    schemes.

Please change "the syntax of previously registered schemes" to "the 
syntax of previously registered schemes with similar components or 
similar syntactic needs." or some such, to make it clear that it's not 
sufficient to just copy some syntax if it's totally unrelated.

    Schemes that are not intended for use with relative URIs SHOULD avoid
    use of the forward slash "/" character, which is used for
    hierarchical delimiters, and the complete path segments "." and ".."
    (dot-segments).
It would be good if the text gave the reasons for the SHOULD (which I 
fully agree with; maybe even a MUST).

Please add a(n informational) reference to Gettys, J., "URI Model 
Consequences", <http://www.w3.org/DesignIssues/ModelConsequences> in 
this section. It is a great text helping designers of URI scheme syntax 
to understand the ideas regarding the different syntax components.

    New schemes SHOULD clearly define the role of [RFC3986] reserved
    characters in URIs of the scheme being defined.
The location of [RFC3986] is a bit strange. It might work if "[RFC3986] 
reserved characters" is taken as a phrase, but it's difficult for the 
reader to see that. Also, the specific topic is discussed in Section 2.2 
of [RFC3986], so change the above to:
    New schemes SHOULD clearly define the role of reserved characters
    (see [RFC3986], Section 2.2) in URIs of the scheme being defined.

3.3. Well-Defined

                                                         and how legal
    values in the base namespace, or legal protocol interactions, might
    be represented in a valid URI.
"might be represented" -> "are represented"

                                    See Section 3.6 for guidelines for
    encoding binary or character strings within valid character sequences
    in a URI .
"binary or character strings" -> "sequences of bytes or characters" (in 
most contexts (programming languages,...), "character string" is 
equivalent to "string", while "binary string" is undefined.)

Superfluous space before period.

                If not all legal values or protocol interactions of the
    base standard can be represented using the scheme, the definition
    SHOULD be clear about which subset are allowed, and why.
"Which subset are" -> "which subset is" (or "which subsets are")

3.5. Context of Use

                   Most commonly, URIs are used as references to
    resources within directories or hypertext documents, as hyperlinks to
    other resources.

This sentence is totally unclear. Why do directories turn up here? Is 
"resources within directories" and "other resources" parallels? Are 
"references" and "hyperlinks" intended to be parallels? Is "references 
to resources within ..." intended to mean "references to resources from 
within ..." or "references to (resources within ...)"?. Please clarify.

3.6. Internationalization and Character Encoding

    When describing schemes in which (some of) the elements of the URI
    are actually representations of human-readable text, care should be
    taken not to introduce unnecessary variety in the ways in which
    characters are encoded into octets and then into URI characters; see
    [RFC3987] and Section 2.5 of [RFC3986] for guidelines.  If URIs of a
    scheme contain any text fields, the scheme definition MUST describe
    the ways in which characters are encoded and any compatibility issues
    with IRIs of the scheme.

I think it would be extremely helpful to the average URI scheme 
designer/describer if this section mentioned the use of UTF-8. The 
reference to Section 2.5 of RFC 3986 is good, but the problem with that 
section is that it starts out with very general and abstract language, 
and one has to read through the whole section to find the relevant (and 
extremely clear and appropriate) advice in the last paragraph.

At a minimum, please point the reader to the last paragraph of Section 
2.5. Much better would be to include that paragraph verbatim (and saying 
so explicitly):

    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.  For example, the character A would be represented as "A",
    the character LATIN CAPITAL LETTER A WITH GRAVE would be represented
    as "%C3%80", and the character KATAKANA LETTER A would be represented
    as "%E3%82%A2".

    The scheme specification SHOULD be as restrictive as possible
    regarding what characters are allowed in the URI, because some
    characters can create several different security considerations (see,
    for example [RFC4690]).
I'm afraid that many people will read "as restrictive as possible" as 
"well, let's just do ASCII only" or some such. I believe and hope that 
this wasn't the intent, but I don't think this comes across. One kind of 
improvement would be to change "as restrictive as possible" to just 
"restrictive". Another is to change "as restrictive as possible" to "as 
restrictive as possible without excluding characters outside US-ASCII".

"can create security considerations" sounds weird. The characters may 
create security issues or security problems or some such, which may need 
to be described in a security consideration section.

    All percent-encoded variants are automatically included by definition
    for any character given in an IRI production.  This means that if you
    want to restrict the URI percent-encoded forms in some way, you must
    restrict the Unicode forms that would lead to them.

I know what you want to say here (I think it's the point originally 
brought up by Björn Höhrmann in the IRI WG). But I think it's too 
restrictive and can be worded better:

    URI schemes that include textual data from Unicode have to be aware
    that they have to define both the actual characters allowed (for
    IRIs) and the corresponding percent-encoded forms (for URIs and
    IRIs). This can be done in various ways, but in most cases, it is
    advisable to define the actual characters allowed in an IRI
    production, to allow the 'pct-encoded' definition from Section 2.1
    of [RFC 3986] at the same places, and to add prose that limits
    percent-escapes to those that can be created by converting valid
    character sequences to percent-encoding via UTF-8.

Regards,    Martin.

---

From: John C Klensin <[email-masked]>
Date: Thu, 12 Mar 2015 12:51:12 -0400

--On Thursday, March 12, 2015 19:05 +0900 "\"Martin J. Dürst\""
<[email-masked]> wrote:

> draft-ietf-appsawg-uri-scheme-reg-04. The review was started a
> while ago, and completed, but the writeup took a lot of time
> and is still not completed, sorry. I may be able to complete
> it tomorrow, but please don't hold your breath.
> 
> [Just in case this is necessary, as a process point, I have
> seen various tracker messages (such as the draft being placed
> on telechat, or that the last call has ended), but I'd like to
> note that the Last Call mentions an end date of 2015-03-12,
> and it's still 2015-03-12 here in Japan, which means that this
> date has barely started in some other locations around the
> world.]
>...
 
Hi.  I had decided to just let this Last Call expire without
comment -- my IETF time in the last several weeks has been
completely taken up by other issues, notably URNBIS and i18n
(IDNA, LUCID, etc.) work on which I'm on the critical path.
However, with the last of those drafts posted, Martin's notes
and a few recent comments prompt a comment from a slightly
different perspective.

(1) First, several people have commented, directly or
indirectly, about the precision and clarity of the document.  I
agree: it is less clear and precise than it should be.  Clarity
and precision are especially important for a document that
specifies expert review because there is limited exposure and
broad community discussion of these documents.  Registration
proposal review lists are not a substitute for the type of
review that occurs (or should occur) in IETF LC because people
with subject matter expertise associated with a particular
registration proposal are unlikely to on on those lists.

(2) The clarity and precision problem is particularly important
in this case because there are issues with the clarity and
precision of the underlying documents.  Both the apps-discuss
and URN mailing lists (and associated WGs) have been treated to
long, and mostly, IMO, still unresolved, threads about what RFC
3986 actually means, specifies, recommends, or requires.
Regardless of the position one takes on those arguments, having
a document that is necessarily dependent on 3986 is problematic
unless they are adequately resolved for its purposes and should
be considered unacceptable if it substantially or completely
ignores those issues.

I note that there have been discussions in other forums,
including WHATWG, W3C, and private discussions among the latter
and relevant ADs, about drafts and proposals that are being
developed outside the IETF with the intention of superceding all
or part of 3986 in the relatively near future.  Regardless of
the other effects of those efforts and how the IETF should
respond to them, work that is heavily dependent on practical
definitions (including definitions-by-practice (aka "running
code") as well as 3986) of URIs needs to be completely clear
about what it is specifying and expecting.

One example arises in passing in Martin's comment (an issue that
has also come up in URNBIS and elsewhere).  3986 parsing and
semantics are either normative or they are not (the current
working assumptions in URNBIS is that semantics need to be
excluded for URNs by amending 3986 for that purpose) and, again,
this document needs to be clear rather than glossing over the
issue and hoping things will work out "by default".

(3) Similarly, as soon as a URI-related specification starts to
discuss non-ASCII characters, it either needs to link itself
_very_ closely to 3986 or it inherently gets tangled up with
IRIs.  In that area, there is a Proposed Standard (RFC 3987).
There was an effort to update 3987 in the IETF that identified a
number of (IMO important) issues but that was unsuccessful in
resolving then, leading to the effort collapsing.  As with 3986,
there are now efforts going on outside the IETF to revise or
reinterpret the IRI spec and/or to simply fold IRIs and URIs
together.  Under other circumstances, that situation might
result in a "health warning" applicability statement about 3987,
but there apparently hasn't been energy to create and debate
such a thing.    It seems to me that we could have an
interesting debate about whether 3986 applies (i.e., no
non-ASCII characters except via %-encoded UTF-8),  some broader
statement about IRIs should be made, or some other direction
taken, but that is is not acceptable to not be clear about the
options for whatever is being registered.

(4) Finally, this Last Call identifies a procedural issue with
APPSAEG in particular and perhaps some other Area WGs.  The
applications area, and hence AppsAWG, span a very broad
collection of topic areas (a situation that will certainly
become worse with the upcoming reorganization and
consolidation).  Most participants are active in other WGs (to
which they may have primary commitments) and few have the time
and expertise to dig deeply into every topic the WG chooses to
take up.  I favor such WGs as a way to discussion Area-wide
topics and to help strike a balance between the overhead of
traditional WGs that have highly constrained and topic-specific
charters and the use of AD-sponsored individual submissions for
immature or controversial drafts.  But because of their breadth
and the difficulty of assuming that there is a significant
number of WG participants who are expert about and examining
each specification in careful and appropriately skeptical way,
automatic use of two-week IETF Last Calls from the output of
such groups may not be consistent with fairness.

  john

---

From: "Martin J. Dürst" <[email-masked]>
Date: Fri, 13 Mar 2015 18:28:38 +0900

> completed, sorry. I may be able to complete it tomorrow, but please

I managed to find my review notes again and to complete the writeup, so 
below is the rest of my comments.

[Looking at the copy with my notes, it's actually the -03 draft, so 
please ignore all issues in yesterday's mail that already have been 
fixed in -04.]

3.8. Scheme Name Considerations

                                       New registered schemes
    registrations MUST follow this syntax, which only allows a limited
    repertoire of characters (taken from US-ASCII).
"schemes registrations" -> "scheme registrations"

    A scheme name is not a "protocol" although, like a service name as
    defined in section 5 of [RFC6335], it often identifies a particular
    protocol or application.
'"protocol" although' doesn't work. I suggest to reword as:
    A scheme name is not a "protocol". However, like a service name as
    defined in section 5 of [RFC6335], it often identifies a particular
    protocol or application.

I wonder whether it makes sense to say something about abbreviations, 
such as "If there is a well-known abbreviation for the protocol or 
service, then it's preferable to use it as a scheme name (e.g. http: 
rather than hypertext-transfer-protocol:)."

    Some organizations desire their own namespace for URI scheme names
    for private use (see Section 6).  In doing so, it is important to
    prevent collisions, and to make it possible to identify the owner of
    a private use scheme.  To accomplish these two goals, such
    organizations SHOULD use a prefix based on their domain name,
    expressed in reverse order.  For example, a URI scheme name of
    com.example.info might be used by the organization that owns the
    example.com domain name.  Care must be taken, however, if the
    organization later loses the domain name embedded in their scheme
    names, since domain name registrations are not permanent.  The URI
    scheme name registration procedure can be used in such an event.
The the last sentence is unclear. I suggest to rewrite the last sentence 
to something like "In order to permanently associate the private use 
scheme name with the original domain name owner, the private use scheme 
can be registered using the registration procedure in Section XYZ.".

Either at the end of section 1 or in a subsection of section 3, it 
should be made *extremely* clear that scheme registrations neither can 
nor should define anything related to fragments, i.e. that fragments are 
mostly if not completely orthogonal to schemes, and their interpretation 
is defined by the MIME media type of the returned representation when 
dereferencing.

4. Guidelines for Provisional URI Scheme Registration

There is a point about provisional registrations meeting the syntax 
restrictions for scheme names, but nothing about syntax restrictions for 
the rest of the URIs. I think it should be made very clear that while we 
have made provisional registration very easy on purpose, if a scheme 
doesn't meet the general syntax restrictions, it may not work in some or 
all URI software, and it doesn't have a chance to move to permanent 
registration.

o  The scheme definition SHOULD include a clear Security
    Considerations (Section 3.7)

"a clear Security Considerations" -> "a clear Security Considerations 
section" or "clear security considerations"
Also: "(Section 3.7)" -> "(see Section 3.7)"

5. Guidelines for Historical URI Scheme Registration

    In some circumstances, it is appropriate to note a scheme that was
    once in use or registered but for whatever reason is no longer in
    common use or the use is not recommended.
Change the last bit ("or the use is not recommended") to "or is no 
longer recommended for use" to avoid a change of subject in mid-sentence.

                   Any scheme that is no longer in common use MAY be
    designated as historical; the registration SHOULD contain some
    indication to where the scheme was previously defined or documented.
"indication to" -> "indication about"

6. Guidelines for Private URI Scheme Use

            As such, a unique namespace (see Section 3.8) MUST be used,
    and it is strongly encouraged to do a Provisional registration unless
    the scheme name is constructed from a domain name.
Please add a pointer to the example at the end of section 3.8.

7. URI Scheme Registration Procedure

7.1. General

    The IANA policy (using terms defined in [RFC5226]) for Provisional
    registration was formerly Expert Review and is now changed to simply
    use a First Come First Served policy.
"is now changed" will read badly a few years down the line. Please 
reword. Also, it may be worth pointing out that somebody who wants to 
register something as provisional still can ask for review. While there 
are people who know that they are exactly right (even if they may be 
wrong), there are also other people who might want to get a (few) 
pair(s) of eyes more on what they are doing.

7.2. Registration Procedures

    Someone wishing to register a new scheme MUST:

    1.  Check the IANA URI Schemes registry to see whether there is
        already an entry for the desired name.  If there is already an
        entry under the name, choose a different scheme name, or update
        the existing scheme specification.
The last clause may be interpreted to allow hijacking. It should be made 
clear that this isn't the intent.

    2.  Prepare a scheme registration request using the template
        specified in Section 7.4.
In this paragraph, it should be made clear that the template should be 
complete on its own. As an example,
    Scheme syntax:
       See the syntax definition in section FOO.
is bad, but
    Scheme syntax:
       See the syntax definition in section FOO of the BAR specification.
may be okay, even if it reads somewhat redundantly when inside the BAR 
specification itself.

        2.  Send a copy of the completed template or a pointer to the
            containing document (with specific reference to the section
            with the completed template) to the mailing list uri-
            [email-masked] , requesting review.
It should be made clear that sending a full copy of the template is 
strongly preferred, because it significantly increases the chance and 
timeliness of comments.

                                                                    For
            example, general discussion of URI syntactical issues could
            be discussed on [email-masked]; schemes for a network protocol
            could be discussed on a mailing list for that protocol.
Change "could" to "ought" or "can" (two times).

    4.  Submit the (possibly updated) registration template (or pointer
        to document containing it) to IANA at [email-masked].
It may be obvious to insiders, but worth pointing out because we want to 
reach outsiders, too: It is important to note that submission to IANA 
for registration doesn't happen automatically but has to be done by the 
registrant.

    1.  IANA checks the submission for completeness; if sections of the
        template are missing or any citations are not correct, IANA will
        reject the registration request.
Again, it may be obvious to insiders, but worth adding: This doesn't 
preclude new, fixed submissions.

    3.  Otherwise, IANA enters the registration request in the IANA
        registry, with status marked as "Pending Review" and the
        remainder of this section applies.
Please add a comma after "Pending Review" (end of 'with' clause).

    6.  In the case of a Permanent registration request, the Designated
        Expert may:
        *  Request additional review or discussion, as necessary.
Again this may be obvious to insiders, but it may be worth saying that 
this should as much as possible be conducted on public mailing lists.

    Either based on an explicit request or independently initiated, the
    Designated Expert or IESG can request the upgrade of a 'provisional'
    registration to a 'permanent' one.
"IESG" -> "the IESG"
It would probably be better if the paragraph starting with the above 
lines would move from the end of section 7.2 to the end of section 7.3.

                                            Typically this would only
    occur if the use is considered a standard (not necessarily an IETF
    standard).
A standard may be used, but 'use' isn't a standard. Either say "use is 
considered to be very widespread" (I'd avoid the word "standard" in that 
sense) and remove the "IETF standard" parenthetical, or change to "if 
the scheme is defined in a standard" (in that case "IETF standard" 
should be changed to (IETF) Internet Standard).

7.4. URI Scheme Registration Template
    Contact:
      Person (including contact information) to contact for further
      information.

    Author/Change controller:
      Person (including contact information) authorized to change this.
This is a problem with many other registration templates, too, which we 
should fix whenever we can: I have seen many people struggling with this 
distinction. It's rarely very useful.

What is useful in some cases is to make a distinction between the 
submitter/author and the organization in charge, but "Author/Change 
controller" mixes the two. The minimum improvement that I'd propose is 
the following:
    Author/Contact:
      Person (including contact information) to contact for further
      information.

    Change controller:
      Organization or person (including contact information) authorized
      to change this.
This would at least make it moderately easy for registrations from the IETF.

    The following fields are no longer required in a scheme registration
    request.  The answers instead belong in the scheme specification.
"no longer required" and "belong" conflict, in that "no longer required" 
doesn't exclude them, but "belong" does. I'd prefer to say that if they 
are short or very important, they should be given in the template, if 
they are lengthy, they should be given separately, and if they are 
irrelevant, they can be ignored.

    Interoperability considerations:
               inability to support multibyte character sets;
The modern Internet, in particular in URIs and IRIs, does have 
absolutely no need to support multibyte character sets, and even less of 
a need to use such a term (see 
http://www.w3.org/MarkUp/html-spec/charset-harmful.html). Please change 
this to something like
"inability to support non-ASCII characters".

    Scheme syntax:  The entire range of allowable syntax specified in
      [RFC3986] is allowed for "example" URIs.
Please add: The entire range of allowable syntax specified in [RFC3987] 
is allowed for "example" IRIs.

8.1. "Example" Scheme Registration Request
Please change this title to "Example" Scheme Registration Template.

10. Security Considerations
    All registered values are expected to contain accurate security
    consideration sections; 'permanent' registered scheme names are
    expected to contain complete definitions.
Words such as "accurate" and "complete" are wishful thinking. When it 
comes to security, there is always the chance of a discovery of new 
security issues. This section should make it clear that best effort is 
expected of the registrants, and that third parties may request the 
addition of new issues, but that the security information in a scheme 
registration should never be seen as complete and final.

Regards,    Martin.