Re: [netmod] stable reference for tree diagram notation

Andy Bierman <> Fri, 03 March 2017 17:36 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 4C6B4129957 for <>; Fri, 3 Mar 2017 09:36:44 -0800 (PST)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.599
X-Spam-Status: No, score=-2.599 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id 5UaKmC3GAwCs for <>; Fri, 3 Mar 2017 09:36:42 -0800 (PST)
Received: from ( [IPv6:2a00:1450:400c:c09::22c]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id D6F6712994E for <>; Fri, 3 Mar 2017 09:36:41 -0800 (PST)
Received: by with SMTP id n11so20788814wma.1 for <>; Fri, 03 Mar 2017 09:36:41 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20150623; h=mime-version:in-reply-to:references:from:date:message-id:subject:to; bh=7GNit4PEdZqBQg9iHNAwksGoZ9iV7JdhLV7lbfjFTFQ=; b=JZP8njeAFXYzE+TgM66b8mLi/t51MN1srDgluSzWlBBnogZ+pWdviJ7Z2bhIzXMxnU I/MI9IH+WbJby9mSV4+ELrCzr+8CE7z/xEOEka3aTCOy+5ocBAG/BTHHN2J6EVpx21C3 WdSELdSkrimFA7TuuVq26qk1VZ6gwTwQbdgavbfRaxb6aTlO4Nz78nhIZbErvSOvngRK x3/Y9my68JKH/BEUQOAoSUZ4r4/zQNK+LmIjlWcCCYp1g3ftMteCIcV6AJyWCIryZ6wA CVkvEto0GweJx+h4b4odZXaUtrhVhyVZBLUZ5JU9mibbCKOikWZtOzN9DtVmXSzIGbjf NjUA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to; bh=7GNit4PEdZqBQg9iHNAwksGoZ9iV7JdhLV7lbfjFTFQ=; b=dwwYWIhcJqcF98Gn3QQ1d04D5xRopqnThmRezW6DdaiPSas4Vzv3Ee7f56akcv3jH1 buP5bJvHdPVh1bigXo8hzwENk6vCcPb4G4IsOL1pyt+cN35xRMuGA52UUPi5NzHAecjx ZKp3Ct/SPx0M9DMVL3VXPV6qn4MUr7a+QOgEuc/nM2IbWWa5fIMO+JH5+oNV4jrTK2Vl XYuvnvQHAHroziLEQ3X8ZfahM55fWdYapm62gA/0z7+1PW9StlqmGEpz5t8A0/G0Wxb2 XkPyd7DGd8bssY3gxoW6b/C5QLKuAQksv13MeuCoVMi1dwIAD5L/uuv5C0MypkOwHQ6i IBLQ==
X-Gm-Message-State: AMke39nZEvg0+vImRNEnF1P5Wxm1+1xTvfhJyN5V6JBkqE3l0LNorztxJCGdBLtKTWDvGH4tASgBSdoNNH4JEA==
X-Received: by with SMTP id u204mr1855606wmu.136.1488562600264; Fri, 03 Mar 2017 09:36:40 -0800 (PST)
MIME-Version: 1.0
Received: by with HTTP; Fri, 3 Mar 2017 09:36:39 -0800 (PST)
In-Reply-To: <20170303170233.GB3345@elstar.local>
References: <> <20170303170233.GB3345@elstar.local>
From: Andy Bierman <>
Date: Fri, 3 Mar 2017 09:36:39 -0800
Message-ID: <>
To: Juergen Schoenwaelder <>, Kent Watsen <>, "" <>
Content-Type: multipart/alternative; boundary=001a11497ace03e7b40549d6fdb2
Archived-At: <>
Subject: Re: [netmod] stable reference for tree diagram notation
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: NETMOD WG list <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Fri, 03 Mar 2017 17:36:44 -0000


Originally 6087bis had a guideline for each draft to have an informative
reference to
6087bis tree diagram section.  This got removed along the way (I can't find
it in sec 4.9).

It is important that documents use the exact same symbols as every other
tree diagram, so the reader can learn to interpret a tree diagram without
constantly checking the mapping guide.

It is less important that all documents have to same set of identifiers in
the diagram.
E.g., if the module only exports groupings, then the groupings should be in
tree diagram.

IMO the tree diagrams are too verbose now, mostly due to leafref and


Here is the output of pyang v1.7.1 --tree-help

Each node is printed as:

<status> <flags> <name> <opts> <type> <if-features>

  <status> is one of:
    +  for current
    x  for deprecated
    o  for obsolete

  <flags> is one of:
    rw  for configuration data
    ro  for non-configuration data
    -x  for rpcs and actions
    -n  for notifications

  <name> is the name of the node
    (<name>) means that the node is a choice node
   :(<name>) means that the node is a case node

   If the node is augmented into the tree from another module, its
   name is printed as <prefix>:<name>.

  <opts> is one of:
    ?  for an optional leaf, choice, anydata or anyxml
    !  for a presence container
    *  for a leaf-list or list
    [<keys>] for a list's keys

  <type> is the name of the type for leafs and leaf-lists

    If the type is a leafref, the type is printed as "-> TARGET", where
    TARGET is either the leafref path, with prefixed removed if possible.

  <if-features> is the list of features this node depends on, printed
    within curly brackets and a question mark "{...}?"

On Fri, Mar 3, 2017 at 9:02 AM, Juergen Schoenwaelder <> wrote:

> On Fri, Mar 03, 2017 at 04:41:44PM +0000, Kent Watsen wrote:
> >
> > All,
> >
> > Lou and I were discussing how it seems unnecessary that every draft
> > has the same boilerplate text regarding how to interpret tree diagram
> > notations.  It would be nice if drafts could instead just reference
> > another draft that contains this information.  Does this make sense?
> >
> > Assuming we're interested in having such a reference, we could define
> > a mini-RFC or, perhaps, leverage Section 3 of 6087bis (YANG Tree
> > Diagrams).  Either way, we'd want/need to ensure the information
> > is updated in a timely manner.
> >
> > Two reasons for why we may not want to pursue this are:
> >   1) we can’t update the reference fast enough
> >   2) drafts might add some proprietary annotations
> >
> > Is this worth pursuing at all?
> This has been discussed before. The tree format that tools generate
> has evolved a bit over time and the current setup allows to have some
> evolution. The question is whether we have reached a state where the
> evolution has come to standstill and we can nail a common tree format
> down. If so, someone should write an I-D and then the format should in
> my opinion become a separate RFC that can be referenced. (I would not
> roll this into RFC 6087 so that the tree format can be revised without
> opening all of RFC 6087.) Others have argued in the past that the
> replication is not such a big deal and the replication has the
> advantage that people who do not read YANG everyday have an
> explanation right in place without having to lookup another RFC.
> For me personally, this is a low low priority item but if someone has
> spare cycles to spend, this is a good target. Such an RFC will get
> tons of references and you become famous. Oh, now I get interested...
> /js
> --
> Juergen Schoenwaelder           Jacobs University Bremen gGmbH
> Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   +49 421 200 3103         <>
> _______________________________________________
> netmod mailing list