[regext] AD Review: draft-ietf-regext-org

[Adam Roach <[e-mail]>]

This is my AD review for draft-ietf-regext-org-08.  I have a handful of
comments below that I'd like to see addressed prior to asking the IESG to
consider the document.  Please treat them as you would any other last-call
comments.

I also have one comment that needs to be addressed prior to IETF last call.

Thanks to everyone who worked on this document.

---------------------------------------------------------------------------

This comment (and only this comment) is blocking, and needs to be addressed
prior to IETF last call.

§4.1.1:

 >  In addition to the standard EPP command elements, the <check> command
 >  MUST contain a <org:check> element that identifies the organization
 >  namespace.

Is the intention here to be more restrictive than normal XML namespace
handling? For example: is it intended to outlaw cases in which the org
namespace is defined in an ancestor element? Given that the rest of XML
processing is in line with normal XML behavior, this exception would 
need some
justification in this document, or a citation to a document that 
provides such
justification.

This issue arises in other parts of the document for <org:chkData>,
<org:info>, <org:infData>, <org:create>, <org:creData>, <org:delete>,
<org:update>, and <org:panData>.


===========================================================================

General:

Examples of elements that contain user-facing strings (<msg> and 
<org:reason>,
for example) should probably contain "lang" attributes, even when using the
default of English, so as to encourage readers of the examples to implement
localization features.

---------------------------------------------------------------------------

§2:

Please update the boilerplate to match RFC 8174.

---------------------------------------------------------------------------

§3.2.3:

 >  A role MAY have a third party assigned identifier such as the IANA ID
 >  for registrars.  Its corresponding element is <org:roleid>.

Shouldn't this element be called "roleID", to match the convention for 
other EPP
identifiers? (e.g., clID, crID, upID)

---------------------------------------------------------------------------

§3.4:

 >  An organization object MUST always have at least one associated
 >  status value.  The default value is "ok".

What is meant by "default" here? Is this the value to be assumed if the 
element
is omitted? If that’s the case, please say so specifically. If this is 
simply
saying that the most common value is "ok," then rephrase to say that.

---------------------------------------------------------------------------

§3.4:

 >  o  linked: The organization object has at least one active
 >     association with another object.  The "linked" status is not
 >     explicitly set by the client.  Servers SHOULD provide services to
 >     determine existing object associations.

Given that this is a normative requirement, you need a normative reference
here to the specification by which such services are provided.

---------------------------------------------------------------------------

§3.5:

 >  A role SHOULD have at least one associated status value. Valid
 >  values include "ok", "linked", "clientLinkProhibited", and
 >  "serverLinkProhibited".  The default value is "ok".

Same comment as above about "ok" as default.

---------------------------------------------------------------------------

§3.6:

 >  Loops SHOULD be prohibited.  If organization A has B as parent
 >  identifier, organization B must not have organization A as parent
 >  identifier.

This is confusing on a couple of fronts. It starts with a "SHOULD be
prohibited," followed by a "must not have" that *appears* to be stating 
the same
thing. While the second sentence appears to be a non-normative example, 
it still
needs to take care not to contradict normative language by appearing to
strengthen it.

The other bit of confusion is that the second sentence is not stated as an
example, and so its omission of larger loops (e.g., A->B->C->A) might be 
read to
indicate that they are not problematic. I would suggest rephrasing along 
these
lines:

    Loops SHOULD be prohibited. For example: if organization A has B
    as its parent identifier, organization B should not have organization
    A as its parent identifier. The same is true for larger loops involving
    three or more organizations.

---------------------------------------------------------------------------

§3.7:

 >  The URL represents the organization web home page, as defined with
 >  the <org:url> element.

Is there any intention to limit the scheme here? Like, is ftp okay? Is coap?

---------------------------------------------------------------------------

§4.1.1:

 >  o  An OPTIONAL <org:reason> element that MAY be provided when an
 >     object cannot be provisioned

"OPTIONAL" is redundant with "MAY" here. Pick one to be normative, and 
use the
non-uppercase form for the other.

---------------------------------------------------------------------------

§4.1.2:

 >  o  A <org:roid> element that contains the Repository Object

Shouldn't this element be called "roID", to match the convention for 
other EPP
identifiers? (e.g., clID, crID, upID)

---------------------------------------------------------------------------

§4.1.2:

 >     If an internationalized form (type="int") is provided,
 >     element content MUST be represented in a subset of UTF-8 that can
 >     be represented in the 7-bit US-ASCII character set.

This falls apart if UTF-16 is used, as explicitly allowed (even if not
recommended) by section 6. I would suggest this be rephrased to simply say
"the subset of Unicode in the range U+0020 - U+007E."

This comment is also applicable to the similar text in sections 4.2.1 
and 4.2.5.

---------------------------------------------------------------------------

§4.1.2:

 >  o  An OPTIONAL <org:voice> element that contains the organization's
 >     voice telephone number.

This is underspecified. I would expect to see something like
https://tools.ietf.org/html/rfc5733#section-2.5 (or a citation to that 
section).

This is also applicable to similar language in sections 4.2.1 and 4.2.5.

---------------------------------------------------------------------------

