Subject: [Netconf] request review of media type application/yang-data+xml

From: Andy Bierman <[email-masked]>
Date: Tue, 28 Jun 2016 19:24:59 -0700

Hi,

Please review and provide feedback on the revised media type registration
for the RESTCONF protocol.

https://tools.ietf.org/html/draft-ietf-netconf-restconf-14#section-11.3.1

thanks,
Andy

---

From: Sean Leonard <[email-masked]>
Date: Tue, 28 Jun 2016 20:06:27 -0700

It is considered customary to copy and paste *just* the registration 
text in this mailing list.
Here you go:

    Type name: application

    Subtype name: yang-data+xml

    Required parameters: none

    Optional parameters: none

   // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with
   // the actual RFC reference for YANG 1.1, and remove this note.

    Encoding considerations: 8-bit
       Each conceptual YANG data node is encoded according to
       XML Encoding Rules and Canonical Format for the specific
       YANG data node type defined in [draft-ietf-netmod-rfc6020bis].

   // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the
   // section number for Security Considerations
   // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual
   // RFC number, and remove this note.

    Security considerations: Security considerations related
       to the generation and consumption of RESTCONF messages
       are discussed in Section NN of [RFCXXXX].
       Additional security considerations are specific to the
       semantics of particular YANG data models. Each YANG module
       is expected to specify security considerations for the
       YANG data defined in that module.

   // RFC Ed.: replace XXXX with actual RFC number and remove this
   // note.

    Interoperability considerations: [RFCXXXX] specifies format of
       conforming messages and the interpretation thereof.

   // RFC Ed.: replace XXXX with actual RFC number and remove this
   // note.

    Published specification: RFC XXXX

    Applications that use this media type: Instance document
      data parsers used within a protocol or automation tool
      that utilizes YANG defined data structures.

    Fragment identifier considerations: The fragment field in the
       request URI has no defined purpose.

    Additional information:

      Deprecated alias names for this type: n/a
      Magic number(s): n/a
      File extension(s): .xml
      Macintosh file type code(s): "TEXT"

   // RFC Ed.: replace XXXX with actual RFC number and remove this
   // note.

    Person & email address to contact for further information: See
       Authors' Addresses section of [RFCXXXX].

    Intended usage: COMMON

    (One of COMMON, LIMITED USE, or OBSOLETE.)

    Restrictions on usage: n/a

   // RFC Ed.: replace XXXX with actual RFC number and remove this
   // note.

    Author: See Authors' Addresses section of [RFCXXXX].

    Change controller: Internet Engineering Task Force
       (mailto:iesg&ietf.org).

    Provisional registration? (standards tree only): no

---

From: Sean Leonard <[email-masked]>
Date: Tue, 28 Jun 2016 20:17:56 -0700

Based on the discussion on media-types@ and netconf@ that I have 
observed, the registration is in pretty good substantive shape. I have 
no substantive comments except for the fragment identifier, which I 
understand is not of consequence to YANG processors. What follows below 
are mostly editorial edits:

>    Required parameters: none

Usually I see this written "None." Purely editorial preference.

>    Optional parameters: none

Ditto.

>       YANG data node type defined in [draft-ietf-netmod-rfc6020bis].

"is encoded according to the XML Encoding Rules"...

>       conforming messages and the interpretation thereof.

"[RFCXXXX] specifies the format of"...

>      that utilizes YANG defined data structures.

"Instance document data parsers used within a protocol or automation tool
      that utilize YANG-defined data structures."

Change utilizes -> utilize. It's plural.

I think YANG-defined is correct due to being stacked noun phrases, or 
something.

>       request URI has no defined purpose.

 From the perspective of NETCONF this is probably correct. However, 
Section 4.11 of RFC 6838 says:

    Media types are encouraged to adopt fragment identifier schemes that
    are used with semantically similar media types.  In particular, media
    types that use a named structured syntax with a registered "+suffix"
    MUST follow whatever fragment identifier rules are given in the
    structured syntax suffix registration.

There are some things about +xml things:
http://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml

RFC 7303.

Look it up.

I don't have experience dealing with this, and I would not hold back the 
registration on that basis. The Expert Reviewer might.

