Subject: Gen-art LC (and telechat) review for draft-ietf-regext-epp-rdap-status-mapping-01

From: Robert Sparks <[email-masked]>
Date: Wed, 5 Oct 2016 15:58:00 -0500

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Document: draft-ietf-regext-epp-rdap-status-mapping-01
Reviewer: Robert Sparks
Review Date: 5 Oct 2016
IETF LC End Date: 10 Oct 2016
IESG Telechat date: 13 Oct 2016

Summary: This draft is on the right track but has open issues, described 
in the review.

Major Issue:

Many of the descriptions describe only side-effects of the status 
instead of the status itself.

All of the descriptions for the new rdap status codes start with "For 
DNR that indicates". This implies that there is a "For not DNR" case 
that's not discussed. I don't think the phrase is necessary and each 
description should look more like the other descriptions already 
registered at 
http://www.iana.org/assignments/rdap-json-values/rdap-json-values.xhtml.

For instance, at 'auto renew period' the document currently says:

"For DNR that indicates if the object is deleted by the registrar during 
this period, the registry provides a credit to the registrar for the 
cost of the auto renewal"

That discusses something (and not the only thing) that can happen while 
the object is in that state. It does not describe the state.

I suggest it should instead say (based on the text in 3915 and the 
current registry entry style):

"The object instance is in a grace period provided between when its 
registration period expires and when its registration is automatically 
renewed by the registry."

I don't think it's important to include the commentary about providing a 
credit if the entity is deleted by the registrar during this period, but 
since that commentary exists in 3915, you can include it if you want. 
The _important_ part to convey is the actual status.

All of the descriptions will need similar attention. Some of them (such 
as clientUpdateProhibited) currently have 2119 words in the description. 
That doesn't make sense - this is a status, not an protocol instruction, 
and trying to put normative language in a registry will lead to 
confusion about where the behavior you are trying to describe is 
actually defined. (To be fair, 5731 has this same problem). Again, I 
suggest following the style that's already in the registry and say 
something like "The client has requested that any requests to update 
this object instance be rejected."

Minor Issues:

You're setting up a minor maintenance headache for any future work that 
might update this document by having the descriptions listed in two 
places. I don't think it's necessary to list the descriptions in section 
2 (currently the bulk of page 4 and the beginning of page 5). Instead, 
stop after the paragraph that ends at the top of page 4, and note that 
the descriptions of each new status code are provided in section 3.

Nits:

Near the end of page 3, the document says "In the DNR, the client and 
server prohibited statuses are separate an RDAP MUST support the same 
separation." There are several nits to address with this. That MUST is 
not a good use of 2119. DNR hasn't been expanded (and "the DNR" is not 
particularly clear).

I suggest you replace that sentence, and the one immediately before it with:

"EPP provides status codes that allow distinguishing the case that an 
action is prohibited because of server policy from the case that an 
action is prohibited because of a client request. The ability to make 
this distinction needs to be preserved in RDAP."

---

From: "Gould, James" <[email-masked]>
Date: Mon, 10 Oct 2016 15:28:39 +0000

Robert,

Thank you for your review and feedback.  I provide responses to your feedback below.

—

JG

James Gould
Distinguished Engineer
[email-masked] <applewebdata://AECD3A2D-1DB8-4EBB-8F64-F11BAFDE30EA/[email-masked]>

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

VerisignInc.com <http://verisigninc.com/>
> On Oct 5, 2016, at 4:58 PM, Robert Sparks <[email-masked]> wrote:
> 
> Summary: This draft is on the right track but has open issues, described in the review.
> 
> Major Issue:
> 
> Many of the descriptions describe only side-effects of the status instead of the status itself.
> 
> All of the descriptions for the new rdap status codes start with "For DNR that indicates". This implies that there is a "For not DNR" case that's not discussed. I don't think the phrase is necessary and each description should look more like the other descriptions already registered at http://www.iana.org/assignments/rdap-json-values/rdap-json-values.xhtml.
> 
> "For DNR that indicates if the object is deleted by the registrar during this period, the registry provides a credit to the registrar for the cost of the auto renewal"
> 
> That discusses something (and not the only thing) that can happen while the object is in that state. It does not describe the state.
> 
> I suggest it should instead say (based on the text in 3915 and the current registry entry style):
> 
> "The object instance is in a grace period provided between when its registration period expires and when its registration is automatically renewed by the registry."
> 
> I don't think it's important to include the commentary about providing a credit if the entity is deleted by the registrar during this period, but since that commentary exists in 3915, you can include it if you want. The _important_ part to convey is the actual status.

