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

From: Pete Resnick <[email-masked]>
Date: Mon, 6 Oct 2014 23:59:47 -0500

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. - +1 (858)651-4478

---

From: Andy Newton <[email-masked]>
Date: Tue, 7 Oct 2014 14:51:11 +0000

Pete,

For the things that need discussion or a reply, response is inline...

>the WG has done a good scrub.

Tom Harrison has found a couple of issues here (that oddly enough passed
my JSON validator) which I¹ll try to incorporate.

>    generators are free to not included values based on their own

As an implementor, I find the change of the wording to parser/generator
more confusing. The JSON parser and generators I have dealt with are
libraries, and the decision to ignore/insert takes place by the RDAP
client or server implementation that uses those libraries.

>required, and the "optional" in the second sentence should be "OPTIONAL".

Good catch. RFC 5988 doesn¹t seem to say what is and what is not required,
though one could get the notion that these are the ones required because
the others all classified as ³link parameters². RFC 4287, which is where
RFC 5988 gets the link structure, only requires href. And that makes sense
as without href it isn¹t a link. So we should change this so that href is
MUST and everything else is OPTIONAL. Does that work?

>requirement, then I would change "SHOULD be" it "is" and be done with it.

I think it is a MUST. If they want to link to an RDAP entity, for
interoperability the link MUST have the right structure.

>Is this a using-http thing?

Clients are required to cache the data at this granularity. So it
shouldn¹t be a MAY. Perhaps changing it to ³can² works.

>explanation of a reason for an exception. Please explain.

No this should be a MUST to guarantee interoperability. Sorry about that.

>    a media type, as they might not be RDAP objects as defined by this

Given the change of the SHOULD to a MUST for creating the self links, I
think we can take out that paragraph entirely.

>    The following is an elided example of an entity with embedded

I don¹t understand this. Move it to where? If you mean remove, why? It is
describing the example that follows and without that description I think
the example doesn¹t work.

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

Actually, we should be calling them jCards. I thought I had changed that.
But the reference to a singular jCard is intentional. We want contact
information for a specific entity, and the jCard standard allows that to
occur within an array. However, we don¹t want the serialization of an
entire address book of jCards referencing unrelated entitiesŠ which the
jCard standard also specifies.

>the WG or something? Maybe I'll ask Barry.

I was just following the example of other registrations. I think it should
be the IESG.

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

Do you mean this specific initial registrations or all the registrations?
I¹m fine changing these initial ones to IESG.

>like a discussion for the using-http document.

As far as I¹m concerned, everything I18N related is black magic. But in
this specific case, we should either take that out or say something like:

   Servers and clients can use other character encodings provided
   they have negotiated data transfer with those encodings via a
   non-standard mechanism.

I lean toward taking it out entirely.

>with Alissa Cooper about who might.

I¹ll send her a message asking for review.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Tue, 7 Oct 2014 12:05:33 -0500

On 10/7/14 9:51 AM, Andy Newton wrote:

> On 10/7/14, 12:59 AM, "Pete Resnick"<[email-masked]>  wrote:
>
>    

Cool.

> client or server implementation that uses those libraries.

That's OK. I can certainly live with the client/server language. Just a 
preference. Are you OK with the rest of my suggested changes (switching 
the terms back to client/server) in this section?

> MUST and everything else is OPTIONAL. Does that work?

Yep, that sounds OK.

> interoperability the link MUST have the right structure.

Well, this might get into one of those cases of, "Why MUST you do this?" 
"Because if you don't, you're an idiot." If someone doesn't use "rel" of 
"related" and "type" of "application/rdap+json", does the an interpreter 
of such an event blow up, or does it just not accomplish something 
useful? If the latter, change "SHOULD be" (or "MUST be") to "is" and be 
done with it.

> shouldn¹t be a MAY. Perhaps changing it to ³can² works.

Makes sense.

> think we can take out that paragraph entirely.

OK.

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

Sorry, I wasn't clear:

I suggested moving that paragraph, and Figure 13, below the bulleted list.

> jCard standard also specifies.

Ah. OK, then it's just the name of the member that confused me. Perhaps 
just calling it a "jcard"? But I'm OK with it either way.

> I was just following the example of other registrations. I think it should

Let's go with IESG. Barry can comment when it gets to IESG Eval.

> I¹m fine changing these initial ones to IESG.

The initial ones.

> I lean toward taking it out entirely.

Taking it out works for me.

> I¹ll send her a message asking for review.

Excellent. Thanks.

pr

---

