Subject: [yang-doctors] YANG doctor review of draft-ietf-lmap-yang-05

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Aug 2016 14:46:36 +0200 (CEST)

Hi,

I am the assigned YANG doctor for this document.  I have reviewed this
document from a pure YANG standpoint.  I have not checked that the
YANG model matches the information model etc.

As expected, this model is in good shape.  Here are my comments:

o  The typedef glob-pattern use \ in a double qouted string.
   Specifically, it uses the characters \\ which actually expand to a
   single '\'.  Also in YANG 1.1 the sequences \* and \?  are illegal.

   I suggest this text is re-written to avoid backslahses, or that a
   single quote string is used.

o  The device-id is of type inet:uri.  I see that this is specified in
   the information model as well.  But why is it a URI?  As an
   operator, which URI should I choose?

o  lmap/agent/device-id's description says:

           The device-id identifies a property of the
           device running the measurement agent.

   Should this be s/a property of//?  Otherwise, which property is
   being referred to?

o  lmap-state/agent/device-id is marked as 'mandatory true', but its
   description says that is optional.

o  lmap/agent/controller-timeout says that "an event is raised".  What
   kind of event?  Which protocol?  [later] Ok, reading the events
   subtree, I see that there is an event 'controller-lost' there.
   Presumably the text refers to this event.  If so, this text could
   maybe be clarified.

o  In /lmap/events/event/event-type there are a couple of cases that
   are leaf empty, and these leafs are marked as 'mandatory true':

          case immediate {
            leaf immediate {
              type empty;
              mandatory true;
              ...
            }
          }

   I was going to write that this is confusing, but in fact it is
   pretty clever!  No action required!

o  Should the choice /lmap/events/event/event-type be marked as
   'mandatory true'?   Otherwise, what happens if no event-type is
   configured?

o  The descriptions in several nodes in
   /lmap/events/event/event-type/calendar are a bit confusing:

              leaf-list month {
                type lmap:month-or-all;
                min-elements 1;
                description
                  "A month at which this calendar timing will
                   trigger. The wildcard means all months.";

   The description says "_A_ month", but the node is a leaf-list.
   Maybe change to "A set of months".  (same for other nodes in this
   case as well)

o  /lmap/tasks/task/program is optional (and marked as
   nacm:default-deny-write).

   What happens if this leaf is not set?

o  Are /lmap-state/agent/{hardware,firmware} different than
   /system-state/platform/{machine,os-release/os-version} in
   ietf-system?

o  So the MA is supposed to invoke RPCs on a controller.  Is this
   described somewhere?  Are the details left to implementations?

/martin