Subject: Artart telechat review of draft-ietf-regext-launchphase-06

From: Harald Alvestrand <[email-masked]>
Date: Wed, 06 Dec 2017 06:07:39 -0800

Reviewer: Harald Alvestrand
Review result: Ready with Issues

Review of draft-ietf-regext-launchphase-06

Summary: I suppose this is ready for the editing pass. Apologies for not
completing it before the telechat.

The document does not do a very good job of describing the overall
flow of the context in which it is going to be used; for example, it
is relatively late in the document that I discovered that claim
notices have expiration dates (launch:notAfter in section 3.3.2).

The document needs a thorough language check, in particular I reacted
negatively to its rather sparse use of commas, which in several cases
left sentences looking ambiguous to me.

However, the implementation section indicates that this is work that
is really waiting for formal approval, and I see no strong reason to delay
the document further.

Nits and grammar points
=======================

Section 1.1

The definitions "launch-1.0", "signedMark-1.0" and "mark-1.0" are not
in fact used. The paragraphs should be rephrased as

"The XML namespace prefix "smd" is used for the
"urn:ietf:params:xml:ns:signedMark-1.0" namespace. Implementations
MUST NOT ....."

2.2

Grammatical: ", that is unique to the server," is ungrammatical. Just
", unique to the server," would be correct and clearer.

2.3.1

Format: "Claims Check Form" and "Claims Create Form" repeats their
hang text in the paragraph. This is confusing to read in ASCII.

2.4

This sentence: "if a launch status is supported and the launch status
is not one of the final statuses, including the "allocated" and
"rejected" statuses." makes equal grammatical sense if "allocated" and
"rejected" are final statuses or non-final statuses. Could be clearer.

The two sentences starting "Is a possible end state" would be more
grammatical if they were "This is a possible end state".

It is not clear what causes the transition from "validated" to
"pendingAllocation". It is also not clear if a transition possibility
exists straight from "validated" to "allocated" for the case where no
external process is needed.

2.5

"A Launch Application MUST and a Launch Registration MAY" would be
clearer if there were commas around "and a Launch Registration MAY".

2.6.3

This section's sentence structure is unclear due to a missing comma
before "or the <smd:encodedSignedMark>".

3.1

It is completely unclear what functional difference there is between
the "Claims Check Form" (3.1.1) and the "Trademark Check Form"
(3.1.3). I suspect the idea behind "whether or not there are any
matching trademarks, in the specified launch phase, for each domain
name passed in the command, that requires the use of the "Claims
Create Form" on a Domain Create Command." (3.1.1) versus "whether or
not there are any matching trademarks for each domain name passed in
the command, independent of the active launch phase of the server and
whether the "Claims Create Form" is required on a Domain Create
Command." (3.1.3) is that the latter will return claims info in cases
where the former would not, but it's not clear when this makes a
difference to the caller - the same reply info seems to be returned in
both cases.

Another interpretation is that there exist trademarks that match in a
given phase and do not match outside that phase, so that the "claims
check form" may return matches that "trademark check form" would not -
this seems a bit bizarre.

---

From: "Gould, James" <[email-masked]>
Date: Wed, 6 Dec 2017 19:18:46 +0000

Harald, 

Thank you for your review and feedback, below are my answers to your feedback.
  
—
 
JG

James Gould
Distinguished Engineer
[email-masked]

703-948-3271
12061 Bluemont Way
Reston, VA 20190

Verisign.com <http://verisigninc.com/> 

On 12/6/17, 9:07 AM, "Harald Alvestrand" <[email-masked]> wrote:

    

    
    
    Nits and grammar points
    =======================
    
    Section 1.1

Yes, you are correct the “launch-1.0”, “signedMark-1.0”, and the “signedMark-1.0” abbreviations are not used.  I agree with your proposal to modify each of those paragraphs to read:

“The XML namespace prefix <prefix> is used for the <namespace> namespace, but implementations…”  for the three <prefix> values (“launch”, “smd”, and “mark”) and three <namespace> values (“urn:ietf:params:xml:ns:launch-1.0”, “urn:ietf:params:xml:ns:signedMark-1.0”, and “urn:ietf:params:xml:ns:mark-1.0”), respectively.   
    
    2.2

Agreed, that is better.
   
    2.3.1

Yes, that is consistent feedback to Eric Rescoria’s feedback.  This can be taken care of.
    
    2.4

Would the use of parenthesis work better as in the sentence below?
“if a launch status is supported and the launch status is not one of the final statuses ("allocated" and "rejected").”

Yes, that is better.

The transitions between the statuses is up to the server policy.  There is no pre-defined timeframe that a domain must remain in a status.  In general, the processing is done asynchronously and based on a batch schedule, where a batch may validate thus putting the domains in the “validated” status.  A separate batch may prepare the domains for the allocation process thus putting the domains in the “pendingAllocation” status.  Finally, a batch will allocate the domains thus putting the domains in either the “allocated” or the “rejected” status.  

