Subject: [weirds] Comments on draft-ietf-weirds-json-response

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 15 Sep 2014 23:21:28 -0700

Hi,

I've reviewed this draft.  Sorry it's last, but it's also the biggest.  :-)

I have the following concerns and editorial suggestions:

1) In Section 1, RESTful is not defined before use.  This is being
discussed on the thread for another document already, so the result of that
debate can be applied here as well.

2) Also in Section 1, "forward DNS names" might be more simply expressed as
"domain names".

3) Also in Section 1, some editorial suggestions:

- s/an JSON object/a JSON object/
- s/object which contains/object that contains/

4) In Section 2, drop the period at the end of each definition and remove
quotes (they aren't needed).

5) Also in Section 2, s/with in/within/

6) In Section 3.1, change one of the "specified"s to "described" or similar.

7) In Section 3.2, the SHOULD NOTs and SHOULDs are stirring up the usual
question: When would it be appropriate to deviate from that advice, and
what might one do instead?

8) Starting about here and throughout the document, there are lots of
"should", "may", "optional", etc. that are all lowercase.  We might get
some whining about the fact that they're RFC2119 words.  You could go
through and tweak the text if you're so inclined to avoid this.

9) In Section 4, some editorial suggestions:

- s/The semantics ... is .../The semantics ... are .../
- s/'handle'/handle/
- s/2 character/two-character/

10) In Section 5, "common data structures used commonly" is redundant.

11) In Section 5.1, this "should" is probably supposed to be a "SHOULD".

12) Also in Section 5.1, there's a reference to a prefix identifier
registry defined in the "using-http" draft, but that draft does not define
a registry by that name.

13) In Section 5.3:

- s/it is contained within/that contains it/
- s/Both are an array/Both are arrays/

14) Also in Section 5.3, the SHOULD NOT can probably just be replaced by
something like:

Each string in the "description" array contains a single complete sentence
indicating to clients where there are semantic breaks in the text.

15) In Section 5.4, I suggest:

This data structure consists solely of a name/value pair, where the name is
"lang" and the value is a string containing a language identifier as
described in [RFC5646].

16) In Section 5.7, should we also allow an IP address?

17) In Section 5.8, do the valid types need to be enumerated?

18) In Section 5.9, why not just require it?

19) In Section 6, another instance of "specified ... specified" in the same
sentence.

20) Also in Section 6, the usual SHOULD/SHOULD NOT questions come up: Under
what conditions might one deviate from this advice?

21) Has anyone tried putting all of the JSON examples through a JSON parser
just to see if they at least conform to basic JSON syntax?

22) In Section 6.2, change "should be the string" to "always the string" or
just "the string".  Same in 6.3, 6.4, and 6.5.

23) In Section 6.3, change instances of "boolean true" to just "true".

24) There are references in Section 6.3 that look like "RFC 4034 RFC 4034
[RFC4034]" that should be tidied up.

25) There are more instances of "specified ... as specified" in the same
sentence in 6.3.

26) Also in 6.3, the "keyData" bullet list has a few entries that end in
periods, unlike the bullets in the rest of the section.

27) Section 6.4 and 6.5: change "2 character" to "two-character".

28) Section 7, "followed by ... followed by" in the same sentence; perhaps
just change the second one to "and"?'

29) Section 8, "as defined ... as defined" in the same sentence; perhaps
just change the second one to "from"?

30) In Section 11.2, why force everything to lowercase rather than just
making comparisons case-insensitive?

31) Also about Section 11.2, it helps the IESG when creating a registry
like this to recommend some people to act as the designated experts.  I
propose we have two DNR and two RIR representatives.  Does anyone want to
volunteer?

32) In Section 11.2.1, "yield" is misspelled as "yeild" in multiple
places.  (Might want to pass the whole thing through a spell checker just
in case.)

33) In Section 11.2.1, registration #3 and #6, the last sentence is kind of
meaningless because retrying might yield a longer result too if whatever
transient condition clears up.  The client doesn't really know either way.
Or am I missing something?

34) In Section 11.2.2, registration #1, I remember this being a topic of
some discussion.  I think it had something to do with the notion of
"validated" being unspecified.  Do we need to say more about that here?

35) In Section 11.2.2, registration #18, "in no longer" should be "is no
longer".

36) In Section 11.2.2, registration #11, is the first document's reference
to EPP.  We need to define that there or someplace earlier (definitions
section, maybe?) and include a defining reference.

37) In Section 12, I suggest we make reference to the Security
Considerations of the using-http document, or to the rdap-sec document, or
both.

38) Section 13.1 mentions XML as if it's an acceptable format.  I don't
think it is, so that should be removed.

39) Appendix F needs a notation like "[RFC Editor: Please delete this
section prior to publication.]"

-MSK

---

From: Andrew Newton <[email-masked]>
Date: Tue, 16 Sep 2014 11:45:57 -0400

> 2) Also in Section 1, "forward DNS names" might be more simply expressed as

