[weirds] AD Evaluation of draft-ietf-weirds-json-response-09

[Pete Resnick <[e-mail]>]

Summary: Almost ready for Last Call, but definitely needs a rev first

None of these issues are complicated or showstoppers, but there are a 
number of them, along with a few questions. So I'd like to have the WG 
address these before I Last Call the document.

Throughout - Use of "client" and "server" in this document sometimes 
seems strained. Mostly you're talking about interpreters/parsers and 
producers/generators. You might want to review this throughout. I've 
made some specific comments below.

Also note that I have not reviewed all of the examples in detail. I hope 
the WG has done a good scrub.

1 - I would mention in the first paragraph that using-http defines a 
communications protocol for exchanging queries and responses.

It seems like maybe the Terminology section should come before 
everything else in this section, given that a lot of the terminology is 
used here.

In the second to last paragraph, either lowercase the MUST or make it 
"needs to". It's not an interoperability statement.

3.1 - I think if you take my suggestion in the intro, you don't need 
this section.

3.2 - You went a little MUST/SHOULD/MAY crazy in this section. I hope 
the following suggested replacements are helpful (and I replace "client" 
with "parser" and "server" with "generator" in my example):

Paragraph 1:

    Parsers of these JSON responses SHOULD ignore unrecognized JSON
    attributes in responses. Generators can insert values into the JSON
    responses which are not specified in this document, but that does not
    constitute an error in the response. Generators which insert such
    unspecified values into JSON responses SHOULD have names prefixed
    with a short identifier followed by an underscore followed by a
    meaningful name.  These short identifiers aid software implementers
    with identifying the specification of the JSON name, and failure to
    use one could cause an implementer to assume the generator is
    erroneously using a name from this specification.  This allowance
    does not apply to jCard ([RFC7095]) objects.  The full JSON name (the
    prefix plus the underscore plus the meaningful name) SHOULD adhere to
    the character and name limitations of the prefix registry described
    in [I-D.ietf-weirds-using-http].  Failure to use these limitations
    could result in slower adoption as these limitations have been given
    to aid some client programming models.

Next to last paragraph:

    Parsers processing JSON responses need to be prepared for values
    specified in this document to be absent from a response, as no JSON
    value listed is required to appear in a response.  In other words,
    generators are free to not included values based on their own
    policies.

4 - I don't think the reference to 1166 is necessary. Dotted-decimal 
notation is well-known enough. Simply strike, "described in [RFC1166]", 
and the reference.

5.1 - Oh, do I hate the word "conformance"! Of course, I will likely 
survive. I also wonder why you went with "rdap_level_0" instead of a 
numeric RFC number here. But again, I will live.

    When custom JSON values are inserted into responses,
    conformance to those custom specifications SHOULD use a string
    prefixed with the appropriate identifier from the IANA RDAP
    Extensions registry specified in [I-D.ietf-weirds-using-http].

So, I presume that "SHOULD" is there because collisions would be bad. If 
that is the case, I would simply say, "MUST use a string...in order to 
avoid collisions", because I can't think of a good reason not to. If 
slower adoption (noted later) is the only reason for the SHOULD, then 
it's bogus and ought to be removed.

5.2 -

    The
    "value", "rel", and "href" JSON values MUST be specified.  All other
    JSON values are optional.

I presume the "MUST be specified" is there because this is a requirement 
of 5988, not because it is a new requirement of this document. If so, 
change that to "are required by [RFC5988]". If this is a new requirement 
of this document, then there should be an explanation of why this is 
required, and the "optional" in the second sentence should be "OPTIONAL".

5.5 - If you're going to use a SHOULD, I should be able to figure out 
why this is a requirement and what exceptions there are to make it a 
SHOULD and not a MUST. Neither is clear. If this isn't a real 
requirement, then I would change "SHOULD be" it "is" and be done with it.

5.9 -

    This data structure, named "objectClassName", gives the object class
    name of a particular object as a string.  This aids clients in
    identifying the type of object being processed.  Servers MUST NOT
    omit this string so that clients can more easily identify the type of
    object.

"Aids" clients? "MUST NOT omit this string so that clients can more 
easily identify"? These seem like really weak reasons. How about simply 
the following?

    This data structure, named "objectClassName", gives the object class
    name of a particular object as a string.  This identifies the type of
    object being processed.  An objectClassName is REQUIRED in all RDAP
    response objects so that the type of the object can be interpreted.

6 -

    When present, clients MAY use the self link for caching data.

I don't understand that MAY. What option is trying to be conveyed here? 
Is this a using-http thing?

    Self links SHOULD contain a "type" element containing the
    "application/rdap+json" media type when referencing RDAP object
    instances as defined by this document.

Again, no explanation of why it SHOULD contain a "type" element, and no 
explanation of a reason for an exception. Please explain.

    Clients SHOULD NOT assume
    self links without this media type are represented as RDAP objects as
    defined by this document.

I'm not sure how to implement a "SHOULD NOT assume". Do you really mean 
something like the following?

    Clients MAY/SHOULD/MUST discard objects containing self links without
    a media type, as they might not be RDAP objects as defined by this
    document.

6.1 -

    For illustrative purposes, it does not include rdapConformance or
    notices data structures.

That sentence occurs a lot throughout the document. Are rdapConformance 
or notices required? If not, I would strike this sentence. If they are 
required, you had better say so back in section 5.

I would move the following:

    Entities may also have other entities embedded with them in an array.
    This can be used to model an organization with specific individuals
    fulfilling designated roles of responsibility.

    The following is an elided example of an entity with embedded
    entities.

and Figure 13 *below* the bulleted list. It confused me here.

    o  vcardArray -- a JSON vCard with the entity's contact information

s/a JSON vCard/one or more JSON vCards. It is an array, after all.

6.4/6.5 -

    o  country -- a string containing the name of the two-character
       country code of the network

Strike "the name of".

7 -

    A client MAY simply use the HTTP response code as the server is not
    required to include error data in the response body.  However, if a
    client wishes to parse the error data, it SHOULD first check that the
    Content-Type header contains the appropriate media type.

This paragraph seems more appropriate for the using-http document.

11.1 - Seems like a reference to rdap-sec might be useful here.

I find it weird (no pun intended) to have an individual be the 
contact/author for a standards registration. Shouldn't it be the IESG or 
the WG or something? Maybe I'll ask Barry.

11.2 -

    This registry should be governed by a designated expert or multiple
    designated experts.  Registration of values into this registry should
    be accomplished by providing the information above to the designated
    expert(s).

Probably simpler (and clearer) for IANA if you simply say, "This 
registry is to be operated under the "Expert Review" policy defined in 
RFC 5226." The IESG will make sure about the one or multiple experts, 
and IANA wil make sure that they get the appropriate information.

Just before 11.2.1, please add: "The following sections provide initial 
registrations into this registry."

I still find it strange to have an individual registrant for these 
registrations.

I did not review the individual registrations in detail.

13.1 -

    Servers
    and clients MAY optionally support other character encodings.

How does *that* work? How is a different encoding indicated? This seems 
like a discussion for the using-http document.

14 - I suspect you're going to be asked for more here. I don't have the 
expertise to give you advice in this area, but you might want to check 
with Alissa Cooper about who might.

pr

-- 
Pete Resnick<http://www.qualcomm.com/~presnick/>
Qualcomm Technologies, Inc. - [phone]