Subject: Re: [weirds] AD Evaluation of draft-ietf-weirds-using-http-05

From: Ning Kong <[email-masked]>
Date: Tue, 4 Jun 2013 23:31:52 +0800

Hi Pete,

Thanks for your review. Please see our (Andy, Byron and myself) feedbacks inline.

> Section 3 says:
> 
>   Second, multiple response formats are supported by this protocol.  At
>   present the IETF Web Extensible Internet Data Service (WEIRDS)
>   working group is defining only a JSON [RFC4627] response format, but
>   server operators may use other data formats when those formats are
>   requested.
> 
> However, section 4.1 says:
> 
>   RDAP clients MUST include an Accept: header field specifying
>   application/rdap+json, application/json, or both.  Servers receiving
>   an RDAP request MUST return an entity with Content-Type application/
>   rdap+json.
> 
> Why are those two not contradictory?
We think the wording in Section 3 needs to be rewritten so as to not be contradictory:

Second, the semantics of the request/response allow for future and/or non-standard response formats. At present, the IETF Web Extensibility Internet Registration Data Service (WEIRDS) working group is defining only a JSON [RFC4627] response format, and this document only describes how RDAP is transported using HTTP with this format.

> Section 5.1:
> 
>   it encodes the answer in the format most appropriate according to the
>   standard and defined rules for processing the HTTP Accept header
>   field, and return that answer in the body of a 200 response.
> 
> The first part is a little convoluted. Does it simply mean, "it encodes the answer appropriately based on the HTTP Accept header field"? Also, grammatical nit: s/return/returns.
This can be simplified to the following:

If a server has the information requested by the client and wishes to respond to the client with the information according to its policies, it returns that answer in the body of a 200 response.

> Section 5.2:
> 
>   If a server wishes to inform a client that the answer to a given
>   query can be found elsewhere, it MUST return a 301 response code to
>   indicate a permanent move, or a 307 response code to indicate a non-
>   permanent redirection, and include an HTTP(s) URL in the Location:
>   header field.
> 
> Is that MUST there for interoperability reasons? That is, is it plausible that a server might choose something other than 301 or 307 and this document is specifically limiting the server to only choose 301 or 307? The same question for including the URL in the Location header field. If it *is* a specific limitation, I suggest a minor rewording to make it clearer:
> 
>   If a server wishes to inform a client that the answer to a given
>   query can be found elsewhere, it MUST return either a 301 response
>   code to indicate a permanent move, or a 307 response code to indicate
>   a non- permanent redirection, and it MUST include an HTTP(s) URL in
>   the Location: header field.
> 
> If it is not a limitation, but rather just a statement of what the server does, I suggest:
> 
>   If a server wishes to inform a client that the answer to a given
>   query can be found elsewhere, it returns a 301 response code to
>   indicate a permanent move, or a 307 response code to indicate a non-
>   permanent redirection, and includes an HTTP(s) URL in the Location:
>   header field.
As for the response codes, technically 301 and 307 are not the only choices for redirections. 302 and 303 can also work based on RFC 2616 but maybe are not best choices. So we think MUSTs are necessary for the response codes.

Based on the section 10.3.2 of RFC 2616, if a 301 response code is received, a new permernent URI SHOULD be given by the Location field in the response. So it's not necessary to use MUST for "include an HTTP(s) URL in the Location: header field".

So, we'd like to use the following text based on your first one:

If a server wishes to inform a client that the answer to a given query can be found elsewhere, it MUST return either a 301 response code to indicate a permanent move, or a 307 response code to indicate a non-permanent redirection, and it includes an HTTP(s) URL in the Location: header field.

> I have similar questions for the MUSTs in 5.3 and 5.4 and the SHOULD in 5.5.
Based on RFC 2616, 404 and 400 both are the appropriated choices. So the MUSTs in the section 5.3 and 5.4 are not necessary. The same conclusion for 429 can be given by the RFC 6585, so the SHOULDs in section 5.5 are not necessary either.

So we'll rewrite these three sections soon based on the above analysis.

