Subject: Re: [netmod] LL review of 6020bis-06

From: Martin Bjorklund <[email-masked]>
Date: Tue, 25 Aug 2015 13:03:59 +0200 (CEST)

Hi Lada,

Thank you for this extensive review!  Comments inline.

Ladislav Lhotka <[email-masked]> wrote:
> Hi,
> 
> this time I reviewed the complete text so my comments aren't limited to
> YANG 1.1 stuff.
> 
> Lada
> 
> **** General comments
>      1. Would it make sense to at least mention that YANG is being
>         used not only for NETCONF and with other encodings?

I think so (and I think that was the general consensus in Prague)
Details TBD.

>      2. I think it would be useful to include text (perhaps in
>         sec. 4.2.2) describing the schema tree and data tree, and
>         introducing appropriate terms so that, e.g., nodes in either
>         tree can be clearly distinguished in the subsequent text. In
>         my experience, this causes a lot of confusion.
> 
> 	For example, sec. 4.2.2.1 says: ' A leaf node contains simple
>         data like an integer or a string.' And then sec. 7.6: ' The
>         "leaf" statement is used to define a leaf node in the schema
>         tree.' If the leaf node is in the schema tree, then it cannot
>         contain any value.

The "leaf" statement defines a node in the schema tree.  This can be
instantiated in a data tree.  A leaf node in the data tree contains a
simple value.

Since section 4.2 is really just intended as an overview, maybe we can
s/A leaf node contains/A leaf contains/ (and similar for container)?

>      3. It's necessary to clearly separate properties of the data tree
>         from properties of XML encoding. For instance, it is an
>         inherent property of a container instance in the data tree
>         that its children are unordered, or ordered in RPC
>         input/output. Yet this is only specified in sec. 7.5.7 (XML
>         Mapping Rules).

I think this is a property of the XML encoding, not an inherent
property of the container.  In JSON, all children are always
unordered.

> 	Similarly, the namespace of a module and XML namespace that's
>         used in XML encoding are IMO two different things (cf. sec
>         5.3).

Yes.  Do you have any specific edits in mind?

>      4. Terms "instance"/"instantiate"/"instatiation" are used in a
>         loose way without being properly defined, probably as SNMP
>         legacy. The XML term "instance document" adds yet another
>         meaning.

I'm not sure these are SNMP specific terms.  I thought they were more
generic.  Do you have any proposed edits?

>      5. A term is needed for describing a data model of a particular
>         server, i.e. a collection of modules + supported features (+
>         deviations). I've used "data model", see
>         https://github.com/mbj4668/pyang/wiki/Tutorial#yang-data-model

The term "data model" is already used in a much more generic way in
6020.

"server YANG data model" maybe.

>      6. As Jürgen suggested, sections "XML Mapping Rules" should be
> 	more appropriately called "XML Encoding Rules".

Fixed.

>      7. I'd remove all mentions of submodules including other
>         submodules, circular includes etc. because it is now
>         confusing. If "include" is ignored in submodules, there is no
>         need to bother with any rules. This sentence in sec. 7.1.6
>         should be enough: 'For backward compatibility with YANG
>         version 1, the "include" statement is permitted in a submodule
>         but has no effect there.'

I found only this sentence:

  Submodules are only allowed to include other submodules belonging to
  the same module.

which I have now removed.

> **** Sec. 3
>      - Shouldn't the term "data tree" also cover the contents of RPC
>        input/output, actions and notifications?

Yes, probably.  But then we need to have a term for some of the
current usages of "data tree".  Maybe "datastore" works (this term is
already used).

> **** Sec. 4.2.2.3
>      OLD
>          A container may contain any number of child nodes of any
>          type (including leafs, lists, containers, and leaf-lists).
>      NEW
>          A container may contain any number of child nodes of any
>          type (leafs, lists, containers, leaf-lists, and actions).

Fixed.

> **** Sec. 4.2.9
>      - Include an example of action?

Fixed.

> **** Sec. 5.2
>      - The last paragraph about separate compilation of submodules
>        looks like an implementation detail and could perhaps be
>        removed.

Fixed.

