Re: [netmod] Use XML namespaces in YANG document examples

[Jürgen Schönwälder <[e-mail]>]

While adding such a disclaimer may help you to move your document
forward (which I assume is your main priority), this looks to me like
a disclaimer added to an arbitrary YANG document for the sake of
making a reviewer happy while (i) we never did this before and (ii) we
likely have no plan to do this in the future.

If this issue is really important, then someone should write an I-D or
an errata for RFC 7950 that clarifies this for _all_ YANG modules.

Given that YANG is 11+ years old, I am not convinced this clarification
is needed, but that certainly may be a biased opinion.

Hence, my preference is to add no disclaimer and to move forward.

/js

On Mon, Feb 07, 2022 at 08:40:49PM +0100, [e-mail] wrote:
> Hi,
> 
> Reading back through the discussion, I think I can summarise the outcome to the following 2 points:
> 
> 1,The examples in the DHCPv6 YANG draft can keep the current use of XML prefixes (e.g. ianaift:ethernetCsmacd)
> 
> 2, In the XML examples appendix, I will change the first paragraph to read:
> 
> XML Examples for DHCPv6 Element Configuration
> 
> This section contains XML examples of data trees for the different
> DHCPv6 elements. In order for the XML data to be used correctly,
> the XML prefix must be the same as the namespace prefix. i.e, for
> The client configuration example, the characters before the colon
> (or 'ianaift:’ in the "interface/type” element content) must match the
> xmlns defined for "urn:ietf:params:xml:ns:yang:iana-if-type”. In this
> case xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type”.
> Therefore, XML software must be chosen that makes the namespace prefix
> information available.
> 
> Does this sound like the right way to proceed?
> 
> Thanks,
> Ian
> 
> 
> 
> 
> > On 4. Feb 2022, at 16:15, Martin Björklund <[e-mail]> wrote:
> > 
> > Jernej Tuljak <[e-mail]> wrote:
> >> 
> >> 
> >> On 04/02/2022 08:18, Martin Björklund wrote:
> >>> Tim Bray <[e-mail]> wrote:
> >>>> On Thu, Feb 3, 2022 at 10:21 AM Martin Björklund <[e-mail]>
> >>>> wrote:
> >>>> 
> >>>>> If an XML document has <foo xmlns:bar="...">, won't the XML processor
> >>>>> pass the attribute "xmlns:bar" and its value to the application?  This
> >>>>> should be enough even if the XML processor doesn't provide a mapping
> >>>>> table between prefix and namespace (it requires more work in the
> >>>>> application of course).
> >>>>> 
> >>>> Nope, there's no requirement that they do and some don't.
> >>> Does this mean that an XML processor might not pass attributes in
> >>> general to the application?  If so, we might have other similar
> >>> problems.  Or does it mean that an XML processor might just not pass
> >>> these "special" attributes?  If so, where is that specified?  (I tried
> >>> to find this info in the spec, but didn't find it).
> >> 
> >> Names that start with "xml" (case insensitive) are reserved by XML 1.0
> >> specification, "xmlns" in an attribute name included (2.3 Common
> >> Syntactic Constructs). They are special. There is also a guideline on
> >> colon usage within names.
> > 
> > Yes, I know.  But I can't see that the spec says that attributes w/
> > reserved names should be treated differently wrt. the application than
> > other attributes.
> > 
> >> All processors I'm aware of differentiate between attributes and
> >> namespace attributes in their APIs. What Tim is probably saying is
> >> that some XML processors either don't implement Namespaces in XML 1.0
> >> or need to be explicitly configured to become "namespace aware". If
> >> not configured as namespace aware, they might simply ignore namespace
> >> attributes therefore not passing them. If they are configured as
> >> namespace aware, they might remove prefix information and pass only
> >> "namespace : local-name" pairs where required (and that excludes text
> >> node content).
> > 
> > I guess I wonder if this is b/c the specification says so, or that
> > some implementations choose to do so.
> > 
> > 
> > /martin
> > 
> > 
> > 
> >> 
> >> Jernej
> >> 
> >>> 
> >>> 
> >>> /martin
> >>> 
> >>> 
> >>>>> I think that if special text is needed for identityref values in XML,
> >>>>> that text should go in to the YANG specification (RFC 7950).  All
> >>>>> these other drafts just follow the rules defined in RFC 7950.
> >>>>> 
> >>>> Agreed.
> >>>> 
> >>>> 
> >>>> 
> >>>>> 
> >>>>> /martin
> >>>>> 
> >>>>> 
> >>>>> 
> >>>>>> 
> >>>>>> 
> >>>>>> 
> >>>>>> 
> >>>>>>> 
> >>>>>>> Andy
> >>>>>>> 
> >>>>>>> 
> >>>>>>>> I've excerpted an email exchange with Ian Farrer that I think makes
> >>>>> the
> >>>>>>>> potential problem concrete:
> >>>>>>>> 
> >>>>>>>> Hi Ian, I don't think we've met.  I'm the grumpy person on the "XML
> >>>>>>>> Directorate" who's been whining about the namespace prefixes in YANG
> >>>>>>>> internet-drafts. One quick issue: I'm a little surprised, is anyone
> >>>>> still
> >>>>>>>> using XML in this kind of thing any more in 2021?
> >>>>>>>> 
> >>>>>>>> Anyhow, below I've excerpted the issue that's still troubling me.
> >>>>> Here's
> >>>>>>>> the XML:
> >>>>>>>> 
> >>>>>>>>  <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
> >>>>>>>>      xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
> >>>>>>>>      <interface>
> >>>>>>>>        <name>eth0</name>
> >>>>>>>>        <type>ianaift:ethernetCsmacd</type>
> >>>>>>>>        <description>DHCPv6 Relay Interface</description>
> >>>>>>>>        <enabled>true</enabled>
> >>>>>>>>      </interface>
> >>>>>>>>    </interfaces>
> >>>>>>>> 
> >>>>>>>> So my question is, I see the XML namespace prefix and the prefix for
> >>>>> the
> >>>>>>>> <type> element content are identical. Is this a coincidence?  For
> >>>>> example,
> >>>>>>>> would the following work, changing the namespace prefix to "foo"?
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>>  <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
> >>>>>>>>      xmlns:foo="urn:ietf:params:xml:ns:yang:iana-if-type">
> >>>>>>>>      <interface>
> >>>>>>>>        <name>eth0</name>
> >>>>>>>>        <type>ianaift:ethernetCsmacd</type>
> >>>>>>>>        <description>DHCPv6 Relay Interface</description>
> >>>>>>>>        <enabled>true</enabled>
> >>>>>>>>      </interface>
> >>>>>>>>    </interfaces>
> >>>>>>>> 
> >>>>>>>> [if - This example would not work and fails validation with yanglint:
> >>>>>>>> 
> >>>>>>>> $ yanglint --strict --verbose -t config -p $IETFYANG
> >>>>>>>> $IETFYANG/iana-if-type.yang $IETFYANG/ietf-interfaces.yang test1.xml
> >>>>>>>> err : Invalid value "ianaift:ethernetCsmacd" in "type" element.
> >>>>>>>> (/ietf-interfaces:interfaces/interface[name='eth0']/type)
> >>>>>>>> ]
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> Follow-up, would the following work, foo for both namespace and
> >>>>> content
> >>>>>>>> prefix?
> >>>>>>>> 
> >>>>>>>> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
> >>>>>>>>      xmlns:foo="urn:ietf:params:xml:ns:yang:iana-if-type">
> >>>>>>>>      <interface>
> >>>>>>>>        <name>eth0</name>
> >>>>>>>>        <type>foo:ethernetCsmacd</type>
> >>>>>>>>        <description>DHCPv6 Relay Interface</description>
> >>>>>>>>        <enabled>true</enabled>
> >>>>>>>>      </interface>
> >>>>>>>>    </interfaces>
> >>>>>>>> 
> >>>>>>>> Thanks in advance!
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> [if - This does validate with yanglint, however the convention in the
> >>>>>>>> IETF examples I’ve seen seems to be to use the prefix that is defined
> >>>>> in
> >>>>>>>> the original YANG module for imports for consistency, e.g. (from
> >>>>>>>> iana-if-type.yang):
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> On Thu, Feb 3, 2022 at 8:03 AM Andy Bierman <[e-mail]>
> >>>>> wrote:
> >>>>>>>>> Hi,
> >>>>>>>>> 
> >>>>>>>>> I think the text from sec 4 refers to the usage within an
> >>>>> application.
> >>>>>>>>> The XML instance document is the on-the-wire representation and
> >>>>>>>>> the I-D example looks correct.
> >>>>>>>>> 
> >>>>>>>>> https://www.w3.org/TR/xml-names/#ns-qualnames
> >>>>>>>>> 
> >>>>>>>>> 
> >>>>>>>>> Andy
> >>>>>>>>> 
> >>>>>>>>> 
> >>>>>>>>> On Thu, Feb 3, 2022 at 3:53 AM tom petch <[e-mail]>
> >>>>> wrote:
> >>>>>>>>>> From: netmod <[e-mail]> on behalf of
> >>>>> [e-mail] <
> >>>>>>>>>> [e-mail]>
> >>>>>>>>>> Sent: 03 February 2022 09:37
> >>>>>>>>>> 
> >>>>>>>>>> Hi,
> >>>>>>>>>> 
> >>>>>>>>>> A draft I have been working on (
> >>>>>>>>>> https://datatracker.ietf.org/doc/draft-ietf-dhc-dhcpv6-yang/)
> >>>>> contains
> >>>>>>>>>> a number of XML configuration examples. During the XML expert
> >>>>> review, a
> >>>>>>>>>> question has been raised about the use of XML namespaces in these
> >>>>> examples.
> >>>>>>>>>> I’m raising it here as I don’t have the XML knowledge to answer.
> >>>>>>>>>> 
> >>>>>>>>>> <tp>
> >>>>>>>>>> 
> >>>>>>>>>> Ian
> >>>>>>>>>> 
> >>>>>>>>>> This looks like the issue I raised on this list 14jan2022 with a
> >>>>>>>>>> subject line of
> >>>>>>>>>> XML and prefix
> >>>>>>>>>> although I have not checked that the usage is exactly the same; the
> >>>>>>>>>> 'XML Expert' comment would appear to be.
> >>>>>>>>>> 
> >>>>>>>>>> Tom Petch
> >>>>>>>>>> 
> >>>>>>>>>> In my example:
> >>>>>>>>>> 
> >>>>>>>>>> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
> >>>>>>>>>> 
> >>>>>>>>>>      xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
> >>>>>>>>>>      <interface>
> >>>>>>>>>>        <name>eth0</name>
> >>>>>>>>>>        <type>ianaift:ethernetCsmacd</type>
> >>>>>>>>>>        <description>DHCPv6 Relay Interface</description>
> >>>>>>>>>>        <enabled>true</enabled>
> >>>>>>>>>>      </interface>
> >>>>>>>>>>    </interfaces>
> >>>>>>>>>> 
> >>>>>>>>>> The question is related to the use of the ‘ianaift:’ prefix. This is
> >>>>>>>>>> quite commonly use in XML examples in YANG documents (e.g. RFC8344)
> >>>>> so I
> >>>>>>>>>> think the question is generally applicable.
> >>>>>>>>>> 
> >>>>>>>>>> The specific comments from the expert review are:
> >>>>>>>>>> 
> >>>>>>>>>> -
> >>>>>>>>>> For the correct processing of these documents requires that whatever
> >>>>>>>>>> XML software is being used makes available to application code the
> >>>>>>>>>> namespace prefixes.
> >>>>>>>>>> 
> >>>>>>>>>> Whilst the recommended tools (e.g. yanglint) provides this
> >>>>> function, it
> >>>>>>>>>> is not an XML best practice. Quoting from the Namespaces in XML,
> >>>>> section 4:
> >>>>>>>>>> "Note that the prefix functions only as a placeholder for a
> >>>>> namespace name.
> >>>>>>>>>> Applications SHOULD use the namespace name, not the prefix, in
> >>>>> constructing
> >>>>>>>>>> names whose scope extends beyond the containing document.”
> >>>>>>>>>> 
> >>>>>>>>>> I think that violating a SHOULD assertion in a W3C standard is a
> >>>>>>>>>> problem.
> >>>>>>>>>> 
> >>>>>>>>>> There is no requirement for XML processors to provide this prefix
> >>>>>>>>>> information, and software that (quite legally) doesn't, will not
> >>>>> work
> >>>>>>>>>> correctly with YANG documents constructed as specified in this I-D.
> >>>>>>>>>> 
> >>>>>>>>>> 1, YANG specifications should note this fact and specify that
> >>>>> software
> >>>>>>>>>> which is used to process YANG documents MUST provide an interface
> >>>>> such that
> >>>>>>>>>> applications can retrieve the prefix-namespace mappings.
> >>>>>>>>>> 2, For constructs such as <type>ianaift:ethernetCsmacd</type> the
> >>>>>>>>>> Internet-Draft should specify that the prefix ("ianaift" in this
> >>>>> case) MUST
> >>>>>>>>>> be identical to the xmlns namespace prefix representing the
> >>>>> namespace name
> >>>>>>>>>> urn:ietf:params:xml:ns:yang:iana-if-type
> >>>>>>>>>> 3, Alternately, the draft could specify that for the namespace
> >>>>>>>>>> urn:ietf:params:xml:ns:yang:iana-if-type, the XML namespace prefix
> >>>>> ianaift
> >>>>>>>>>> MUST be used. Another XML bad practice because software that
> >>>>> generates XML
> >>>>>>>>>> programmatically should feel free to generate synthetic prefixes
> >>>>> without
> >>>>>>>>>> breaking the content, but at least this would solve the problem.
> >>>>>>>>>> -
> >>>>>>>>>> 
> >>>>>>>>>> BCP216 (RFC8407 - Guidelines for Authors and Reviewers of Documents
> >>>>>>>>>> Containing YANG modules) doesn’t make any mention of how XML
> >>>>> namespaces
> >>>>>>>>>> should be used, only that example XML/ JSON should be included and
> >>>>> that
> >>>>>>>>>> these examples need to be validated (pyang and yanglint are
> >>>>> mentioned for
> >>>>>>>>>> this).
> >>>>>>>>>> 
> >>>>>>>>>> Does this guidance need to be updated to reflect expert review
> >>>>> comments
> >>>>>>>>>> above?
> >>>>>>>>>> 
> >>>>>>>>>> Thanks,
> >>>>>>>>>> Ian
> >>>>>>>>>> 
> >>>>>>>>>> 
> >>>>>>>>>> 
> >>>>>>>>>> _______________________________________________
> >>>>>>>>>> netmod mailing list
> >>>>>>>>>> [e-mail]
> >>>>>>>>>> https://www.ietf.org/mailman/listinfo/netmod
> >>>>>>>>>> 
> >>> _______________________________________________
> >>> netmod mailing list
> >>> [e-mail]
> >>> https://www.ietf.org/mailman/listinfo/netmod
> >> 
> > _______________________________________________
> > netmod mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/netmod
> 

> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod


-- 
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://www.jacobs-university.de/>