Hi Authors,
some quick comments on your draft.
meta-comments:
1) shouldn’t this be in the NETMOD WG and be named
“draft-netmod-yang-json-rpc-00” once adopted, and “draft-issn-yang-json-rpc-00”
(or whatever) for now? Posting these comments to NETMOD at any rate :)
2) why does each page have a number 0 at the top?
3) might be worth adding a security section and some IANA considerations (even
if there are no actions required from IANA)
Section 1:
4) s/ZMQ/0MQ (ref can still be [ZEROMQ])
5) s/RabbitMQ/AMQP (ref can still be [RABBITMQ])
6) you say JSON RPC 2.0 has a number of well known shortcomings. Aren’t there
really just the two - no means of describing/documenting an API method and no
means to interpret data and to generate structures to receive the data? or is
that three? ;) I almost wonder if bullets are the answer here.
7) s/lead/led in “this has lead them”
8) I think it should be “and/or use” not “and/or the use of”
9) isn’t “not portable across languages” basically the same as “break the core
assumption of JSON being a language agnostic interchange format”?
10) is it really a core assumption that JSON is language agnostic? Given the
JS in its name i mean…
11) you reference the "JSON Encoding of Data Modeled with YANG” draft. That’s
RFC7951 :)
Section 2:
12) maybe it’s time to move to YANG 1.1 (RFC 7950)
13) do you need to use square brackets each time you refer to a doc? I’d just
do it the first time and use the name thereafter.
Section 3:
14) s/yang/YANG
15) where you have links to sections of RFCs I’d keep the link to the section
separate from any link to the whole RFC.
16) where referring to an RFC outside of square brackets I think the correct
style is to have a space between “RFC” and the RFC number.
17) might be worth explaining why use of must, when, leafref and identityref
can harm interoperability.
18) also might be worth enumerating the characters to be discouraged.
19) it’s probably worth breaking the input and output for the RPC out as
separate sub-sections rather than having the input in the main part of section
3 and the output as one sub-section of section 3.4
20) it’s probably worth explaining that figure 3 is the positional form and
figure 4 is named. You do that later on so not to do it for your first
example is somewhat confusing.
21) it’s probably also worth explaining that the mappings for the positional
form are a difference wrt RFC7951 (since YANG-modelled data is always carried
in named form when mapped into XML or JSON).
Section 3.2:
22) link missing under 7.13.3
Section 3.3:
23) from my understanding of YANG extensions you need to write a YANG model for
idl and publish that.
24) seems you’ve actually defined two extensions here - idl:value-type and
idl:implemented-by
Section 3.4:
25) the output rules seem to conflict with the input rules re lists (one reason
why I think separating those out into separate subsections makes sense)
Section 3.4.1:
26) I’m not sure having {“key” : “value”} is a good example for anyxml in that
it tends to imply you have a model somewhere and know the keys? The same
occurs in Fig 23 (sec 3.4.3)
Section 3.4.3:
27) in fig 26 I think the result should be “object”, not “test-object”?
Section 3.6:
28) I think this is section 6.11 not 6.1 of RFC7951?
29) worth explaining why the representation doesn’t match JSON semantics
30) is this YANG path stuff equivalent to the actions in YANG 1.1?
Section 3.6.1:
31) please define QName
Section 3.6.3:
32) please delete the word “section” after “Section 3.6.1"
Section 4:
33) the Zero MQ and JSON RPC refs seem to be back to front
34) you’ve got PJZMQ pointing at www.jabsorb.org <http://www.jabsorb.org/>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