Well, that is less accurate as the reverse DNS is also composed of domain names.

> "should", "may", "optional", etc. that are all lowercase.  We might get some
> whining about the fact that they're RFC2119 words.  You could go through and
> tweak the text if you're so inclined to avoid this.

So what is the excepted practice now with 2119? Even uncapitalized
2119 words have 2119 meaning now? Or can we explicitly say up front
that when we want to attach 2119 meaning, those words are in caps?

> 11) In Section 5.1, this "should" is probably supposed to be a "SHOULD".

I don't know about that. Not using the prefix will also likely not
cause problems. Using it is more a matter of style and a way for
programmers to reference back to the IANA registry.

> 16) In Section 5.7, should we also allow an IP address?

Specifying an IP address is bad practice. I would hope most registries
have their whois infrastructure behind load balancers or multiple DNS
entries, etc...

> 17) In Section 5.8, do the valid types need to be enumerated?

As we don't validate them, no.

> 18) In Section 5.9, why not just require it?

Ok.

> just to see if they at least conform to basic JSON syntax?

I have, though not lately. The elided examples require editing though.

> making comparisons case-insensitive?

Since they are identifiers, a straight string comparison is all that
is required. It's also about style of the raw JSON.

>
> 31) Also about Section 11.2, it helps the IESG when creating a registry like
> this to recommend some people to act as the designated experts.  I propose
> we have two DNR and two RIR representatives.  Does anyone want to volunteer?

I can do it.

> "validated" being unspecified.  Do we need to say more about that here?

That would up to individual policy of the registry. I don't think we
should specify it.

-andy

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Tue, 16 Sep 2014 09:34:58 -0700

> Well, that is less accurate as the reverse DNS is also composed of domain

Hmm, right.  I just think "forward DNS" is practically a term of art; end
users won't necessarily know what that means if it appears in the output
they see.

> some

I don't really like this issue either, and I only bring it up because it's
been brought up for other documents in the past.  How it gets resolved
unfortunately depends on who's reviewing it.  The problem is that RFC2119
doesn't say that "SHOULD" only means "SHOULD" when it's in all-caps, which
was probably an oversight when that RFC was written.  Some people suggest
including modified RFC2119 boilerplate that specifically says only the
all-caps versions carry the RFC2119 meaning, others argue that's not
necessary, etc.

I think I brought it up because if we can sidestep it by simply using a
different word, then we avoid the problem altogether.  But it's a pain to
have to do that now.

I guess we can leave this as-is, but it might come back to us later.

> programmers to reference back to the IANA registry.

On re-reading, I actually don't understand the sentence containing that
SHOULD.  Is it trying to encourage operators to use registered prefixes
when using their own custom tokens in responses?

> have their whois infrastructure behind load balancers or multiple DNS

That's interesting... Why is it bad practice?  It's certainly inconvenient
to humans that want to hit the WHOIS server from the command line, but is
it harmful?

> As we don't validate them, no.

OK; I ask because there are other places where "type" refers to something
enumerated, but here it doesn't.

> I have, though not lately. The elided examples require editing though.

OK.  That might be a good idea before this goes up (though I know it's a
bit time consuming).

> is required. It's also about style of the raw JSON.

Does requiring lowercase mean anything to non-English character sets?

> like

Great!  Anyone else, especially at least one DNR representative?

> That would up to individual policy of the registry. I don't think we

OK; I suggest then that we make it explicit that we're punting on this one.

Thanks!
-MSK

---

From: Andrew Newton <[email-masked]>
Date: Tue, 16 Sep 2014 13:05:19 -0400

> users won't necessarily know what that means if it appears in the output

Why would they see it in output? This is just a description of the
types of registries using RDAP.

> all-caps versions carry the RFC2119 meaning, others argue that's not

I'm partial to this solution.

> SHOULD.  Is it trying to encourage operators to use registered prefixes when
> using their own custom tokens in responses?

Yes, and the prefix registry stops collisions.

> to humans that want to hit the WHOIS server from the command line, but is it
> harmful?

For the same reason a website shouldn't use it. If you want to move
that web site to a different host but everybody has the IP address,
that is a problem.

> Does requiring lowercase mean anything to non-English character sets?

I don't know. But since these are protocol tokens and the IETF
specifies things in English, we should probably add "should be
English" to the list.

-andy

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Tue, 16 Sep 2014 11:01:17 -0700

> types of registries using RDAP.

Not all implementers are as thoughtful as you are.  :-)

> > I guess we can leave this as-is, but it might come back to us later.

Let's just leave it.  I admit that I may just be projecting my own prior
battle damage here, and really nobody will notice or care.

> when

OK, can we rework that sentence so it's more clear?

> that web site to a different host but everybody has the IP address,

But if the IP address changes, wouldn't the response start using the new IP
address?

I'll drop it here because I've made my point.  I just wanted to understand
the restriction here when in just about everywhere else I can think of in
application space, either form is allowed.

-MSK