The “For DNR that indicates” can be removed from the descriptions.  For example, the "addPeriod = add period; For DRN that indicates if the object is …”  mapping could be "addPeriod = add period; If the object is …”.  The purpose of this draft is to map the statuses defined in EPP and RDAP, so the status descriptions included in the draft where taken from the EPP RFC’s.  There is no intent to redefine the statuses included in the EPP RFC’s in anyway.

> 
> All of the descriptions will need similar attention. Some of them (such as clientUpdateProhibited) currently have 2119 words in the description. That doesn't make sense - this is a status, not an protocol instruction, and trying to put normative language in a registry will lead to confusion about where the behavior you are trying to describe is actually defined. (To be fair, 5731 has this same problem). Again, I suggest following the style that's already in the registry and say something like "The client has requested that any requests to update this object instance be rejected."
> 
> 

The clientUpdateProhibited status is defined as:

clientUpdateProhibited = client update prohibited;  For DNR that
       indicates the client requested that requests to update the object
       (other than to remove this status) MUST be rejected.

Where do you see 2119 words in the clientUpdateProhibited description?  The status descriptions were taken from the EPP RFC’s with no intent on changing their meaning.  

> Minor Issues:
> 
> You're setting up a minor maintenance headache for any future work that might update this document by having the descriptions listed in two places. I don't think it's necessary to list the descriptions in section 2 (currently the bulk of page 4 and the beginning of page 5). Instead, stop after the paragraph that ends at the top of page 4, and note that the descriptions of each new status code are provided in section 3.

The desire was for section 2 to stand on its own to define the statuses and the mapping, and for section 3 to be used to register the statuses in registry.  I believe it would be cleaner to duplicate the descriptions in this instance.  

> 
> Nits:
> 
> Near the end of page 3, the document says "In the DNR, the client and server prohibited statuses are separate an RDAP MUST support the same separation." There are several nits to address with this. That MUST is not a good use of 2119. DNR hasn't been expanded (and "the DNR" is not particularly clear).
> 
> "EPP provides status codes that allow distinguishing the case that an action is prohibited because of server policy from the case that an action is prohibited because of a client request. The ability to make this distinction needs to be preserved in RDAP.”
> 

This change will be made.

---

From: "Gould, James" <[email-masked]>
Date: Mon, 10 Oct 2016 17:43:48 +0000

I incorporated Robert Sparks feedback and made the following editorial changes in the just published draft-ietf-regext-epp-rdap-status-mapping-02 draft:

Replaced the reference of “redemptionPeriod” to “redemption period” to use the RDAP form
Replaced the reference of “domain name” to “object” to not tie it to one object type
Replaced the reference of “registrar” to “client” and “registry” to “server” to be more consistent across the descriptions

Please review draft-ietf-regext-epp-rdap-status-mapping-02 and provide any feedback.

Thanks,

—

JG

James Gould
Distinguished Engineer
[email-masked] <applewebdata://3E726A32-6A60-4928-9840-5BA9DC4FC7E7/[email-masked]>

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

> On Oct 10, 2016, at 11:28 AM, Gould, James <[email-masked]> wrote:
> 
> Robert,
> 
> <BF09FAA4-32D8-46E0-BED0-CD72F43BD6E0[81].png>
> 
> James Gould
> Distinguished Engineer
> [email-masked] <x-msg://81/[email-masked]>
> 
> 703-948-3271
> 12061 Bluemont Way
> Reston, VA 20190
> 
>> On Oct 5, 2016, at 4:58 PM, Robert Sparks <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>>.
>> 
>> All of the descriptions for the new rdap status codes start with "For DNR that indicates". This implies that there is a "For not DNR" case that's not discussed. I don't think the phrase is necessary and each description should look more like the other descriptions already registered at http://www.iana.org/assignments/rdap-json-values/rdap-json-values.xhtml <http://www.iana.org/assignments/rdap-json-values/rdap-json-values.xhtml>.
>>

---

From: Robert Sparks <[email-masked]>
Date: Tue, 11 Oct 2016 11:00:47 -0500

Responses inline -

