Subject: [weirds] Review of draft-ietf-weirds-boostrap-06

From: Alexander Mayrhofer <[email-masked]>
Date: Tue, 16 Sep 2014 12:02:20 +0000

I've reviewed the bootstrap document. Generally, i think it does what it is supposed to do, but could use some editorial work and some definitions / clarifications: 

There we go:

**  1. Introduction: 

"extracts" instead of "extract", "does" instead of "do"

** 3. Structure: 

-  "version id identified as a timestamp" etc.. sounds confusing. change to proper definition of metadata
- Further, i think the whole document would benefit from defining a name for the several sub-arrays, because "the second third-level array" makes me look it up each time. I suggest using this section to define the "Entries" array, and the "Base URL" arrays, and use that terminology in subsequent sections. Sometimes those "Entries" seem to be called "keys" subsequently in the document? Clarify on terminology.
- There's no text about recommended sorting in the "Entries" array

** 4. Domain RDAP registry

- I find it weird (sic!) that the *definition* starts with an example. The definition should go first, and after that an example should be illustrative. It even gets more confusing reading the last sentence of that section "This example is not normative". To which of the two examples does this refer? Suggest to change the section so that formal definition comes first, and example follows.
- Again, we have the "first array" and "second array" issue here. I think everybody knows what is supposed to happen, but i don't think that's formal enough for a Proposed Standard.

** 5. Internet Numbers

- Again, this could benefit from being clear which "array" is being searched, in order to remove ambigiuity... 
- The description here is better than in section 4, because the definition comes first, followed by examples.
- Text explaining what is in the "second array" is repetitive ("... which is an array of RDAP URLS..."). Again, defining a name for the Arrays in the document would make it clearer
- (Same for the V6 section, where the text is repeated 1:1)

** 5.3. AS numbers

- funny enough, the text defines a name for the "first arrays" here ("AS Numbers array").  Besides that, my comment from above apply again.

** 6. Entity

- I'm unsure if the "could be queried" text tries to RECOMMEND some kind of client behaviour? It seems vague. 
- On the other hand, where is the client behaviour actually specified (Disclaimer: I have yet to read the other drafts). I can't find in the document that the client MUST or SHOULD use those URLs once it has discovered them (besides the text in the Introduction) -> Add this text?

** 7. 

- The "error behaviour" of the client is much more precisely specified than the "success" bahaviour anywhere else in the document... I take that as an indication that we tend to be pessimists? ;-) We should also specify the "success" behaviour of the client (see above)

** 8. Deployment Cons.

- "fetch registry every time" -> "fetch registry on every RDAP request"
- I would actually be even stronger on the caching, and make that a MUST. This can be dangerous if clients get too creative..
- Typo "garanteed"

** 9. Limitations

- Change text slightly so that types don'T need to be prefixed with "for" everytime?
- I'm confused by the "queries using search patterns", and have no idea what that means (but, again, i have yet to read the other documents thoroughly)

** 10. Security considerations

- "Clients" rather than "End users"? I don't see how the registry makes sure that an entity that is not even defined for the document scope gets whatevery kind of information... If "end user" is defined in another RDAP document, refer there for terminology.

** 11. IANA

- Without having an insight into the hallway discussions with IANA, i understand that the definition of Registries would require more information (see RFC5226, Section 4). Specifically, a registration policy etc. is required. Also, change control in case a revision of the Bootstrap document was to be done. However, i guess this is all up to discussion between document shepherds and IANA...  I do 

tia,
Alex