> Section 6:
> 
> I'd like to understand the exceptions that exist that justify SHOULD/SHOULD NOT instead of MUST/MUST NOT for the name syntax.
The reason for SHOULD NOT instead of MUST NOT is that violation of these rules will not cause interoperability with all implementations, just those using the methods outlined in the last paragraph of that section.

> The syntax itself allows a name of "X______". It also imposes no length limit. Is that OK?
There is no length limitation in the JSON standard. So we think this is ok.

> Section 8.2: Shouldn't this registration go in draft-ietf-weirds-json-response? Also, the reference to 6839 is Informative, not Normative, as far as I can tell.
We think it's in here because json-query needs it too. The working group insisted on it being in this doc. And 6839 should be informative.

> Section 9.1: I think the MAYs in there could turn out badly. Might I suggest instead:
> 
>   Clients can use IRIs [RFC3987] for internal use as they see fit, but
>   MUST transform them to URIs [RFC3986] for interaction with RDAP
>   servers.  RDAP servers MUST use URIs in all responses, and again
>   clients can transform these URIs to IRIs for internal use as they see
>   fit.
> 
> The MAYs seem to imply that there are places in the protocol where they MAY use IRIs, and AFAICT that's not true.
We like this wording much better.

> Appendix B: s/MAY/can. You're not really specifying a protocol option here.
Agreed.

> Appendix C: A note in here for the RFC Editor to remove this section would be useful.
Agreed.

Cheers,
Ning

---

From: Pete Resnick <[email-masked]>
Date: Tue, 4 Jun 2013 14:44:20 -0500

> Second, the semantics of the request/response allow for future and/or non-standard response formats. At present, the IETF Web Extensibility Internet Registration Data Service (WEIRDS) working group…

OK, but I think that reveals another potential problem: I was going to 
suggest that instead of, "At present, the IETF Web Extensibility 
Internet Registration Data Service (WEIRDS) working group is defining 
only a JSON [RFC4627] response format", because referring to the WG in 
the document isn't the best, that perhaps you'd rather say, "At present, 
only a JSON [RFC4627] response format is being defined", but that led me 
to want to add "in [draft-ietf-weirds-json-response]". And there's your 
problem. Section 4.1 is requiring (as in, a "MUST") the use of the JSON 
format, which sounds to me like a normative dependency on 
draft-ietf-weirds-json-response.

You need to decide whether you want to write a more generic HTTP draft, 
in which case mandating that the application/rdap+json MUST be used is 
inappropriate, or if this draft is inextricably linked to the use of 
JSON, in which case you'll want to make a normative reference to 
-response, and I'll wonder why this draft is being advanced at a 
different time than the others.

> If a server has the information requested by the client and wishes to respond to the client with the information according to its policies, it returns that answer in the body of a 200 response.

That's fine.

> As for the response codes, technically 301 and 307 are not the only choices for redirections. 302 and 303 can also work based on RFC 2616 but maybe are not best choices. So we think MUSTs are neces…

Does "not the best choices" mean that clients receiving those responses 
won't work as well (i.e., an interoperability issue), or does it mean 
simply that they are not the most descriptive and therefore 
aesthetically less pleasing? It seems to me that saying "not the best 
choices" does not imply "MUSTs are necessary". If the former, your 

> If a server wishes to inform a client that the answer to a given query can be found elsewhere, it MUST return either a 301 response code to indicate a permanent move, or a 307 response code to indi…

If the latter, perhaps my second suggestion is better.

> So we'll rewrite these three sections soon based on the above analysis.

Excellent.

> The reason for SHOULD NOT instead of MUST NOT is that violation of these rules will not cause interoperability with all implementations, just those using the methods outlined in the last paragraph…

Ah, I now understand. That's fine.

> There is no length limitation in the JSON standard. So we think this is ok.

That's fine. And you are also OK with a single ALPHA followed by only 
underscores? That's fine with me if that's your intention.

> We think it's in here because json-query needs it too. The working group insisted on it being in this doc.

This goes back to the issue of whether this document should be requiring 
JSON or whether it should be left to other documents.

>   And 6839 should be informative.
>    

OK.

