ietf
[Top] [All Lists]

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

2015-03-13 04:29:47
On 2015/03/12 19:05, "Martin J. Dürst" wrote:
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.

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-
           review(_at_)ietf(_dot_)org , 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 uri(_at_)w3(_dot_)org; 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 iana(_at_)iana(_dot_)org.
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.



<Prev in Thread] Current Thread [Next in Thread>