§5, Page 34:

 >   <complexType name="checkType">
 >     <sequence>
 >       <element name="id" type="contact:checkIDType"/>
 >       <element name="reason" type="eppcom:reasonType"
 >        minOccurs="0"/>
 >     </sequence>
 >   </complexType>

The "reason" element needs to have a "maxOccurs" of greater than one
(presumably "unbounded") to allow for the conveyance of reasons in multiple
languages.

---------------------------------------------------------------------------

§6:

Please cite UTF-8 (RFC 3629) and UTF-16 (RFC 2718).

---------------------------------------------------------------------------

§7.3:

 >  The following values should be registered by the IANA in the "EPP
 >  Organization Role Values" registry.  The registration policy for this
 >  registry is "Expert Review" [RFC8126].

It's not clear, from this text, that the document is asking to create a new
table. I would recommend making that clearer in this section.


===========================================================================

My remaining comments are minor editorial points.


General:

The examples use "http" for all of the organization URLs. With the current
industry shift to use https instead of http, it would probably be better 
to use
"https" in such examples.

---------------------------------------------------------------------------

§2:

 >  "org-1.0" in is used as an abbreviation for
 >  "urn:ietf:params:xml:ns:org-1.0".

I can't find where this abbreviation is used. I suggest removing this 
sentence.

---------------------------------------------------------------------------

§3.2.1:

 >  An organization role MUST have a type which support a list of values.

"...which supports..."

---------------------------------------------------------------------------

§3.2.3:

 >  A role MAY have a third party assigned identifier such as the IANA ID

"...third-party-assigned..."

---------------------------------------------------------------------------

§3.3:

 >  All EPP contacts are identified by a server-unique identifier.
 >  Contact identifiers are character strings with a specific minimum
 >  length,

Should this say "specific" or "specified"? If "specific" is correct, I would
expect to see the specific number either in this document or in another
document that is referenced here.

---------------------------------------------------------------------------

§3.6:

 >  Take a reseller organization for example, the parent identifier is

"...organization, for example. The..."
                 ^            ^
---------------------------------------------------------------------------

§4.1.1:

 >  In addition to the standard EPP command elements, the <check> command
 >  MUST contain a <org:check> element

"...contain an <org:check>..."


---------------------------------------------------------------------------

§4.1.2:

 >  o  A <org:id> element that contains the server-unique identifier of
 >     the organization object to be queried.

"An <org:id>..."

 >  o  A <org:roid> element that contains the Repository Object

"An <org:roid>..."

 >  o  One or more <org:role> elements that contains the role type, role

"...that contain..."

 >     *  A <org:type> element that contains the type of the

"An <org:type>..."

 >     *  One or more <org:status> elements that contains the role

"...that contain..."

 >     *  An OPTIONAL <org:roleid> element that contains a third party
 >        assigned identifier, such as IANA ID for registrars, as defined
 >        in Section 3.2.3.

"...third-party-assigned..."

---------------------------------------------------------------------------

§4.1.2 (at the bottom of Page 13):

 >  Example <info> response for "Example Reseller Inc." organization
 >  object of reseller type managed by identifier "registrar1362":

This should say "reseller1362".

---------------------------------------------------------------------------

§4.2.1:

 >  o  A <org:id> element that contains the desired server-unique

"An <org:id>..."

 >  o  One or more <org:role> elements that contains the role type, role

"...that contain..."

 >     *  A <org:type> element that contains the type of the

"An <org:type>..."

 >     *  Zero or more <org:status> elements that contains the role

"...that contain..."

 >     *  An OPTIONAL <org:roleid> element that contains a third party
 >        assigned identifier

"...third-party-assigned..."

 >  o  Zero of more <org:status> element that contains the operational

"Zero or more <org:status> elements that contain the..."
        ^                          ^             ^

 >        +  A <org:city> element that contains the organization's city.

"An <org:city>..."

 >        +  A <org:cc> element that contains the organization's country

"An <org:cc>..."

---------------------------------------------------------------------------

§4.2.1:

 >  EPP command elements, the <delete> command MUST contain a
 >  <org:delete> element

"...an <org:delete> element..."

 >  o  A <org:id> element that contains the server-unique identifier of

"An <org:delete> element..."


---------------------------------------------------------------------------

§4.2.5:

 >  o  A <org:id> element that contains the server-unique identifier of

"An <org:id>..."

 >  MAY be omitted if an <update> extension is present. The OPTIONAL
 >  <org:add> and <org:rem> elements contain the following child element:

"...following child elements:"

 >  o  Zero or more <org:role> elements that contains the role type, role

"...that contain..."

 >     *  A <org:type> element that contains the role type of the

"An <org:type>..."

 >     *  Zero or more <org:status> elements that contains the role

"...that contain..."

 >  o  Zero or more <org:status> element that contains the operational

"...that contain..."

 >     *  A <org:name> element that contains the name of the

"An <org:name>..."

 >        +  A <org:city> element that contains the organization's city.

"An <org:city>..."

 >        +  A <org:cc> element that contains the organization's country

"An <org:cc>..."

---------------------------------------------------------------------------

§4.3:

 >  o  A <org:id> element that contains the server-unique identifier of

"An <org:..."

 >  o  A <org:paTRID> element that contains the client transaction

"An <org:..."

 >  o  A <org:paDate> element that contains the date and time describing

"An <org:..."


/a