Subject: Re: [netmod] comments on netmod-yang-05

From: Wes Hardaker <[email-masked]>
Date: Mon, 22 Jun 2009 16:31:31 -0700

Martin,

Sorry about the delay in a response but most of your note didn't need a
response and it fell to my "response not immediately critical" time
frame.

Thanks for incorporating and/or reviewing my suggestions.  I'm only
responding to a few extra points that looked like they needed a more
direct followup.

WH> Section 4.2.3:
WH> The example adds a few things not discussed so far:
WH> "config true;" at the top: what's the default value?  It must be true
WH> based on the other examples?  You should state one way or the other
WH> (maybe in a // comment) that it's the default or not.

MB> The second sentence in 4.2.3 says:

MB> When a node is tagged with "config false",
MB> its subhierarchy is flagged as state data

MB> So it implies that if the node is not tagged with config false, and
MB> does not belong to such a subhierarchy, then it is is config data.

Understood.  The thing I think, though, that might confuse a reader is
why the first "config true;" is in there at all.  If it's the default,
leave it out to show it's the default.

[4.2.8]
MB> How about this rewording, and simplification:

MB> NEW:

MB> YANG allows a module to extend data models with additional nodes.

I agree, that's better.

> 6.1.3:
> 
>   It should be noted that many definitions of "whitespace" include
>   newlines, including standard regular expressions.
> 
>     # perl -l -e 'print "hello" if ("\n" =~ /\s/);'
>     hello
> 
>   But this section deviates from that and discusses whitespace heavily
>   but the examples show that newlines are exempt from being called
>   whitespace (and you really mean just spaces and tabs).  (mostly in the
>   paragraph "trailing whitespace is stripped..." which would remove the \n)

MB> We can't simply s/whitespace/space or tab/.   

Why not?  Or simply state up front that whitespace in this document
means just spaces and tabs and not newlines or returns.

MB> Do you think it would work if we write:

MB> If a string contains any whitespace characters (space or tab), 

I'd make it more explicit because you mention whitespace in multiple
places and adding the () text in each instance you didn't want to do.

>   "A module SHOULD have the following layout:"
> 
>   What if it doesn't?  Does that mean a parser implementation doesn't
>   have to accept it?  (this is an example of text written toward the
>   author when it's the parser implementation that will be the most
>   affected but yet the text doesn't describe the requirements of the
>   implementation).

MB> The exact rules are specified in the grammar.  This text is there to
MB> give the reader a quick overwiew of a what a module contains, instead
MB> of having to figure it out from the grammar.  Would it be better to
MB> write

MB> A module has the following layout:

MB> or would that just make it worse?

err...  Different?

If it's specified somewhere else that you should not expect things to
definitively follow that order, then the SHOULD there is fine.  If I'm
an implementer of a parser all I want is to know whether I need to
support YANG documents that are arbitrarily ordered.

> 7.1.2:
> 
>   Is yang-version technically a string, decimal64 or binary blob?

MB> Or an uint8, uint64...  Does it matter what it is?

Well, people may choose a data type in their code and APIs to pass
around yang version references.  If you later decide that "1.1.1" is a
valid yang version and I had picked an uint8 I'll have to go change a
bunch of APIs and code.  Declaring it up front as a string or a float in
the document prevents implementations from making incorrect choices (and
also limits you in the future, which is likely ok as well).

> 7.7.5:
> 
>   What happens when a client requests data from a system ordered set of
>   data, jumbles it (say makes it alphabetical according to how a user
>   sorted it on the screen) and sends it back (eg, via a replace)?  This
>   isn't discussed...
> 
>   1) can the server reject it?
>   2) does the server have to parse it?

MB> Why would the server reject it?  Since there is no semantic order
MB> defined, the client can send the data in any order, but the server is
MB> free to re-order (but it doesn't have to).

Because it's expensive to reorder if the cheap router server detects the
ordering doesn't match their internal storage ordering requirements?

The "ordered-by server" statement gives me the impression that something
other than me (the user) is deciding what the proper ordering is and
that is decided upon by the server.  The text, however, is not clear as
to whether or not it's allowed that the management console can reorder
at will because it feels like it and the server has to accept it, or if
the server does in deed have authority over the ordering because it's
"the authoritative ordering source" and "thou shall not reorder my
data".

>   3) is the server allowed to define internal semantics of it's own
>      ordering?   (see large routing table implementations)

MB> I don't understand what you mean with "define internal semantics"?

Consider the classic example of route table ordering.  Different router
implementations have different ways of storing routing data that is
optimized for their internal processing requirements.  If I, as a
client, take a set of 10k routes and reorder them arbitrarily and give
it back to the router it may be computationally intensive to reorder
them.

Honestly, I actually don't care one way or the other.  My thinking is
that documenting whether or not something marked as "ordered-by server"
means that ordering CAN be important to the server (but you, the client,
may not know what it is) is probably important.  Simply stating that
"ordered-by server" actually means "no ordering at all and feel free to
jumble at will" is probably sufficient.

Maybe change "ordered-by server" to "ordered-by none" would make more sense.

Wes

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Jun 2009 10:25:03 +0200 (CEST)

Hi Wes,

> leave it out to show it's the default.

Ok.  I will remove the first "config true;" statement.

> places and adding the () text in each instance you didn't want to do.

Ok, I will do s/whitespace/space or tab/ in some places to get e.g:

  If the double quoted string contains space or tab characters before
  a line break, this trailing whitespace is stripped from the string.

Would that work?  

> also limits you in the future, which is likely ok as well).

Ok.   I will state that the argument is a string.  That leaves
us flexibility for the future.

> ordering doesn't match their internal storage ordering requirements?

But again, the cheap server doesn't have to reorder - it can choose to
keep the data in the order it was given by the client, or any internal
order.

> Maybe change "ordered-by server" to "ordered-by none" would make more sense.

The text says:

  Thus an implementation is free to sort the entries in the most
  appropriate order.

What should we write to make it more clear?

/martin

---

From: Wes Hardaker <[email-masked]>
Date: Tue, 23 Jun 2009 10:56:00 -0700

>>>>> On Tue, 23 Jun 2009 10:25:03 +0200 (CEST), Martin Bjorklund <[email-masked]> said:

MB> If the double quoted string contains space or tab characters before
MB> a line break, this trailing whitespace is stripped from the string.

MB> Would that work?  

That looks good.  I didn't check the rest of the text.

MB> Ok.   I will state that the argument is a string.  That leaves
MB> us flexibility for the future.

Agreed; I think that's the right choice (though it does nuke the
possibility of >, == and < comparisons which might be helpful).

Didn't yang module version numbers end up being a float after a
discussion at the last IETF ?  If so, maybe syncing with that would make
the most sense.

MB> The text says:

MB> Thus an implementation is free to sort the entries in the most
MB> appropriate order.

MB> What should we write to make it more clear?

How about:

  Thus an implementation is free to sort the entries in the most
  appropriate order.  A netconf client and server should not expect
  their preferred ordering to be kept consistent by the other side.

-- 
\ Wes Hardaker                           http://pontifications.hardakers.net /
 \_____ "In the bathtub of history the truth is harder to hold than ________/
       \_______ the soap, and much more difficult to find." _______/
               \_________ -- Terry Pratchett ______________/
                         \__________________/