> We like this wording much better.

Great.

>> Appendix C: A note in here for the RFC Editor to remove this section would be useful.

Cool.

Thanks for working on this.

pr

-- 
Pete Resnick<http://www.qualcomm.com/~presnick/>
Qualcomm Technologies, Inc. - +1 (858)651-4478

---

From: Pieter Vandepitte <[email-masked]>
Date: Wed, 05 Jun 2013 09:10:28 +0200

Hi

> You need to decide whether you want to write a more generic HTTP
> draft, in which case mandating that the application/rdap+json MUST be
> used is inappropriate, or if this draft is inextricably linked to the
> use of JSON, in which case you'll want to make a normative reference
> to -response, and I'll wonder why this draft is being advanced at a

Pete has a point here. I think currently the drafts are very much 
depending on each other (which is not necessarily a problem)

I think if it almost definitely sure other content types will ever be 
introduced in the future, it would be better to split up documents into 
a
- data model document: abstract data model (not json, really abstract)
- data binding document: binding of the model to some content type: 
e.g. json or xml
- protocol document: abstract protocol (currently searches and 
lookups), messages and allowed responses
- protocol binding: rest binding, soap binding, thrift, protobuf, avro, 
... binding

On the other hand, the charter states it will define a 'simple' 
protocol and so my question is if we will ever need to have such a 
heavy weight rfc.
imho i would remove the "multiple response formats supported". It 
probably won't happen.

I'm having another issue with the same draft. I'm currently working on 
an implementation and for me it's unclear which object MUST be returned 
by which response code.
e.g. can a 404 for a /domain/xxx query return a domain object? I'm 
looking for a way to make a differentiation to the client whether a 
registration is not found but available and whether a registration is 
not found and not available because it is not supported (like 
characters not allowed)... one solution is to return a domain object 
with different statuses, another is to return an error object with 
different titles.

Any recommendations?

Pieter

---

From: Ning Kong <[email-masked]>
Date: Thu, 6 Jun 2013 10:18:24 +0800

Hi Pete,

Please see our feedbacks inline.  

> OK, but I think that reveals another potential problem: I was going to suggest that instead of, "At present, the IETF Web Extensibility Internet Registration Data Service (WEIRDS) working group is defining only a JSON [RFC4627] response format", because referring to the WG in the document isn't the best, that perhaps you'd rather say, "At present, only a JSON [RFC4627] response format is being defined", but that led me to want to add "in [draft-ietf-weirds-json-response]". And there's your problem. Section 4.1 is requiring (as in, a "MUST") the use of the JSON format, which sounds to me like a normative dependency on draft-ietf-weirds-json-response.
> 
> You need to decide whether you want to write a more generic HTTP draft, in which case mandating that the application/rdap+json MUST be used is inappropriate, or if this draft is inextricably linked to the use of JSON, in which case you'll want to make a normative reference to -response, and I'll wonder why this draft is being advanced at a different time than the others.
We agree that this document should be a more generic HTTP draft. So we'd like to remove the MUSTs from section 4.1.

If WG agree with that direction, we'd like to check and modify the wording of JSON in the whole draft soon.

> Does "not the best choices" mean that clients receiving those responses won't work as well (i.e., an interoperability issue), or does it mean simply that they are not the most descriptive and therefore aesthetically less pleasing? It seems to me that saying "not the best choices" does not imply "MUSTs are necessary". If the former, your suggestion is fine:
> 
After re-discussion among us, we don't think using a 302 or 303 would be an interoperability problem, as long as clients understand all four redirect codes adequately, so maybe we should drop the MUSTs and expand to mention all the redirects. We recall a discussion early on about not profiling HTTP that might apply here.

So the modified text is based on your second suggestion as following:

If a server wishes to inform a client that the answer to a given query can be found elsewhere, it returns either a 301 response code to indicate a permanent move, or a 302, 303 or 307 response code to indicate a non-permanent redirection, and it includes an HTTP(s) URL in the Location: header field.

> That's fine. And you are also OK with a single ALPHA followed by only underscores? That's fine with me if that's your intention.
X__ does not violate the reasoning given in the second paragraph of that section, so we think we don't care. A future IETF RFC could very well define FOO____ and that would be fine.

