Re: [weirds] About to push the approve button, but...

[Pete Resnick <[e-mail]>]

On 12/31/14 1:46 PM, Andy Newton wrote:
>> On json-response, Stephen's last two points:
>>
>> On 10/30/14 8:47 AM, Stephen Farrell wrote:
>>      
>>> - p21, the list following the example contains items that were
>>> not in the example - this is unclear writing. Are you saying
>>> that the list is normative or not? If so, you need to say so.
>>> If not, why go beyond the example? The same point applies to
>>> the lots of other examples that follow.
>>>        
> Well, this is a general problem with describing JSON without a schema language: clarity relies on the copious use of examples. This section lays out an example of entity as it might be rendered by an RIR, then lays out the normative structure, then gives an elided example, then gives an example as it might be rendered by a DNR. I fail to see how rearranging things helps or giving an example with ALL valid fields would be clearer. And the words "This object has the following members” precedes the list. How can that be made clearer?
>    

I think it's the "This" that's the problem: It's not that the object in 
the above example has the following members; it's that an object of the 
particular type *can* contain the following members. Saying that is 
probably a good idea. So for 5.1:

The entity object class can contain the following members:

For 5.2, simply s/has/can contain, and so on for the other sections. 
That would certainly clarify.

>>> - 10.2.X: there's a lot of stuff here that wasn't described. I
>>> wouldn't be surprised if that causes interop problems.
>>>        
> Every value in that section as a description field. And to my knowledge, none of it has shown up as an issue in our interop sessions.
>    

Seems like a satisfactory response to me.

>> and both of Ted's points:
>>
>> On 10/29/14 2:40 PM, Ted Lemon wrote:
>>      
>>> Point 1:
>>>
>>> In 4.3:
>>>     It is the job of the clients to determine line breaks, spacing and
>>>     display issues for sentences within the character strings of the
>>>     "description" array.  Each string in the "description" array contains
>>>     a single complete division of human readable text indicating to
>>>     clients where there are semantic breaks.
>>>
>>> What do you mean by "semantic breaks"?   Paragraph breaks?   Sentence
>>> breaks?   Dependent clause breaks?   This doesn't make sense.   I'm not
>>> going to raise a discuss on it because I don't think it affects
>>> interoperability, but I have no idea how to implement a client to display
>>> this in a way that will make sense to the user.
>>>        
> This was discussed on the list and, as I recall, there was an issue over these being considered paragraph breaks. The current words raised no objections. We can change it, but it is just gonna make somebody else unhappy for little benefit.
>    

I'm OK with leaving it. It's basically saying that the creator of the 
array decided on where to put breaks, and the interpreter of the array 
can do what it will with that information.

>>> Point 2:
>>>
>>> A general question that occurred to me in reading 5.5, which also applies
>>> to 5.4: should you have some text talking about how the link member of a
>>> network or autnum object is generated?  Both networks and autnum objects,
>>> as I understand it, can be gotten by querying any number in the range
>>> they enclose.   But of course the link member isn't going to enumerate
>>> all the possible queries that could return the particular object
>>> containing that link member.   So how is the value that's returned
>>> chosen?  Is it the lowest number in the range?   The number that was used
>>> in the query that returned the object?   Some other number?
>>>
>>> I don't think you need to change anything, but it might be worth
>>> discussing this in sections 5.4 and 5.5.
>>>
>>>        
> I don’t think text discussing how to generate links will be helpful because the solution is just to pick a number (perhaps the lowest or highest) in the range and go for it. Or use object handles (synthetic keys). It’s an implementation issue that could have many solutions.
>    

Ack.

So, I wouldn't mind a quick edit of those lines in json-response, and 
I'll consider the rdap-query issues addressed.

Thanks.

pr

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