Re: [VCARDDAV] Last call comments: XML draft

[Simon Perreault <[e-mail]>]

On 2010-06-01 10:40, Cyrus Daboo wrote:
> Section 1: Change "individuals" to "individuals and resources".

Changed to "individuals and other entities", since "resources" is a
loaded term in scheduling. That's also what's in the abstract for vCard.

> Section 4.1: Change "from IANA" to "with IANA".

Done.

> Section 4.1: First paragraph. "separate document may be used instead". I
> don't really understand this statement.

Me neither, and I wrote it... :(

Removed.

> By default any vCard items
> registered with IANA are automatically valid elements in the XML. The
> only case where a separate definition for XML is needed is if a new
> structured value type is defined that requires sub-elements.

It's true that most of this schema can be derived algorithmically. But
this algorithm hasn't been written down, so we can't expect people to
just infer XML syntax from plain vCard syntax.

Even if such an algorithm was published, I'd still prefer vCard
extensions to list the output of this algorithm explicitly (the output
being the XML schema for the extensions).

And it's not about checking for validity. As you say, everything that is
not recognized is valid. Most of a schema's value is in communicating
without ambiguity how data should be formatted.

> Section 4.1: Second paragraph. I thought we had agreed that X- and VND-
> properties would be in the vcard-4.0 namespace.

True. But one could still use XML namespaces. I changed it to:

   Unregistered extensions (i.e. those starting with "X-" and
   "VND-...-") are expressed in XML by using elements starting with "x-"
   and "vnd-...-".  Usage of XML namespaces for extensibility is
   RECOMMENDED for extensions that have no equivalent in plain text
   vCard.  Refer to Section 5 for the implications when converting
   between plain-text vCard and XML.

   Examples:

     <x-my-prop>
       <parameters>
         <pref>1</pref>
       <text>value goes here</text>
     <x-my-prop>

     <ext:my-prop
         ext:xmlns="http://example.com/extensions/my-vcard">
       <parameters>
         <pref>1</pref>
       </parameters>                 <!-- Core vCard elements  -->
       <text>value goes here</text>  <!-- are still accessible -->
     </ext:my-prop>

> Section 5: Empty "o" bullet before "*" bullets in the list (several times).

Fixed.

> Section 5: Change: "The name of the property element is set to that of
> the property." to "The name of the property element is set to the
> lowercased name of the property."

Done.

> Section 5: Change: "If the property has attributes, they get translated
> as-is into sub-elements of the <parameters> element" to "If the property
> has parameters, they get translated as-is (with lowercasing of parameter
> names, removal of backslash escaping, and removal of quoting) into
> sub-elements of the <parameters> element.".

Done.

> Section 7: Add a MIME type registration for application/vcard+xml.

Done.

> General issues:
> 
> 1. Backslash escaping: there is no need to preserve backslash escaping
> because list items are broken out into separate elements. So backslash
> escaping must be removed/added when converting to/from XML. This needs
> to be discussed in Section 5.

> 2. Parameter quoting: there is no need to maintain double-quotes around
> parameter values in the XML. So double-quotes around parameter values
> must be removed/added when converting to/from XML as appropriate. This
> needs to be discussed in Section 5.

Agreed. Added the following 4 bullets:

   When converting from XML vCard (this specification) to plain-text
   vCard [I-D.ietf-vcarddav-vcardrev], the following rules apply:
   [...]
   o  Property value escaping (Section 3.3 of
      [I-D.ietf-vcarddav-vcardrev]) is carried out.  For example, a
      NEWLINE character (ASCII decimal 10) becomes "\n".

   o  Double-quoting of parameter values, as well as backslash escaping
      in parameter values, is carried out.  For example,
      <param>"foo","bar"</param> becomes PARAM="\"foo\",\"bar\"".

   When converting from plain-text vCard [I-D.ietf-vcarddav-vcardrev] to
   XML vCard (this specification), the following rules apply:
   [...]
   o  Property value escaping is undone.  For example, "\n" becomes a
      NEWLINE character (ASCII decimal 10).

   o  Double-quoting of parameter values, as well as backslash escaping
      in parameter values, is undone.  For example,
      PARAM="\"foo\",\"bar\"" becomes <param>"foo","bar"</param>.

> 3. There needs to be some discussion of the <vcards> root element as
> there is no direct analogue of that in vCard.

Added the following paragraph in section 4:

   A top-level <vcards> element is used as root.  It contains one or
   more <vcard> element, each representing a complete vCard.  The
   <vcards> element MUST be present even when only a single vCard is
   present in an XML document.

> 4. There needs to be some discussion of the special treatment of groups
> and probably an example too.

Agreed. Here's what I came up with:

   The group construct (Section 3.2 in [I-D.ietf-vcarddav-vcardrev]) is
   represented with the <group> element.  The "name" attribute contains
   the group's name.  For example:

     <vcards>
       <vcard>
         <group name="contact">
           <fn>...</fn>
           <email>...</email>
         </group>
         <group name="media">
           <photo>...</photo>
         </group>
         <categories>...</categories>
       </vcard>
     </vcards>

   is equivalent to:

     BEGIN:VCARD
     VERSION:4.0
     contact.FN=...
     contact.EMAIL=...
     media.PHOTO=...
     CATEGORIES=...
     END:VCARD

Thanks for the review!
Simon
-- 
NAT64/DNS64 open-source --> http://ecdysis.viagenie.ca
STUN/TURN server        --> http://numb.viagenie.ca
vCard 4.0               --> http://www.vcarddav.org