> This goes back to the issue of whether this document should be requiring JSON or whether it should be left to other documents.
I think even if JSON is not mandatory in HTTP draft, it still makes sense to keep this section in this draft. Because this section is needed by not only one document.

Cheers,
Ning

---

From: Ning Kong <[email-masked]>
Date: Thu, 6 Jun 2013 10:39:02 +0800

Hi Pieter,

Thanks for your comments. Please see my feedbacks inline.

> … binding
I don't think RDAP protocol will definitely become complicated if multiple response formats could be allowed. IMO, it's deficient that RDAP protocol can only support one special response format. 

I partly agree with your first idea. We'll try to make it as a more generic HTTP draft in the next version. I don't want this document become a HTTP-JSON draft ;-) 

Any more comments from you are appreciated.

> with different statuses, another is to return an error object with 
I prefer the second one. That is to say, a 404 response code with different customized "error" information.

Cheers,
Ning

---

From: "John Levine" <[email-masked]>
Date: 6 Jun 2013 10:19:52 -0000

>I don't think RDAP protocol will definitely become complicated if multiple response formats
>could be allowed. IMO, it's deficient that RDAP protocol can only support one special response
>format. 

Do you really think that other formats will be standardized and documented?

Remember that a standard doesn't prevent private extensions.  It
defines the features that servers and clients have to implement to
interoperate.  As I understand it, RDAP clients and servers exchange
JSON, and we decided some time ago not to support XML and other
formats as part of the spec.

---

From: Ning Kong <[email-masked]>
Date: Sat, 8 Jun 2013 15:41:15 +0800

Hi John,

> Do you really think that other formats will be standardized and documented?
I'm not sure. IMO, the other formats may not be necessarily documented because they can be transformed by the JSON response document.

> interoperate.
I agree.

> As I understand it, RDAP clients and servers exchange

Could you please provide some references for this conclusion?

IMHO, even if XML and other formats will never be documented by WEIRDS WG, they should not be forbidden by RDAP protocols. The RDAP specs should provide an interopration mechanism for RDAP clients and servers to signal and identify these formats, just like using the Accept Header Field for JSON format.

Cheers,
Ning

---

From: "John R Levine" <[email-masked]>
Date: 8 Jun 2013 10:20:09 -0400

> I'm not sure. IMO, the other formats may not be necessarily documented because they can be transformed by the JSON response document.

I think we agree here.  If they're not documented, there's no reason for 
the standard to mention them.  Remember that IETF standards are voluntary, 
so they don't have to give anyone permission to do anything.

> Could you please provide some references for this conclusion?

We discussed it at great length on the list, the only response format is 
JSON.  Again, if you want to provide XML or anything else as a private 
extension, that's fine, but there's no reason for the standard to say 
anything about it.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
"I dropped the toothpaste", said Tom, crestfallenly.

---

From: Andy Newton <[email-masked]>
Date: Sat, 8 Jun 2013 15:12:29 +0000

>extension, that's fine, but there's no reason for the standard to say

John is right. This issue has been discussed on the mailing list several
times.

The intent of the language is to provide for the following:

1) Future specifications in other data formats. In fact, the rules behind
JSON naming are constructed to allow automatic conversion to XML and we
use to have an algorithm in this draft which showed how to do it. However,
nobody was interested in it and that got ripped out. But the possibility
is always there, though we'll likely never do it.

2) The use of RDAP URLs in the browser bars of web browsers to get
non-RDAP results. The ARIN service does this today by returning XHTML or
plain text, and many people find it handy. That doesn't mean we intend
generic web browsers to be RDAP clients. It just means we see the utility
of using RDAP query URLs in web browsers for non-RDAP purposes. Though I
said #1 is unlikely to happen, it is likely that some server operators
will do this.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Fri, 14 Jun 2013 10:01:32 -0500

So, where are we with this document? I think all of my questions were 
answered and it sounded like the WG was moving toward some changes, but 
I haven't seen a new version yet. I'm holding off on the Last Call for 
the -sec document (which is ready to go) so that I can send the two 
together.