> **** Sec. 5.5
>      s/closest matching/matching/
> 
>      (because definitions of groupings/typedefs cannot shadow an
>       equally named grouping/typedef in an outer scope)

Fixed.

> **** Sec. 5.6.4
>      - OLD
>            A server implements a module if it implements the module's data
>            nodes, rpcs, notifications, and deviations.
>        NEW
>            A server implements a module if it implements the module's data
>            nodes, rpcs, actions, notifications, and deviations.
>      - s/augement/augment/
>      - spurious string '#}}' at the end.

Fixed.

> **** Sec. 6.1.3
>      I think the rules for whitespace trimming are confusing and have
>      very little practical uses, so I'd recommend to remove them
>      entirely. However, if the decision is to keep them, the following
>      ambiguities need to be addressed:
>      - It is unclear whether '\n' is equivalent to the literal LF
>        character in the trimming process, i.e. whether the
>        substitution of escape sequences is done before or after the
>        trimming.

How does this matter?

>      - Is tab character treated as 8 spaces also before the opening
>        double quote? Example:
> 
>        description "This is a long
>                     text."
> 
>        Does it matter whether the character between "description" and
>        the opening double quote is a space or tab character? (Both
>        cases may have identical visual rendering depending on the
>        column where the statement starts.)

I would think so.  I think whitespace-trimming in general is very
useful, but the tab-expansion is a bit confusing.  I think it would be
ok to remove the expansion of tab with 8 spaces.

> **** Sec. 6.2
>      OLD
>          Implementations MUST support identifiers up to 64 characters in
> 	 length.
>      NEW
>          Implementations are not required to support identifier longer
>          than 64 character.
> 
>      (The current formulation can IMO be understood so that identifiers
>      longer than 64 chars cannot be supported.)

How about:

         Implementations MUST support identifiers up to 64 characters in
         length, and MAY support longer identifiers.

> **** Sec. 6.3.1
>      What does the last paragraph mean? In particular: if an extension
>      is imported and used in a module that the server advertises,
>      could the server ignore that extension?

This is being in discussed in a separate thread.

> **** Sec. 6.4
>      - 'The data model used in the XPath expressions is the same as
>        that used in XPath 1.0 [XPATH], …'
> 
>        I think some explanation is needed describing how a data tree
>        is mapped onto the (restricted) XPath data model. Specifically:
>        * The data tree has no concept of document order, except for
>          RPC input/output. The spec should say implementations need
>          to choose some document order but how it is done is
>          undefined, so XPath expressions in YANG modules shouldn't
>          rely on the document order.

Ok, makes sense.  How about adding a new paragraph three:

  The data tree has no concept of document order.  An implementation
  needs to choose some document order but how it is done is an
  implementation decision.  This means that XPath expressions in YANG
  modules SHOULD not rely on any specific document order.

>        * It might be useful to define how namespace nodes representing
>          YANG namespaces appear in the XPath tree so that the
>          namespace:: axis works in a deterministic fashion. For
>          example, one could say that all these namespaces are in scope
>          for all elements corresponding to YANG data nodes. One could
>          use it, e.g. to determine whether a particular YANG module is
>          a part of the data model.

Why wouldn't the namespace axis work in a deterministic fashion?  All
nodes defined in a module have the same XML namespace, which is
well-defined.

>      - Another possible source of surprises are equality tests (but
>        maybe it belongs to 6087bis). With
> 
>        container top {
>          must "x = y";
>          leaf x {
>            type decimal64 {
>              fraction-digits 1;
>            }
>          }
>          leaf y {
>            type uint8;
>          }
>        }
> 
>        the following instance violates the must constraint:
> 
>        <top>
>          <x>1.0</x>
>          <y>1</y>
>        </top>

If it is belongs anywhere it would be in 6087.  But this is just how
XPath works, so I am not sure it is needed...

> **** Sec. 6.4.1
>      - The accessible tree should also be defined for action
>        input/output.

Fixed.

>      - Canonical values should be used also for RPCs, actions and
>        notifications.

I don't understand what this refers to?

>      - s/all all/all/

Fixed.

> 
> **** Sec. 7.1.5.1
>      - 'The "revision-date" statement MUST match the most recent
>        "revision" statement in the imported module.'
> 
>        This should be removed because otherwise the importing module