On 10/10/16 10:28 AM, Gould, James wrote:
> *James Gould
> *Distinguished Engineer
> [email-masked]
> VerisignInc.com <http://VerisignInc.com>
>
>> "For DNR that indicates if the object is deleted by the registrar 
>> during this period, the registry provides a credit to the registrar 
>> for the cost of the auto renewal"
>>
>> That discusses something (and not the only thing) that can happen 
>> while the object is in that state. It does not describe the state.
>>
>> registration period expires and when its registration is 
>> automatically renewed by the registry."
>>
>> I don't think it's important to include the commentary about 
>> providing a credit if the entity is deleted by the registrar during 
>> this period, but since that commentary exists in 3915, you can 
>> include it if you want. The _important_ part to convey is the actual 
>> status.
>
>
> The “For DNR that indicates” can be removed from the descriptions. 
>  For example, the "addPeriod = add period; For DRN that indicates if 
> the object is …”  mapping could be "addPeriod = add period; If the 
> object is …”.  The purpose of this draft is to map the statuses 
> defined in EPP and RDAP, so the status descriptions included in the 
> draft where taken from the EPP RFC’s.  There is no intent to redefine 
> the statuses included in the EPP RFC’s in anyway.
But you are not including the entire EPP definition for most of these - 
you are only copying in _part_ of it, and it's not the important part.
Looking at -02 of the draft, you currently have this:

    addPeriod = add period;  If the object is deleted by the client
        during this period, the server provides a credit to the client
        for the cost of the registration.

Where did you take the definition out of the EPP suite though?
On a fast skim, I assumed you took it from this statement in RFC3915:

    addPeriod: This grace period is provided after the initial
       registration of a domain name.  If the domain name is deleted by
       the registrar during this period, the registry provides a credit
       to the registrar for the cost of the registration.

You left out "The grace period is provided after the initial 
registration of a domain name" which is what the the status _is_. That's 
what the status code is conveying. The extra words about credit after 
deletion are commentary about things that can happen while the object is 
in that state.

(And you're already changing words by using "the client" instead of "the 
registrar".)

Maybe you took the state definition from some other place?

Many of the other definitions in this document have that same problem.

>
>>
>> All of the descriptions will need similar attention. Some of them 
>> (such as clientUpdateProhibited) currently have 2119 words in the 
>> description. That doesn't make sense - this is a status, not an 
>> protocol instruction, and trying to put normative language in a 
>> registry will lead to confusion about where the behavior you are 
>> trying to describe is actually defined. (To be fair, 5731 has this 
>> same problem). Again, I suggest following the style that's already in 
>> the registry and say something like "The client has requested that 
>> any requests to update this object instance be rejected."
>>
>>
>
> Where do you see 2119 words in the clientUpdateProhibited description? 
>  The status descriptions were taken from the EPP RFC’s with no intent 
> on changing their meaning.
You copied it - above - it's the MUST.
This is 5731's issue - that MUST should have been in text about what 
servers do with requests received while the object is in that state, 
instead of being part of the state definition, and the state description 
in a registry.
I understand not wanting to risk introducting confusion by restating a 
definition since you are simply wanting to take the EPP definitions 
completely, so it's probably the better trade-off to propagate that 
problem rather than fix it in this document.

>> Minor Issues:
>>
>> You're setting up a minor maintenance headache for any future work 
>> that might update this document by having the descriptions listed in 
>> two places. I don't think it's necessary to list the descriptions in 
>> section 2 (currently the bulk of page 4 and the beginning of page 5). 
>> Instead, stop after the paragraph that ends at the top of page 4, and 
>> note that the descriptions of each new status code are provided in 
>> section 3.
>
> The desire was for section 2 to stand on its own to define the 
> statuses and the mapping, and for section 3 to be used to register the 
> statuses in registry.  I believe it would be cleaner to duplicate the 
> descriptions in this instance.
As I note, this is a minor issue, but I disagree. Cleaner for _who_? 
It's certainly not cleaner for the anyone who has to revise this 
document (and it's not cleaner for you as the editor of this document or 
the RFC editor since you have to make any change in two places, risking 
having the document become internally inconsistent). I don't see how 
it's cleaner for the implementer of the specification either.

>> separation." There are several nits to address with this. That MUST 
>> is not a good use of 2119. DNR hasn't been expanded (and "the DNR" is 
>> not particularly clear).
>>
>> this distinction needs to be preserved in RDAP.”
>>
>