I'll mark this in the tracker as "Revised ID Needed" so that it reminds 
me when you create a new version. But let's move this along. Do you need 
anything else from me?

pr

---

From: Andy Newton <[email-masked]>
Date: Fri, 14 Jun 2013 15:57:55 +0000

Thanks Pete. We'll get cracking on a new version of the draft.

-andy

On 6/14/13 11:01 AM, "Pete Resnick" <[email-masked]> wrote:

>_______________________________________________
>weirds mailing list
>[email-masked]
>https://www.ietf.org/mailman/listinfo/weirds
>

---

From: Ning Kong <[email-masked]>
Date: Tue, 18 Jun 2013 23:22:42 +0800

Hi Pete,

I just posted draft-ietf-weirds-using-http-06 to address your comments. Any further comments are appreciated.

Cheers,
Ning

> So, where are we with this document? I think all of my questions were answered and it sounded like the WG was moving toward some changes, but I haven't seen a new version yet. I'm holding off on the Last Call for the -sec document (which is ready to go) so that I can send the two together.
> 
> I'll mark this in the tracker as "Revised ID Needed" so that it reminds me when you create a new version. But let's move this along. Do you need anything else from me?
> 
> pr
> 
> --

---

From: Pete Resnick <[email-masked]>
Date: Tue, 18 Jun 2013 10:33:00 -0500

> I just posted draft-ietf-weirds-using-http-06 to address your comments. Any further comments are appreciated.

Two weeks ago, you sent the following message.

> If WG agree with that direction, we'd like to check and modify the wording of JSON in the whole draft soon.

I see that the new draft still has MUSTs for JSON in section 4.1, still 
defines the registry for JSON responses, and still has no normative 
reference to the -json-response document. The other changes look fine, 
but the genericizing activity does not seem done. Is there some reason 
for this?

pr

---

From: Ning Kong <[email-masked]>
Date: Wed, 19 Jun 2013 00:24:25 +0800

Hi Pete,

> I see that the new draft still has MUSTs for JSON in section 4.1, still defines the registry for JSON responses, and still has no normative reference to the -json-response document. The other changes look fine, but the genericizing activity does not seem done. Is there some reason for this?

Sorry for not clarifying this issue in advance.

Based on the recent discussions on this thread, there is a consensus that the only response format is JSON. So we finally didn't modified the section 4.1. We re-modified the wording in section 3 as follows.

   Second, the semantics of the request/response allow for future and/or
   non-standard response formats.  In this document, only a JSON
   [RFC4627] response media type is defined, with the response contents
   to be described separately.  This document only describes how RDAP is
   transported using HTTP with this format.

This allows for future bis or other updates to obsolete or update this document with additional MIME types, but otherwise simply locks it down to JSON for now. Doing this we think resolves the conflict with 4.1 without needing to change that section.

IMHO, this document only focuses on how RDAP is transported using HTTP, but doesn't cover the response data structure in JSON. So a normative reference to the -json-response document is not necessary.

Cheers,
Ning

---

From: Andy Newton <[email-masked]>
Date: Tue, 18 Jun 2013 17:54:59 +0000

On 6/18/13 12:24 PM, "Ning Kong" <[email-masked]> wrote:

>>> We agree that this document should be a more generic HTTP draft. So
>>>we'd like to remove the MUSTs from section 4.1.
>>> 
>Based on the recent discussions on this thread, there is a consensus that
>the only response format is JSON. So we finally didn't modified the
>section 4.1. We re-modified the wording in section 3 as follows.
>
>This allows for future bis or other updates to obsolete or update this
>document with additional MIME types, but otherwise simply locks it down
>to JSON for now. Doing this we think resolves the conflict with 4.1
>without needing to change that section.
>
>IMHO, this document only focuses on how RDAP is transported using HTTP,
>but doesn't cover the response data structure in JSON. So a normative
>reference to the -json-response document is not necessary.

To build upon Ning's response, the registry for the JSON values was moved
to this document from the json-response document by the working group.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Tue, 18 Jun 2013 15:42:37 -0500