Yes, there can be a server policy that supports moving domains to the “validated” or “invalid” status in one step and then deciding on the allocation in a separate step synchronously.  In this case, there is no need for the “pendingAllocation” status.  
  
One scenario is that a pendingValidation domain may skip the validated status and transition immediately to the pendingAllocation status, or 
    
    2.5

How about trying to fix the sentence overall, with the following two sentences?

“A Launch Application MUST be handled as an EPP domain name object, as specified in RFC 5731 [RFC5731], with the "pendingCreate" status and with the launch status values defined in Section 2.4.  A Launch Registration MAY be handled as an EPP domain name object, as specified in RFC 5731 [RFC5731], with the "pendingCreate" status and with the launch status values defined in Section 2.4.” 
    
    2.6.3

I believe the fix here is to remove “either” and the comma from the sentence as in:

“Digital signatures MAY be used by the server to validate the mark information when using the "signed mark" validation model with the <smd:signedMark> (Section 2.6.3.1) element or the <smd:encodedSignedMark> (Section 2.6.3.2) element.”

Do you agree that this is better?
    
    3.1

    
The Trademark Check Form was explicitly requested on the list to support checking for the existence of trademarks independent of the active or specified phase and without requiring an indication that a claims notice is required on a domain create.  The primary purpose of a check is to indicate to the client whether a create will work, which is the goal of the Claims Check Form.  Depending on the phase, the Claims Check Form may not return the claims information because the create does not require it.  However, the Trademark Check Form will always return the claims information if there is at least one trademark associated with the domain name.  This is a subtle difference, but an important difference since some systems require providing the raw trademark information without including the extra phase-specific logic of the Claims Check Form.

---

From: Harald Alvestrand <[email-masked]>
Date: Mon, 11 Dec 2017 12:47:03 +0100

> Thank you for your review and feedback, below are my answers to your feedback.

Thanks for the quick response!
Deleting all below where you said "yes, we'll do that" and where I have
no further comment.

> “if a launch status is supported and the launch status is not one of the final statuses ("allocated" and "rejected").”

This is much more readable, thank you.

> One scenario is that a pendingValidation domain may skip the validated status and transition immediately to the pendingAllocation status, or 

In that case, it would be clearer if the drawing was preceded by a
sentence saying: "The transitions between states is a matter of server
policy. One possible set of permitted transitions is given in the
diagram below".

This will make it clear to people that this isn't a total map of
possible transitions.

> “A Launch Application MUST be handled as an EPP domain name object, as specified in RFC 5731 [RFC5731], with the "pendingCreate" status and with the launch status values defined in Section 2.4.  A…

This looks good to me.

> Do you agree that this is better?

I'm still a bit confused about where the beginning of the sentence is
that ends with "or". Is it obvious to everyone that the "signed mark"
validation model is used both with <smd:signedMark> and with
<smd:encodedSignedMark>? It's possible to read this as there being two
validation models, one that is called "signed mark and uses
<smd:signedMark>, and another one that's not named, but uses
<smd:encodedSignedMark>.

> The Trademark Check Form was explicitly requested on the list to support checking for the existence of trademarks independent of the active or specified phase and without requiring an indication th…

This makes perfect sense (if I interpret it correctly), and was the most
reasonable interpretation I had.

Would it make sense to add a sentence saying "The Trademark Check Form
will always return at least the marks returned by a similiar Claims
Check Form, but may return additional marks"?

Happy that the review was useful!

Harald

---

From: "Gould, James" <[email-masked]>
Date: Mon, 11 Dec 2017 16:59:48 +0000

Harald,

Thanks, as before my responses are embedded below.
  
—
 
JG

James Gould
Distinguished Engineer
[email-masked]

703-948-3271
12061 Bluemont Way
Reston, VA 20190

On 12/11/17, 6:47 AM, "Harald Alvestrand" <[email-masked]> wrote:

    

    

Ok, I’ll add a preamble to the diagram that reads “The transitions between the states is a matter of server policy.  This diagram defines one possible set of permitted transitions.”  Does this work?

    This looks good to me.

The <smd:encodedSignedMark> is the <smd:signedMark> encoded (e.g., Base64), where both are directly related to the “signed mark” validation model.  The “signed mark” validation model is defined in 2.6 applies to the use of the <smd:signedMark> and the <smd:encodedSignedMark> elements.  The description in 2.6.3 should match the description in 2.6 with using an “and” instead of an “or”.  It would be more consistent to read “Digital signatures MAY be used by the server to validate the mark information when using the "signed mark" validation model with the <smd:signedMark> (Section 2.6.3.1) element and the <smd:encodedSignedMark> (Section 2.6.3.2) element”.  Do you agree with changing the “or” with an “and”?       

    

I believe it’s best to keep them separate and not add the sentence, since adding a linkage between the Trademark Check Form and the Claims Check Form may add confusion.  The Trademark Check Form is a raw trademark check without applying any additional server policy, and the Claims Check Form is meant to apply the server policy as an indication of whether a create will work.  Do you agree that we should leave the two forms separate? 

    Harald