[regext] some feedback on draft-ietf-regext-rdap-versioning

["Andrew Newton (andy)" <[e-mail]>]

Hi,

I just read through the versioning draft and have some feedback.

1. The first clause of the abstract is confusing to me. Maybe
something like this:

OLD:

This document describes an RDAP extension for an extensible set of
versioning types with the features of identifying the RDAP extension
versions supported by the server, the RDAP extension versions included
in an RDAP response, and enabling a client to specify the desired RDAP
extension versions to include in the RDAP query and RDAP response.

NEW:

This document describes an RDAP extension to describe versioning
meta-data of RDAP extensions to be included in RDAP response, and
describes methods for client signaling of supported extensions. This
extension also specifies two versioning types and a means to add
future versioning types,

Of course, which is clearer is a matter of opinion so take it or leave it.

2. In section 1, the sentence on RDAP conformance values is
misleading. I propose:

OLD:

The RDAP Conformance values are identifiers with no standard mechanism
to support structured, machine-parseable version signaling by the
server.

NEW:

The RDAP Conformance values are identifiers that are by default opaque
in nature.

3. The first bulleted point of section 1 describes a client including
information in an RDAP response. It should be that the client signals
to the server and the server includes the information in the response.

4. Section 3.2 paragraph 1 gives equivalency to both signaling
methods, but the query parameter may not always work. I suggest the
following:

OLD:

The client MAY provide an Extension Versioning Request to indicate the
desired extension versions to include in the RDAP query and RDAP
response. There are two Extension Versioning Request methods with the
Versioning Query Parameter (Section 3.2.1) and the Versioning
Extensions Media Type Parameter (Section 3.2.2). The server MUST
support both methods of Extension Versioning Request methods and the
client MUST use at most a single Extension Versioning Request method
in the RDAP query.

NEW:

The client MAY provide an Extension Versioning Request to indicate the
desired extension versions for inclusion in an RDAP response by a
server. There are two Extension Versioning Request methods: Versioning
Extensions Media Type Parameter (Section 3.2.2) and Versioning Query
Parameter (Section 3.2.1). The Versioning Extensions Media Type
Parameter should be the preferred signaling method as there are known
limitations regarding propagation of query parameters (see
draft-ietf-regext-rdap-extensions). The Version Query Parameter is
used provided to aid in troubleshooting of RDAP services. The server
MUST support both methods of Extension Versioning Request methods and
the client MUST use at most a single Extension Versioning Request
method in the RDAP query.

5. Swap section 3.2.2 and 3.2.1.

6. The "version" JSON member should be marked required in the
"versions" array described in 3.3.2.

7. When troubleshooting RDAP servers, there is other helpful
information that would be greatly beneficial regarding the server
version. I propose defining two objects for "versioning_help", one
about the server and one about the extensions. Here is prototype:

"versioning_help": {
    "server" : {
        "server_id": "1",
        "version": "1.2",
        "type": "semantic",
        ...
    }
    "extensions": [
       {
        "extension": "rdap_level_0",
        "type": "opaque",
        ...
       },
       {
          "extension": "versioning",
          "type": "semantic",
          ...
       }
    ]
}

"extensions" would be the array currently defined in
"versioning_help". "server" would have all the same JSON members as a
"version" object with the addition of "server_id" which is a string
identifying a specific server in a cluster.

-andy