---

From: "Gould, James" <[email-masked]>
Date: Wed, 12 Oct 2016 14:27:05 +0000

Robert,

Thanks again for reviewing the draft and providing feedback.  I reply to your replies below.  

—

JG

James Gould
Distinguished Engineer
[email-masked] <applewebdata://4A1F47AC-1925-4268-B05E-E5A4B8964D1B/[email-masked]>

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

> On Oct 11, 2016, at 12:00 PM, Robert Sparks <[email-masked]> wrote:
> 
> Responses inline -
> 
>> <Mail Attachment.png>
>> [email-masked] <x-msg://92/[email-masked]>
>> 
>> 703-948-3271
>> 12061 Bluemont Way
>> Reston, VA 20190
>> 
> But you are not including the entire EPP definition for most of these - you are only copying in _part_ of it, and it's not the important part.
> You left out "The grace period is provided after the initial registration of a domain name" which is what the the status _is_. That's what the status code is conveying. The extra words about credit after deletion are commentary about things that can happen while the object is in that state.
> 
> (And you're already changing words by using "the client" instead of "the registrar".)
> 

Yes, this is the text block from RFC 3915 that was used as the basis for the description.  I disagree that the extra words about credit after deletion are commentary, since that is really the point of the status.  The status does not do anything other than to inform the client / registrar that a credit will be given upon deletion.  I can add the “This grace period is provided after the initial registration of a object” and look to add similar text to the other statuses.  Does that meet your concern?  

The reason for the change in the terms (object instead of domain name, client instead of registrar, and server instead of registry) is based on your prior feedback of not tying the statuses to the Domain Name Registries (DNR).  Does providing more generic descriptions make sense to you?  

> This is 5731's issue - that MUST should have been in text about what servers do with requests received while the object is in that state, instead of being part of the state definition, and the state description in a registry.
> I understand not wanting to risk introducting confusion by restating a definition since you are simply wanting to take the EPP definitions completely, so it's probably the better trade-off to propagate that problem rather than fix it in this document. 
> 

Got it, thanks.

> As I note, this is a minor issue, but I disagree. Cleaner for _who_? It's certainly not cleaner for the anyone who has to revise this document (and it's not cleaner for you as the editor of this document or the RFC editor since you have to make any change in two places, risking having the document become internally inconsistent). I don't see how it's cleaner for the implementer of the specification either.
> 

We can agree to disagree on this one.  It is cleaner for the user of the document.  As the editor of the document, it’s not an issue.  Section 2 provides the description of the mapping and section 3 is for IANA consideration to get the missing statuses registered into RDAP JSON Values Registry.

---

From: Robert Sparks <[email-masked]>
Date: Wed, 12 Oct 2016 09:44:49 -0500