From: Andy Newton <[email-masked]>
Date: Tue, 7 Oct 2014 19:35:10 +0000

On Oct 7, 2014, at 1:05 PM, Pete Resnick <[email-masked]> wrote:

> That's OK. I can certainly live with the client/server language. Just a preference. Are you OK with the rest of my suggested changes (switching the terms back to client/server) in this section?
> 

Absolutely! I’ll incorporate them.

> Well, this might get into one of those cases of, "Why MUST you do this?" "Because if you don't, you're an idiot." If someone doesn't use "rel" of "related" and "type" of "application/rdap+json", does the an interpreter of such an event blow up, or does it just not accomplish something useful? If the latter, change "SHOULD be" (or "MUST be") to "is" and be done with it.

There is no requirement to link an event to an RDAP entity, or to link the actor of the event to any identifier. But, if a registry wanted to link an event to an RDAP entity, this is what they MUST do.

This is the current wording:

   The 'links' array in this data structure is provided for references
   to the event actor.  If the event actor being referenced is an RDAP
   entity, the link reference SHOULD be made with "rel" of "related" and
   "type" of "application/rdap+json”.

Changing the SHOULD to MUST seems appropriate to me. That’s what they MUST do to link to an RDAP entity. Or perhaps this slight change:

   The 'links' array in this data structure is provided for references
   to the event actor.  If the event actor being referenced is to be an RDAP
   entity, the link reference MUST have a "rel" of "related” and a
   "type" of "application/rdap+json”.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Tue, 7 Oct 2014 15:40:04 -0500

On 10/7/14 2:35 PM, Andy Newton wrote:
> That’s what they MUST do to link to an RDAP entity. Or perhaps this slight change:
>

I won't belabor this one if I'm in the rough, but just one more attempt. :-)

In 5.5, you have:

The "events" array consists of objects, each with the following
members:

You could have said:

The "events" array MUST consist of objects, and each object MUST have
the following members:

But I would say that if you did so, you were being a goofball. Yes, it 
is true that if you want to use "events", the array *will* consist of 
objects, and each object *will* have such and so members, but MUST 
indicates that you might somehow choose to do otherwise and that you 
MUST NOT do otherwise. The reason we don't have to use MUST in this case 
is because if you don't have an array of objects with the appropriate 
members, you simply don't have an "events" array. You don't need a MUST 
when the statement is definitional.

Same thing above. If you're going to link to an RDAP entity, you *will* 
use a "rel" of "related” and a "type" of "application/rdap+json". If you 
don't do that, you're simply not linking to an RDAP entity. There's no 
other path to take. So I'm suggesting:

The 'links' array in this data structure is provided for references
to the event actor. In order to reference an RDAP entity, a "rel" of
"related" and a "type" of "application/rdap+json" is used in the link
reference.

If you disagree, I'll just go weep in my beer. But seriously, I'm fine 
if you want the MUST. I just find it kind of silly.

Sounds like you're all set to go on the rest except for the privacy 
considerations. If you don't hear back soon, make the other changes and 
we can deal with whatever comments we get in Last Call.

pr

---

From: Andy Newton <[email-masked]>
Date: Tue, 7 Oct 2014 20:59:47 +0000

On Oct 7, 2014, at 4:40 PM, Pete Resnick <[email-masked]> wrote:

> Same thing above. If you're going to link to an RDAP entity, you *will* use a "rel" of "related” and a "type" of "application/rdap+json". If you don't do that, you're simply not linking to an RDAP entity. There's no other path to take. So I'm suggesting:
> 
> If you disagree, I'll just go weep in my beer. But seriously, I'm fine if you want the MUST. I just find it kind of silly.

Ah. We’re saying the same thing. I don’t especially care either way, so I’ll take your suggestion.

-andy

---

From: Andy Newton <[email-masked]>
Date: Tue, 7 Oct 2014 21:44:53 +0000

One last thing on this one, Pete…

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

Using-http already has this:

   If a server wishes to respond that it has an empty result set (that
   is, no data appropriately satisfying the query), it returns a 404
   response code.  Optionally, it MAY include additional information
   regarding the negative answer in the HTTP entity body.

So I think the paragraph you mentioned from Section 7 of json-response can simply be deleted.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Tue, 7 Oct 2014 16:55:02 -0500

On 10/7/14 4:44 PM, Andy Newton wrote:
> On Oct 7, 2014, at 12:59 AM, Pete Resnick<[email-masked]>  wrote:
>
>    
>> 7 -
>>

I agree. Thanks.

pr