Subject: [yang-doctors] Yangdoctors last call review of draft-ietf-netconf-http-client-server-06

From: Ladislav Lhotka via Datatracker <[email-masked]>
Date: Mon, 12 Apr 2021 01:19:23 -0700

Reviewer: Ladislav Lhotka
Review result: Ready with Nits

The document defines two YANG modules - ietf-http-client and ietf-http-server -
that belong to a relatively complex set of modules. The modules are well
designed and nicely documented, both in the descriptions and document text.

**** Comments

- Sections 2.1.3 and 3.1.3: the sentence 'The "..." module does not contain any
protocol-accessible nodes.' is misleading in that the modules do define data
nodes that are intended to be protocol accessible after the corresponding
grouping is used. I know this is a part of the NETCONF/YANG lingo, but another
formulation that clearly says what's going on might be preferable.

- Sections 2.2 and 3.2: the XML snippets use document elements "http-client"
and "http-server", but these containers are not defined in the corresponding
modules. This is confusing, my suggestion is to rewrite the examples in the
JSON representation where no such top-level node is necessary.

- Placeholders BBBB, CCCC and EEEE are defined in Editorial Note but never used

**** Nits

- RFC 7950 is cited repeatedly (4 times) in a general context, e.g. whenever
YANG 1.1 is mentioned. It should suffice to use the citation at the first
appearance.

---

From: Kent Watsen <[email-masked]>
Date: Mon, 19 Apr 2021 22:23:07 +0000

Hi Lada,

Thank you for your review!

Below are responses to your comments.

K.

> On Apr 12, 2021, at 4:19 AM, Ladislav Lhotka via Datatracker <[email-masked]> wrote:
> 

 :)

> formulation that clearly says what's going on might be preferable.

I fixed this when I addressed the same comment made in the “tcp-client-server” draft.

> JSON representation where no such top-level node is necessary.

Same solution as for the “tcp-client-server” draft, which is to simply remove the first and last lines, for the non-existent “container” statement.

Update: I was going to proactively-apply the same solution to the “ssh” and “tls” drafts, but I couldn’t because the top-level element defines additional prefixes.  This is where your “JSON” idea could help, though, for some reason, having a mix of XML/JSON in the suite of drafts is off-putting to me.  We could convert all the examples to JSON, but that’s a fair amount of work too…  

How about adding an XML-comment indicating that the top-level element doesn’t really exist?

> - Placeholders BBBB, CCCC and EEEE are defined in Editorial Note but never used

Fixed.

> YANG 1.1 is mentioned. It should suffice to use the citation at the first

Fixed.  Also in the “ssh” and “tls” drafts.

K.

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 20 Apr 2021 14:58:50 +0200

> I fixed this when I addressed the same comment made in the “tcp-client-server” draft.

OK

> Update: I was going to proactively-apply the same solution to the “ssh” and “tls” drafts, but I couldn’t because the top-level element defines additional prefixes.  This is where your “JSON” idea c…

If you already have that "foobar-usage.yang" module, you could possibly translate these snippets automatically using the "jsonxsl" plugin of pyang.

I also think that JSON examples are easier to parse for a human reader.

> How about adding an XML-comment indicating that the top-level element doesn’t really exist?

Yes, as I wrote in the other review, some explanation might suffice.

Lada

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67