On 10/12/16 9:27 AM, Gould, James wrote:
>> On Oct 11, 2016, at 12:00 PM, Robert Sparks <[email-masked] 
>> <mailto:[email-masked]>> wrote:
>>
>> Responses inline -
>>
>>
>>>> All of the descriptions for the new rdap status codes start with 
>>>> "For DNR that indicates". This implies that there is a "For not 
>>>> DNR" case that's not discussed. I don't think the phrase is 
>>>> necessary and each description should look more like the other 
>>>> descriptions already registered at 
>>>> include it if you want. The _important_ part to convey is the 
>>>> actual status.
>>>
>>>
>>> draft where taken from the EPP RFC’s.  There is no intent to 
>>> redefine the statuses included in the EPP RFC’s in anyway.
>> But you are not including the entire EPP definition for most of these 
>> - you are only copying in _part_ of it, and it's not the important part.
>> registration of a domain name" which is what the the status _is_. 
>> That's what the status code is conveying. The extra words about 
>> credit after deletion are commentary about things that can happen 
>> while the object is in that state.
>>
> Yes, this is the text block from RFC 3915 that was used as the basis 
> for the description.  I disagree that the extra words about credit 
> after deletion are commentary, since that is really the point of the 
> status.  The status does not do anything other than to inform the 
> client / registrar that a credit will be given upon deletion.  I can 
> add the “This grace period is provided after the initial registration 
> of a object” and look to add similar text to the other statuses.  Does 
> that meet your concern?
It will.
>
> The reason for the change in the terms (object instead of domain name, 
> client instead of registrar, and server instead of registry) is based 
> on your prior feedback of not tying the statuses to the Domain Name 
> Registries (DNR).  Does providing more generic descriptions make sense 
> to you?
I understand. I'm pointing to the tension between the goals of matching 
the style of the existing rdap registry and not changing the definitions 
from EPP. Don't fret it much. Your argument against trying to avoid 
accidentally failing to preserve the meaning of the EPP status is 
compelling, so I wouldn't object to staying as close to the exact words 
in 3915 as you can.
>>>> same problem). Again, I suggest following the style that's already 
>>>> in the registry and say something like "The client has requested 
>>>> that any requests to update this object instance be rejected."
>>>>
>>>>
>>>
>>> Where do you see 2119 words in the clientUpdateProhibited 
>>> description?  The status descriptions were taken from the EPP RFC’s 
>>> with no intent on changing their meaning.
>> instead of being part of the state definition, and the state 
>> description in a registry.
>> I understand not wanting to risk introducting confusion by restating 
>> a definition since you are simply wanting to take the EPP definitions 
>>>> that might update this document by having the descriptions listed 
>>>> in two places. I don't think it's necessary to list the 
>>>> descriptions in section 2 (currently the bulk of page 4 and the 
>>>> beginning of page 5). Instead, stop after the paragraph that ends 
>>>> at the top of page 4, and note that the descriptions of each new 
>>>> status code are provided in section 3.
>>>
>>> statuses and the mapping, and for section 3 to be used to register 
>>> the statuses in registry.  I believe it would be cleaner to 
>>> duplicate the descriptions in this instance.
>> document (and it's not cleaner for you as the editor of this document 
>> or the RFC editor since you have to make any change in two places, 
>> risking having the document become internally inconsistent). I don't 
>> see how it's cleaner for the implementer of the specification either.
>>
>
> We can agree to disagree on this one.  It is cleaner for the user of 
> the document.  As the editor of the document, it’s not an issue. 
>  Section 2 provides the description of the mapping and section 3 is 
> for IANA consideration to get the missing statuses registered into 
> RDAP JSON Values Registry.
>
>>
>>>>
>>>> Nits:
>>>>
>>>> Near the end of page 3, the document says "In the DNR, the client 
>>>> and server prohibited statuses are separate an RDAP MUST support 
>>>> the same separation." There are several nits to address with this. 
>>>> That MUST is not a good use of 2119. DNR hasn't been expanded (and 
>>>> "the DNR" is not particularly clear).
>>>>
>>>> "EPP provides status codes that allow distinguishing the case that 
>>>> an action is prohibited because of server policy from the case that 
>>>> an action is prohibited because of a client request. The ability to 
>>>> make this distinction needs to be preserved in RDAP.”
>>>>
>>>

---

From: "Gould, James" <[email-masked]>
Date: Wed, 12 Oct 2016 21:12:59 +0000

Robert,

I posted draft-ietf-regext-epp-rdap-status-mapping-03 that incorporates the remainder of your feedback.  Let me know if you find anything else.

Thanks,

—

JG

James Gould
Distinguished Engineer
[email-masked] <applewebdata://FDD96ADC-7474-4285-AC67-555FD5D1A08E/[email-masked]>

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

> On Oct 12, 2016, at 10:44 AM, Robert Sparks <[email-masked]> wrote:
> 
> 
> 
>> [email-masked] <x-msg://110/[email-masked]>
>> 
>> 703-948-3271
>> 12061 Bluemont Way
>> Reston, VA 20190
>> 
>>> On Oct 11, 2016, at 12:00 PM, Robert Sparks <[email-masked] <mailto:[email-masked]>> wrote:
>>> 
>>> Responses inline -
>>> 
> I understand. I'm pointing to the tension between the goals of matching the style of the existing rdap registry and not changing the definitions from EPP. Don't fret it much. Your argument against trying to avoid accidentally failing to preserve the meaning of the EPP status is compelling, so I wouldn't object to staying as close to the exact words in 3915 as you can.
>> 
>> 
>>> 
>>>> 
>>>>>

---

From: Jari Arkko <[email-masked]>
Date: Thu, 13 Oct 2016 02:13:17 +0300

Many thanks Robert for the review, and thank you James for the edits.

Jari