[art] Artart last call review of draft-ietf-regext-epp-registry-maintenance-17

[Harald Alvestrand via Datatracker <[e-mail]>]

Reviewer: Harald Alvestrand
Review result: Almost Ready

I have reviewed this document as part of the ARTART review team.

Verdict: Almost ready
There are a few things that need better definitions to be comprehensible enough
for interoperable implementation. There is also one confusing formatting error
that should be fixed before publication.

Weak definitions:

- "Maintenance event" is never defined. From context, it is possible to infer
that a maintenance event refers to some service being partially or wholly
unavailable in the time interval given; given that this is the whole point of
the document, this should be explicit. It should also be explicit that the
service will be either fully and correctly available or not available at all,
and that no harm (apart from being denied service) will come from trying to
access the service in the maintenance interval; "maintenance" that, for
instance, puts a test database up where the normal database is would be just a
broken service, not "maintenance" in this sense. (If broken stuff might happen,
I think you need a new impact value in addition to "full", "partial" or "none"
- something like "STAYAWAYYOUWILLREGRETEVENTHINKINGABOUTTRYING").

- "maint:connection" and "maint:implementation" make very little sense as
described. They may refer to having to reconnect the EPP service or to upgrade
the EPP schema in use, but since the "maint:name" element of "maint:system"
seems to encompass WHOIS and others, the actions that may be required are not
clear; an instruction to "do something connection-related" cannot be
interoperably implemented. Suggestion: Either delete these elements or (if
intended to be consumed by a human) add the option to add a text description of
what should be done.

- pollType seems somewhat strange. The implicit definition seems to be that the
client polls the server and the server replies with a list of outstanding
maintenance events, with the value "create" returned the first time the server
tells the client about the event. This implies that the server is required to
keep state of what it has told each client about the event; same goes for event
deletion. If such a state tracking requirement is indeed intended, this should
be explicit.

Formatting issues:

In the list of elements in section 3, the indentation of <maint:environment>
and the succeeding elements indicates that it is an element of <maint:systems>.
Examples indicate that it is an element of <maint:item>, which makes a lot more
sense.

Precision in definition issues:

The incantation "The extended date-time form using upper case "T" and "Z"
characters defined in ISO 8601 [RFC3339] MUST be used to represent date-time
values." is not precise (I don't know if it's common) - it seems to claim that
RFC 3339 is ISO 8601, which is just confusing. Suggested format: "The date-time
format defined as "date-time" in [RFC3339], with time-offset="Z", MUST be used".

Styllistic issues:

The cuteness of using "upDate" as both meaing "update" and "this is a date"
hurts the eyes :-) Unless there is tradition for this name, I'd suggest being
boring and using "updateDate".

Having migration considerations before item descriptions looks a bit weird when
reading the document top to bottom. Would it be nicer to move it after section
4?

I have not attempted to verify the schema, nor have I attempted to check the
document against common styles for EPP extensions. If comments touch on things
that are mandated by common EPP practices, feel free to consider these comments
overridden.

Hope this is helpful.