>        couldn't stick to an old revision of the imported module.

I think what this tries to say is if a specific revision of a module
is needed (for import by revision), then you must find the module with
exactly that given revision (kind of obvious...).

So I agree that this sentence probably can be removed (done).

> **** Sec. 7.1.6
>      - 'If no "revision-date" substatement is present, it is undefined which
>        revision of the submodule is included.'
> 
>        I think in this case the submodule revisions need to be
>        specified in yang-library.

I think they are.

> **** Sec. 7.5.1
>      - 'In the first style, the container has no meaning of its own,
>        existing only to contain child nodes.'
> 
>        I don't think this is really true, e.g. "must" statement on a
>        NP containers adds meaning to it, see Y41.

Do you have some proposed text?  I don't think the existance of a must
statement in the NP-container changes the fact that its presence has
no meaning.

>      - 'In the second style, the presence of the container itself is
>        configuration data, representing a single bit of configuration
>        data.'
> 
>        What about containers with presence outside config=true data?

Fixed.

> **** Sec. 7.5.7
>      - Is the order of subelements also fixed in action input/output?

Yes, fixed.  (and various other similar places).

> **** Sec. 7.5.8
>      - ' If a container does not have a "presence" statement and the last
>        child node is deleted, the NETCONF server MAY delete the
>        container.'
> 
>        Without further explanation this contradicts the resolution of
>        Y41. It should say at least where such containers may be
>        deleted (e.g. in the reply to <get-config> or <get>).

I don't agree, since the text now says that for validation purposes,
NP containers *always* exist if its parent exists.

> **** Sec. 7.6.1
>      - The text is suitable for config, defaults in RPC input/output
>        and notifications are covered elsewhere, but what about
>        defaults (and mandatory) in state data?

I don't think this text is excludes state data.

> **** Sec. 7.7.1
>      - The term "array" suggests some higher-level data structure (as
>        in JSON encoding). I'd use "sequence of leaf nodes" instead.

I think "array" is ok.

>      - s/firewall filters/packet filter/

Fixed.

> **** Sec. 7.7.4
>      - ' The "default" statement MUST NOT be present on nodes where
>        "min-elements" has a value greater than or equal to one.'
> 
>        Why? This should be OK:
> 
>        leaf-list foo {
>          type uint8;
>          min-elements 1;
>          default 54;
>        }

No, b/c min-elements 1 says that there must be at least one instance,
and the default statement specifies what happens if there are no
instances.

> **** Sec. 7.7.9
>      - Is the interaction of <edit-config> operations, leaf-list
>        default values, and with-defaults modes sufficiently clear?
>        See also the thread starting with
>        https://mailarchive.ietf.org/arch/msg/netmod/PvMzWfzpYa0bg-S2jErX975Y3Jk

I don't know if we need to add anything.  Suggestions?

> **** Sec. 7.8.6
>      - It would be helpful to include an example of yang:key attribute
>        value with multiple (two) keys. I remember somebody asked me
>        about that.

Fixed.

> **** Sec. 7.9.2
>      - The paragraph about shorthand case statement should more
>        explicitly explain that a case node is present in the schema
>        tree even for short-case-stmt, and thus schema node identifiers
>        always need to include case node identifiers.

I don't understand how the current text could give the impression that
there is no case node in the schema tree of shorthand cases are used.

> **** Sec. 7.10
>      - The section should also state that the data model for "anydata"
>        content may or may not be known at run time.

How about this:

NEW:

  An implementation may or may not know the data model used to model a
  specific instance of an anydata node.

> **** Sec. 7.12
>      - 'For extensions, this means that extensions are applied to the
>        grouping node, not the uses node.'
> 
>        I dont understand what this means. What is the "grouping node"?

Right; there is no "grouping node" and no "uses node".  I suggest we
simply do:

NEW:

   For extensions, this means that extensions are applied to the
   grouping itself.

> **** Sec. 7.13.2
>      - Can a leaf-list also get (new) default values through "refine"?
>        If so, how are they combined with the default values defined in
>        the grouping?

Good point.  I suggest:

NEW:

- A leaf-list node may get a set of default values, or a new set of
  default values if it already had defaults; i.e., the set of refined
  default values replaces the defaults already given.

> **** Sec. 7.15
>      - 'An action MUST NOT be defined within an rpc, another action or a
>         notification, …'
> 
>        Also it MUST NOT be defined within leaf and leaf-list, right?

Right, but this is not allowed according to the grammar.

>      - Can an action defined on a list be applied to the whole list?

No.

(It is in general IMO unfortunate that there is no way to manipulate
the whole list.)

> **** Sec. 7.21.3
>      - Maybe this section should also explain that descriptions are an
>        integral part of the data model and may specify, e.g., semantic
>        constraints that cannot be expressed formally.

Can you suggest some text?  (I am not sure I understand what you think
is needed to explain...)

> **** Sec. 9.10.2
>      - s/supported by the server/implemented by the server/

I think these words mean the same thing.  For example, we have (for
the deviate statement):

   The argument "not-supported" indicates that the target node is not
   implemented by this device.

> **** Sec. 9.10.3
>      The last paragraph should probably be replaced with an advice that
>      identityref values or nodesets should never appear as bare
>      strings in XPath expressions, and functions derived-from() or
>      derived-from-or-self() should be used instead.

I think the string value needs to be defined.

>      Example in
>      sec. 9.10.5 should be changed to use derived-from-or-self().

I think it reasonable to examplify the string value of an identity.
However, I agree that we should add advice about using
derived-from-or-self(), but I think that should be done in 6087bis.

> **** Sec. 10.3.1
>      - The document order is undefined in a data tree (also in
>        sec. 10.4.1 and 10.4.2).

Above (for 6.4) you suggested that the document order is
implementation-specific.

>      - I think deref() could return non-empty nodeset only for
>        instance-identifiers because for leafref it's not needed.

Ok...?  Do you have any edits in mind?

>        The
>        "must" constraint in sec. 10.3.1.1 is better expressed like so:
>        '/interface[name=current()]/enabled = "true"'

But then it wouldn't examplify the deref() function, would it ;-)

But maybe this is a better example:

  list interface {
      key "name type";
      leaf name { ... }
      leaf type { ... }
      leaf enabled {
          type boolean;
      }
      ...
  }

  container mgmt-interface {
      leaf name {
          type leafref {
              path "/interface/name";
          }
      }
      leaf type {
          type leafref {
              path "/interface[name=current()/../name]/type";
          }
          must 'deref(.)/../enabled = "true"' {
              error-message
                  "The management interface cannot be disabled.";
          }
      }
  }

> **** Sec. 13
>      - The ABNF can be made stricter by replacing "[default-stmt]"
>        among the substatements of "choice-stmt" with
>        "[default-case-stmt]", and then adding
> 
>        default-case-stmt = default-keyword sep node-identifier
>          stmtend

But then it would be tempting to add [default-case-stmt] to
refine-stmt and deviate-* as well.  But then we'd get both
[default-stmt] and [default-case-stmt] in these statements.  So I
prefer to keep it as is.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 25 Aug 2015 18:23:12 +0200

Martin Bjorklund <[email-masked]> writes:
...

> s/A leaf node contains/A leaf contains/ (and similar for container)?

What about "A leaf instance contains ..."

> property of the container.  In JSON, all children are always

I assume that data in whatever encoding contribute to the same
(conceptual) data tree, so it would be useful to know the properties of
the latter, such as whether some document order exists (as in XML) or
not (as in JSON). 

> Yes.  Do you have any specific edits in mind?

Section 5.3 IMO can't say that "All YANG definitions are specified
within a module that is bound to a particular XML namespace
[XML-NAMES], ..." because XML namespaces really make sense only in
XML. I'd suggest something like this:

    A YANG module defines a namespace that is identified by the module
    name. Names of all YANG definitions specified in a module belong to
    its namespace.

And then

    Statements "namespace" and "prefix" define a mapping of the module
    namespace to the XML namespace and recommended prefix taht are used
    in XML encoding.

> generic.  Do you have any proposed edits?

I am not sure what it exactly means. For example, what is an instance in
the case of a list/leaf-list: is it the complete array or an individual
list entry?

