Hi Miguel,
Thank you for your detailed review.
--On September 8, 2010 3:25:49 PM +0200 "Miguel A. Garcia"
<[email protected]> wrote:
Minor issues:
- Section 4, second paragraph. The text reads:
A site MAY provide TXT records in addition to SRV records for each
service.
I think that the "MAY" word does not make sense written in capital
letters, because in this case you are giving an operational advice of the
protocol. This is not the intention of a capitalized "MAY", which is
supposed to indicate an optional requirement for conformance of the
protocol. I suggest to replace "MAY" with "may".
In my working copy I have changed "MAY" to "might".
- A question on Section 4, 2nd paragraph. The text says how to _use_ the
existing "context path" with the received "path" in the TXT record.
First, I am not sure that the word "use" is good enough here. Do you mean
"replace"?
I think "use" is correct here, as at that point there is no "context path"
already defined that could be replaced.
Second, I don't know what is a "context path" and where it is
defined, so, can you add a reference to a document that defines context
path?
Paragraph 5 of the Introduction introduces the term "context path". I am
not aware of any formal definition of that. Perhaps "service path" would be
a better term.
Third, it is not clear to me that even with the two above
clarifications, there is a unique way to build a new URI with the
information received in the TXT record. Can you demonstrate that there is
only one way of creating this URI with the received "path", so that all
the implementations will obtain the same result?
There is only one path value specified in the TXT record so there is only
one way to build the HTTP request-URI (using the SRV host/port and the TXT
path= values). I don't see where there are "multiple" ways to do that.
- Section 6. The title of the section contains the word "Guidelines". To
me, the word Guideline indicates a suggestion, or pure informative text.
So, I am surprise to see quite a lot of normative text (see bullet points
2, 4, etc.). This makes me think that the title is not accurate, and
perhaps you should talk about "Procedures" rather than "Guidelines".
I don't want to "insist" that all clients or servers do things exactly in
the way proscribed. There could be reasons for following slightly different
approaches (e.g. when out-of-band forms of authentication are used). That
said changing "Guidelines" to "Procedures" is fine given that the first
paragraph makes it clear that this procedure is optional.
- Section 6, first paragraph, the text reads:
This section describes a procedure that CalDAV or CardDAV clients MAY
use to do their initial configuration based on minimal user input.
This is a relative clause. I don't like to have normative statements
("MAY") in relative clauses, because normative part of it becomes
diluted. If you still want to have normative MAY, split the sentence into
two. My recommendation, you don't need normative, and the "MAY" should be
written in lower case.
As mentioned in the answer to the previous issue, I want to make it clear
that the procedure being described is not required. So how about:
This section describes a procedure that CalDAV or CardDAV clients can
use to do their initial configuration based on minimal user input. This
procedure is OPTIONAL, clients can use alternative methods to accomplish
the appropriate configuration steps.
- In Section 6, bullet point 3, the text describes a client making an SRV
request and receiving SRV and TXT records in a response. So, the client
receives TXT even when it didn't ask for it. In principle,
draft-cheshire-dnsext-dns-sd does not recommend the inclusion of TXT
records when SRV is requested. So, I wonder if there is a real use case
for this paragraph.
Actually my intent was that the client needs to do another query for the
TXT record. So how about changing the text to:
When an SRV lookup is done and a valid SRV record returned,
the client MUST also make a query for a corresponding
TXT record and check for a "path" key in its value.
- Section 6, bullet point 5, first paragraph. The text reads:
Certificate verification MUST
use the procedure outlined in Section 4 of
[I-D.saintandre-tls-server-id-check] in regard to verification
with an SRV RR as the starting point.
I would like to see an explicit active sentence, with a proper subject.
So, who must do the verification, the client? Then write:
"The client MUST do a certificate verification by using the
procedure... "
Fixed in my working copy.
Nits/editorial comments:
- Abstract. I am missing an explicit mention to "DNS", for example:
"This specification describes how DNS SRV records, DNS TXT records
and well-known URIs can be used together or separately to locate..."
Fixed in my working copy.
- The short title of the I-D, which is visible in the header of every
page, misses "CardDAV, because it merely reads "SRV for CalDAV".
Fixed in my working copy.
- Introduction, first paragraph: s/port/port number
I made that change in my working copy for all appropriate instances of
"port" throughout the document.
- Introduction, third paragraph: s/addition al/additional
Fixed in my working copy.
- Section 4, 2nd paragraph. Write ".well-known" within quotes to
facilitate the reading of the text.
Fixed there and other places for consistency.
- Section 5 talks about the prohibition to servers to locate the actual
service in the well-known URI. I would suggest to add a bit of
motivation. Perhaps it is already covered in another document, but still
it would be good to find out the reason.
I added a reference to "Section 1.1 of [RFC5785]" to cover that. This
requirement was imposed by the .well-known registry expert review - prior
to that it was not explicitly stated.
--
Cyrus Daboo
_______________________________________________
Gen-art mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/gen-art