>    (One of COMMON, LIMITED USE, or OBSOLETE.)

You can remove the parenthetical. It's not part of the template instance.

>    Restrictions on usage: n/a

RFC 6838 Section 5.6 says '"N/A", written exactly that way'. Stick with 
N/A (all-caps).

>    Provisional registration? (standards tree only): no

You can also remove the parenthetical. It's not part of the template 
instance.

Best regards,

Sean

> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

---

From: Andy Bierman <[email-masked]>
Date: Thu, 30 Jun 2016 17:52:43 -0700

On Tue, Jun 28, 2016 at 8:17 PM, Sean Leonard <[email-masked]> wrote:

removing all text except the fragment identifier issue....

According to RFC 7303, sec. 5, any usage of +xml requires implementation of
the XPointerFramework
https://www.w3.org/TR/2003/REC-xptr-framework-20030325/

RESTCONF "fragments" are sub-trees within the YANG data structures.
These are accessed by the request URI path and the "fields" query parameter.
XPointer is rather complex and completely redundant for RESTCONF.

So do we have to add text that a RESTCONF server MUST implement the
"element"
scheme?

> From the perspective of NETCONF this is probably correct. However, Section
> 4.11 of RFC 6838 says:
>

   The syntax and semantics of fragment identifiers for the XML media
   types defined in this specification are based on the
   [XPointerFramework
<https://tools.ietf.org/html/rfc7303#ref-XPointerFramework>] W3C
Recommendation.  It allows simple names and
   more complex constructions based on named schemes.  When the syntax
   of a fragment identifier part of any URI or Internationalized
   Resource Identifier (IRI) ([RFC3987
<https://tools.ietf.org/html/rfc3987>]) with a retrieved media type
   governed by this specification conforms to the syntax specified in
   [XPointerFramework
<https://tools.ietf.org/html/rfc7303#ref-XPointerFramework>],
conforming applications MUST interpret such
   fragment identifiers as designating whatever is specified by the
   [XPointerFramework
<https://tools.ietf.org/html/rfc7303#ref-XPointerFramework>] together
with any other specifications governing
   the XPointer schemes used in those identifiers that the applications
   support.  Conforming applications MUST support the 'element' scheme
   as defined in [XPointerElement
<https://tools.ietf.org/html/rfc7303#ref-XPointerElement>], but need
not support other schemes.

Registrations which use this '+xml' convention MUST also make
reference to [RFC7303 <http://www.iana.org/go/rfc7303>], specifically
Section 5, in specifying fragment identifier syntax and semantics, and
they MAY restrict the syntax to a specified subset of schemes, except
that they MUST NOT disallow barenames or 'element' scheme pointers.
They MAY further require support for other registered schemes. They
also MAY add additional syntax (which MUST NOT overlap with
[XPointerFramework
<http://www.w3.org/TR/2003/REC-xptr-framework-20030325/>] syntax)
together with associated semantics, and MAY add additional semantics
for barename XPointers which, as provided for in Section 5, will only
apply when [RFC7303 <http://www.iana.org/go/rfc7303>] does not define
an interpretation.

In practice these constraints imply that for a fragment identifier
addressed to an instance of a specific "xxx/yyy+xml" type, there are
three cases:

For fragment identifiers matching the syntax defined in
[XPointerFramework
<http://www.w3.org/TR/2003/REC-xptr-framework-20030325/>], where the
fragment identifier resolves per the rules specified there, then
process as specified there;

For fragment identifiers matching the syntax defined in
[XPointerFramework
<http://www.w3.org/TR/2003/REC-xptr-framework-20030325/>], where the
fragment identifier does _not_ resolve per the rules specified there,
then process as specified in "xxx/yyy+xml";

For fragment identifiers _not_ matching the syntax defined in
[XPointerFramework
<http://www.w3.org/TR/2003/REC-xptr-framework-20030325/>], then
process as specified in "xxx/ yyy+xml". A fragment identifier of the
form "xywh=160,120,320,240", as defined in [MediaFrags
<http://www.w3.org/TR/2012/REC-media-frags-20120925/>], which might be
used in a URI for an XML-encoded image, would fall in this category.
See Section 10, [RFC7303 <http://www.iana.org/go/rfc7303>].

Andy