On 6/18/13 12:54 PM, Andy Newton wrote:
> On 6/18/13 12:24 PM, "Ning Kong"<[email-masked]>  wrote:
>
>    
>> section 4.1.

That's fine, but that means that 4.1 is requiring something with a MUST 
(i.e., JSON responses) that this document does not define. That is, you 
cannot comply with all of the MUSTs in the document without reading the 

>> reference to the -json-response document is not necessary.

No, it is absolutely necessary if you make this choice. This document is 
unimplementable now without -json-response.

> to this document from the json-response document by the working group.

And now this is more problematic. The registration for the JSON values 
(especially the media type) presume a payload format that you have not 
defined in this document. Unless I am misunderstanding something, the 
registration of the media type is missing what goes in the payload. That 
can't be a legitimate registration.

Please explain.

pr

---

From: Andy Newton <[email-masked]>
Date: Wed, 19 Jun 2013 10:18:32 +0000

>can't be a legitimate registration.

Understood, and thanks Pete.

The draft authors feel this question needs to be asked of the working
group. There are two ways to proceed:

1. Move the media type to json-response and change of the subsequent
requirements; or
2. Add a normative reference to json-response and accept the delay in
publishing using-http.

The draft authors are partial to #1, and in the absence of feedback will
modify the draft in that respect.

Does anybody in the working group have an opinion about either of these
options?

-andy

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Wed, 19 Jun 2013 07:41:50 -0700

> Does anybody in the working group have an opinion about either of these
No hat:

I don't have a preference either way.  I also don't think the delay
identified in #2 is a big concern for me; is there some reason we should
avoid it?

-MSK

---

From: Andy Newton <[email-masked]>
Date: Wed, 19 Jun 2013 16:28:55 +0000

From: "Murray S. Kucherawy" <[email-masked]<mailto:[email-masked]>>
Date: Wednesday, June 19, 2013 10:41 AM
To: Andrew Newton <[email-masked]<mailto:[email-masked]>>
Cc: Pete Resnick <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [weirds] AD Evaluation of draft-ietf-weirds-using-http-05

I don't have a preference either way.  I also don't think the delay identified in #2 is a big concern for me; is there some reason we should avoid it?

If the publication of the draft is to be delayed, then why do we have a milestone for it so early? I think that is one of the drivers.

I do think that #2 would keep the MUST language, which is contrary to the other edits we just made.

-andy

---

From: Pete Resnick <[email-masked]>
Date: Wed, 19 Jun 2013 11:44:26 -0500

> 2. Add a normative reference to json-response and accept the delay in

And to be perfectly clear: I do not wish to express a preference on 
this; as AD, I am happy to bring either choice to Last Call and to the 
IESG. It's just that I can't figure out how the document is currently 
consistent with either of these two. So effectively is a third choice:

3. Explain why it is OK as it is.

I'm assuming that you are only listing the above two choices because you 
agree with me that there is a problem. If you think there is not a 
problem (especially if the WG agrees), let's not spend time changing the 
document, but rather "getting Pete's head right." If, on the other hand, 
I've convinced you that there is a problem, I am fine with either of the 
two choices.

pr

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Wed, 19 Jun 2013 16:30:35 -0700

On Wed, Jun 19, 2013 at 9:28 AM, Andy Newton <[email-masked]> wrote:

>   From: "Murray S. Kucherawy" <[email-masked]>
> To: Andrew Newton <[email-masked]>
> Cc: Pete Resnick <[email-masked]>, "[email-masked]" <
> [email-masked]>
>  If the publication of the draft is to be delayed, then why do we have a
> milestone for it so early? I think that is one of the drivers.
>
The milestone says "to the IESG', not "published as an RFC".  We have
little enough control over the actual publication process that I would
avoid including it in a time estimate.  Barring some major problem
discovered during IESG Evaluation, I consider the milestone reached when
the document enters IESG Evaluation state.  It may still have to wait for
something else before the RFC Editor can publish it, but that doesn't mean
the WG hasn't completed its work.

-MSK, behatted