> "server YANG data model" maybe.

Perhaps we could use "data model" in the general sense as defined in
sec. 3, and then "YANG data model" as the substance of the YANG
"contract", which can be exactly constructed from the server's hello or
yang-library.

> which I have now removed.

- Sec. 4.1: "Derived types and groupings can be defined in one module or
  submodule and used in either that location or in another module or
  submodule that imports or includes it."

  Remove "or submodule" twice and "or includes".

- Sec. 5.1: "There MUST NOT be any circular chains of imports or
  includes."

  Remove "or includes" - since includes in submodules are a no-op,
  circular includes cannot happen.
  
> current usages of "data tree".  Maybe "datastore" works (this term is

What current usages of "data tree" do you mean?

Sec. 3:

OLD

   o  data tree: The instantiated tree of configuration and state data
      on a device.

NEW

   o data tree: The instantiated tree of configuration, state data,
     combined configuration and state data, RPC input or output, or
     notification.

>>        substitution of escape sequences is done before or after the

Are the following two defaults identical or not?

default "foo
         bar";

default "foo\n\t bar";

> ok to remove the expansion of tab with 8 spaces.

I don't think they are that useful. In practice, such multiline strings
only appear in descriptions and references where whitespace trimming is pretty much
irrelevant. Using it elsewhere means asking for troubles - the "+"
operator should be used for splitting long strings.

>          length, and MAY support longer identifiers.

OK.

> This is being in discussed in a separate thread.

Yup.

>   modules SHOULD not rely on any specific document order.

Good.

> nodes defined in a module have the same XML namespace, which is

The content of the namespace:: axis depends on how exactly XML
namespaces are specified. For example, it would be different for the
"foo" element in each of the following three cases:

<a xmlns="http://example.com/foo">
  <b xmlns="http://example.com/bar"/>
</a>

<foo:a xmlns:foo="http://example.com/foo">
  <b xmlns="http://example.com/bar"/>
</foo:a>

<foo:a xmlns:foo="http://example.com/foo">
       xmlns:bar="http://example.com/bar">
  <bar:b xmlns="http://example.com/bar"/>
</foo:a>

I'd suggest to have it by definition so that all namespaces are
specified outside the data tree - as if the definitions are on the
encapsulating NETCONF <data> or <config> - and with prefixes that are
defined in the modules (unless there is a conflict).

This would mean that instances of all data nodes have the same
namespace:: axis.

> XPath works, so I am not sure it is needed...

Yes, this is how XPath works on XML documents, but if YANG XPath
expressions are evaluated conceptually on the data tree (as Juergen
suggested), it is less clear - it depends on whether type infomation is
available in the data tree. I wouldn't be surprised if 90 % implementors
translated "x = y" into a numeric equality test.

> I don't understand what this refers to?

Hmm, I probably by mistake looked into original RFC 6020 text.

...

> statement in the NP-container changes the fact that its presence has

OK, you are right.

> NP containers *always* exist if its parent exists.

OK.

> I don't think this text is excludes state data.

I think the semantics of defaults in configuration and state data is
different - state data just report (hopefully true) state, so the
requirement that "the server MUST operationally behave as if the leaf
was present in the data tree with the default value as its value" seems
somewhat backwards.

> and the default statement specifies what happens if there are no

OK.

> I don't know if we need to add anything.  Suggestions?

I have to read the text and the mail thread again. I'll come back if I
find something.

OLD

In this case, the identifier of the case node is the same as the
identifier in the branch statement.

NEW

In this case, the case node still exists in the schema tree, and its
identifier is the same as the identifier in the branch statement. Schema
node identifiers (Section 6.5) MUST always explicitly include case node
identifiers - if a shorthand case statement is used, the identifier of
the branch statement will appear twice. 

>   specific instance of an anydata node.

OK.

>    For extensions, this means that extensions are applied to the

I still don't get the point. How does it apply e.g. to NACM extensions
if they are used inside a grouping? 

>   default values replaces the defaults already given.

Yes, this is reasonable.

> Right, but this is not allowed according to the grammar.

I would still add "leaf and leaf-list" to that sentence.

> Can you suggest some text?  (I am not sure I understand what you think

Unlike comments in programming language, descriptions may contribute to
the data model specification. For example, a description can state a
semantic constraint that cannot be expressed formally using a "must"
statement, or it can specify a dynamic default value for a leaf node. 

> I think these words mean the same thing.  For example, we have (for

Sec. 5.6.4 uses strictly "implement". It must be clear that identities
defined in modules that are only imported for groupings/typedefs don't apply. 

> I think the string value needs to be defined.

OK, but still some text like this could help: "In general, equality
tests involving identityref nodes should be avoided - XPath functions
derived-from() or derived-from-or-self() (Section 10.4) should be used
instead."

> Above (for 6.4) you suggested that the document order is

But that means different implementations may give different results. 

> Ok...?  Do you have any edits in mind?

Remove the third paragraph. Unlike instance-identifier, a leafref
*instance* doesn't refer to any nodes.

> But then it wouldn't examplify the deref() function, would it ;-)

Yes, because for leafrefs it's not needed. I think an example in that
section should just use an instance-identifier - see above.

> [default-stmt] and [default-case-stmt] in these statements.  So I

OK. In fact, the two statements have different semantics, so it might
have been better to use a different keyword in the first place,
e.g. "default-case". But it's too late now.

Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 26 Aug 2015 14:29:39 +0200 (CEST)

> What about "A leaf instance contains ..."

Ok.

> the latter, such as whether some document order exists (as in XML) or

Ok.  We have two alternatives:

1)  Say that the data tree is unordered (or rather the order is
    implementation specific)

2)  Enforce an order.  This would probably be the order that the nodes
    are defined in the module (but keys first) + augments after that.
    The problem is then in what order are the augmented nodes added?
    Lexicographically on the module name maybe.

Currently we have (1).

> XML.

I agree that XML namespaces make sense in XML.  But why can't we say
that all definitions are bound to this XML namespace?

> I'd suggest something like this:
> 

But this text doens't belong to section 5.3.

> the case of a list/leaf-list: is it the complete array or an individual

Maybe it helps if you point to specific text that is problematic.  I
find for example:

   A list node may exist in multiple instances in the data
   tree.  Each such instance is known as a list entry.

> "contract", which can be exactly constructed from the server's hello or

What do you call the complete set of modules in a client then?

But I am not sure the current text need this term?

Fixed.

> What current usages of "data tree" do you mean?

For example:

  The difference between an action and an rpc is that an action is tied
  to a node in the data tree

We also talk about "configuration data tree".  (In the section about
constraints, which would benefit from a term for different 'data
trees').

No.

Ok, how about:

OLD:

  Whitespace trimming and substitution of backslash-escaped characters
  in double-quoted strings is done before concatenation.

NEW:

  Whitespace trimming is done before substitution of backslash-escaped
  characters in double-quoted strings.  Concatenation is performed as
  the last step.

> irrelevant.

It is not irrelevant if you transform descriptions to some other
format, such as YIN or a man-page or whatever.

> namespaces are specified.

[re-reading the text on namespace nodes...]

Ok.

> For example, it would be different for the

Well, since the local-name of a namespace node is the prefix, I think
it would be more correct to say all nodes defined in a module have the
same set of namespace nodes, and that this set built from the the own
module + all imports.  (exact text TBD...)

> was present in the data tree with the default value as its value" seems

I think this means that a server can choose to NOT send default values
for state node.  But it also allows a server to always send all
values.

> identifiers

Ok, I'll add this.

> - if a shorthand case statement is used, the identifier of

... but this part is somehwat confusing - I understand what you mean,
but maybe we can skip it?

> if they are used inside a grouping? 

Ah, ok, I see how it is unclear.  How about:

NEW:

    For extensions, this means that extensions defined as direct
    children to a "grouping" statement are applied to the
    grouping itself.

> statement, or it can specify a dynamic default value for a leaf node. 

Yes, they describe the behavior of the node.

> defined in modules that are only imported for groupings/typedefs don't apply. 

Ok.

> derived-from() or derived-from-or-self() (Section 10.4) should be used

I still think this text doesn't belong here.  This is a best practise
issue.

> But that means different implementations may give different results. 

Yes.

> *instance* doesn't refer to any nodes.

Ok, I see, I mis-read your original comment.

We have had deref() implemented for several years, and it is mostly
used for leafrefs.  I really think we should keep it also for
leafrefs.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 26 Aug 2015 16:33:16 +0200

...

>     Lexicographically on the module name maybe.

Are there any use cases where order is important? I cannot think of
any.

> Currently we have (1).

If we stick to (1) then I think the special ordering rules (keys go
first, RPC input/output has fixed order) should apply only to XML
encoding because presumably it is important there for streaming data,
and in JSON they cannot be enforced.

> that all definitions are bound to this XML namespace?

[XML-NAMES] defines specific ways of how XML namespaces are declared,
and we use these only in XML encoding but not in general.

Or is the problem that you want to have the URI as the "official"
namespace identifier? This is possible although I'd rather avoid using
URIs and prefixes outside XML.

> But this text doens't belong to section 5.3.

It could belong there if the section is renamed to "Namespaces". IMO XML
namespaces should only be dealt with in an "XML Encoding" section.

>    tree.  Each such instance is known as a list entry.

On the other hand, section 7.7.1 shows an "XML instance example"
consisting of two <allow-user> elements.

I'd suggest to use the term "instance" (data node instance) as a
data tree counterpart of a data node in the schema tree. That is, an
instance of a (leaf-)list would be an array containing (leaf-) list
entries.

> What do you call the complete set of modules in a client then?

As it is now, the contract is defined by the server in terms of
advertised modules, features and deviations. This sets the rules. The
client, on the other hand, doesn't do a similar advertisement, so it has
to abide by the rules set by the server, and it is IMO not that
important whether the client fully understands the contract.

> But I am not sure the current text need this term?

Apparently there are misunderstandings regarding conformance so I guess
some clarification would be useful.

...

>   to a node in the data tree

Hmm, could actions be attached to nodes in state data?

> constraints, which would benefit from a term for different 'data

Configuration data is OK, it is just a special data tree, as is e.g. RPC
input data tree. It is important e.g. for XPath evaluation, because as
it is now, one can think that canonical values are not used in RPCs or
notifications.

>   characters in double-quoted strings.  Concatenation is performed as

Yes, this solves this issue.

> format, such as YIN or a man-page or whatever.

In simple cases a straightforward space normalization will usually do,
and in more complicated cases, e.g. a description with bullet list, the
raw description text isn't of much use anyway.

Anyhow, I think such use cases don't warrant a section in the language
spec full of relatively tricky rules.

> module + all imports.  (exact text TBD...)

Yes, that's what I meant.

OK.

> but maybe we can skip it?

I have seen several YANG users (including myself) who were wondering why
a certain schema node identifier doesn't work. It is somewhat
counter-intuitive because the shorthand case nodes don't appear in a
module hierarchy so it is easy to forget about them.

OK.

...

OK.

> used for leafrefs.  I really think we should keep it also for

deref() for instance-identifiers doesn't need a schema (all "normal"
XPath functions don't) whereas for leafrefs the implementation has to
find the path of the leafref in the corresponding YANG module. This
means that such a function cannot be implemented as an extension to
standard XPath/XSLT processors such as "xsltproc".

For instance-identifiers this function is indispensable while for
leafrefs it is just an abbreviation, and an alternative expression
without deref() always exists.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 26 Aug 2015 19:28:12 +0200 (CEST)

> Are there any use cases where order is important? I cannot think of

Neither can I.  The implication is that you can't rely on any specific
order when you write your must/when expression.

> and in JSON they cannot be enforced.

Agreed.

> and we use these only in XML encoding but not in general.

Agreed.

No.

> namespaces should only be dealt with in an "XML Encoding" section.

Ok.  Let me have a look at this.

[...]

> standard XPath/XSLT processors such as "xsltproc".

derived-from() also needs YANG knowledge.

> without deref() always exists.

Agreed.  But IMO deref() is a very useful syntactic sugar, as it's
meaning is clearer than the unwieldy expanded expression.  And it is
fairly trivial to expand the deref() expression into the plain XPath
alternative.

/martin