Hi Juergen, thank you for the review.
Juergen Schoenwaelder <[email protected]> writes: > On Mon, Jun 15, 2015 at 10:49:28PM +0000, Kent Watsen wrote: >> >> This is a notice to start a NETMOD WG last call for the document "JSON >> Encoding of Data Modeled with YANG": >> >> https://tools.ietf.org/html/draft-ietf-netmod-yang-json-04 >> >> Please indicate your support by Monday June 29, 2015 at 9PM EST. > > Hi, > > I have reviewed draft-ietf-netmod-yang-json-04. > > - I am not sure I agree with the wording in section 3. Why is section > 8.3.3 only applicable to XML encoded data? Validation applies to > datastores. While constraints are defined using XML-based notations You are right that this section shouldn't talk about XML-encoded data, i.e. serialized form. On the other hand, XPath 1.0 spec says: "XPath operates on the abstract, logical structure of an XML document, …". So I think a datastore needs to be represented, at least conceptually, as XML infoset. > such as XPATH, how the validation is carried out is not defined in > the YANG specifications. I guess I actually disagree with the I don't think this is true. YANG spec doesn't say how "must" and "when" statements are evaluated, and relies on XPath. > wording in section 3 of the JSON encoding I-D. What specifically? Do you have any suggestions for changes? > > - It is unclear whether the 'if and only if' on page 4 means that an > implementation that generates namespace prefixes that are not > strictly needed is violating this I-D. I see the need for a MUST to Yes, that's the intention. Why is it unclear? > include the module name if the parent node belongs to a different > module. I am not sure why it is necessary to mandate minimal > encodings (if that is the idea here). Whatever the answer is, it > would be good to use RFC 2119 language. Revision -02 used 2119 terms but there were objections against it: https://mailarchive.ietf.org/arch/msg/netmod/xXS0uSKKu83qBQVCJ_CYmdsavUc In fact, YANG spec also states syntax rules without using 2119 keywords, for example "Each identifier starts with an uppercase or lowercase ASCII letter or an underscore character, …", it doesn't say that it MUST NOT start with anything else. > > - The reason for the requirement that list keys are encoded first in > RFC 6020 is to make it easier to process data in a stream-oriented > fashion. If keys can appear anywhere, they might appear at the very > end and thus buffering is required in order to process data > properly. Is this concern not relevant for the JSON encoding? This cannot be required as long as our aim is interoperability of implementations based on off-the-shelf JSON parsers, hence I_JSON. RFC 7493 states it clearly: "The order of object members in an I-JSON message does not change the meaning of an I-JSON message." > Perhaps this is not relevant, but then we might also state this > explicitly: > > As a consequence, implementations must be cable to buffer JSON > encoded instances in order to locate keys that may appear at the > end of a JSON encoded instance. I think it is clear that an implementation needs to be able to handle keys appearing anywhere in a list-entry-object. How it is handled is IMO implementation-specific - I guess it also depends on where and how the stream-oriented data processing is used. > > - I think that section 5.5 should say: > > If the data model for the data in an anydata instance is known, > then the data must be encoded following the rules defined in > this I-D. Something like this should then probably appear in 6020bis, yet it doesn't. I am unclear how one can determine that the data model is known because anydata nodes don't provide this information. Perhaps it can be specified in the description but then is it known including the revisions of YANG modules involved? Moreover, the data model needn't be known at all. Therefore, I tend to think about anydata as kind of ad hoc data that's just piggybacked inside YANG-modelled data. There may be rules that this data have to conform to (expressed in YANG or not) but they are out of scope from the perspective of the data model that's specified in hello or yang-library. That's why sec. 5.5 only states syntactic constraints to make sure that the data "can be modelled with YANG". BTW, I have a growing concern that anydata creates more problems than it solves. > > In other words, it is not arbitrary JSON with a few constraints but > something that matches the JSON encoding rules once the data model > is known. > > - Section 6, I suggest s/mapped/encoded/. Agreed. > > - I do not understand 'An "enumeration" value is mapped in the same > way as a string except that permitted values are defined by enum > statements in YANG.' Perhaps this is simpler: > > An "enumeration" value is encoded as a JSON string. The allowed > string values are the enumeration names assigned by the enum > statement in YANG. > > The representation is identifical to the XML encoding, see > sec. 9.6 in [RFC6020bis]. > > I specifically tried to avoid 'value' in order to avoid confusion with > the value YANG statement. OK, good point. > > - Perhaps remove the reference to XML in section 6.5 from the > definition of the encoding rules so that the JSON encoding rules are > not tied into the XML encoding rules. It is OK to mention that it is > the same. > > A "bits" value is encoded as a JSON string. Multiple bit names > assigned by the bit statement in YANG are encoded as a > space-separated string of bit names representing the individual > bits that are set. > > The representation is identifical to the XML encoding, see > sec. 9.7 in [RFC6020bis]. > > - Same as before for section 6.6: > > A "binary" value is encoded by first encoding the binary value in > base64 and encoding the resulting base64-encoded value as a JSON > string. > > The representation is identifical to the XML encoding, see > sec. 9.8 in [RFC6020bis]. OK. > > - I am not sure I understand the argument why [null] is better than > null for the empty type. Perhaps it is but the text does not really > tell me. "foo": null may sometimes appear as if the "foo" instance is not present at all - in some languages this is probably more serious than in others. This is how it works in Python: >>> import json >>> obj = json.loads('{"foo": null, "bar": [null]}') >>> "YES" if obj["foo"] else "NO" 'NO' >>> "YES" if obj["bar"] else "NO" 'YES' So the special value "[null]" seems safer and it cannot appear in any other context. > > - I suggest to remove the reference to 9.13.3 in the definition. In … definition of instance-identifier encoding. > fact, the representation is pretty different since XML uses > namespace prefixes while JSON uses module names. (I must admit that > I find the JSON representation more readable since it does not > require XML namespace context.) Yes, the document could simply state an ABNF production for JSON-endoded instance-identifier without further ado. > > - Section 7: So what happens in the rare case of a binary value > appearing in a RESTCONF URI? Is the resulting BASE64 value than > simply subject to URI escaping rules? Right, and I agree the document should say this. > > I assume this 'rare event' would happen if a list is indexed by a > leaf of type binary, no? Are there any other cases? I am not aware of any other case. > > /js > > PS: Should RFC 6020bis change the section titles "XML Mapping Rules" to > "XML Encoding Rules"? I think we really talk about 'encoding', not > about 'mapping' and if we agree on this, we should try to be > consistent with the terms we use. I agree, it would be better. Lada > > -- > Juergen Schoenwaelder Jacobs University Bremen gGmbH > Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany > Fax: +49 421 200 3103 <http://www.jacobs-university.de/> > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod -- Ladislav Lhotka, CZ.NIC Labs PGP Key ID: E74E8C0C _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
