Subject: Re: [VCARDDAV] I-D Action:draft-ietf-vcarddav-vcardxml-01.txt

From: Joe Hildebrand <[email-masked]>
Date: Mon, 23 Nov 2009 19:30:21 -0700

Sorry I was double-booked in Hiroshima and couldn't attend.  I've got some
comments on this draft:

1) My view is that it should be possible to write a vcard processor using
just draft-ietf-vcarddav-vcardrev and draft-ietf-vcarddav-vcardxml, that can
convert between the two formats without losing data.  I don't see how that's
possible with the current extensibility approach.  For each X- or VND-
property  in the non-XML format, I have to know what new schema to map into;
for unknown names, I have nothing to map into.

2) The mapping from the structured text approach (N, ADR, ORG) to the XML
schema seems pretty underspecified to me.  For example, the fact that the
second component of N ("Given Names") maps to "<given/>" is left implicit.
It would be easier to implement (albeit less semantic) to have a mechanical
mapping between structured text properties and the XML representation of
those lines.  Example (with intentionally ugly syntax):

<n>
  <c0><text>Perreault</text></c0>
  <c1><text>Simon</text></c1>
  <c2><text/></c2>
  <c3>
    <text>ing. jr.</text>
    <text>M.Sc.</text>
  </c3>
</n>

3) The XML property should be restricted to extension properties that do not
have known mappings to textual format.  This will cut down on the ugly use
cases that have been proposed on this list, and ensure that text-based
processors don't have to *also* implement all of the XML logic.

4) "XML chunk" from section 5 is not defined, nor is it a standard term in
the XML world; you might have meant "fragment".  It's probably better to say
that an XML property is a single element that expects to be inserted as a
child of a vcard element as defined in this spec.  You could reuse the term
"stanza" from the XMPP world, if you wanted.  If you have multiple stanzas,
you use multiple XML content lines.

5) Mapping *from* XML properties in text format to XML format is
unspecified.  Presumably they get un-wrapped and inserted in order.

6) No (un)escaping rules are specified for &, <, and >.  Test: what if I've
got this content line from the text format:

NICKNAME:Dazed&amp;Confused

7) I'm concerned about textual processors needing to look inside the XML
properties to find extensions that the XML processor didn't know how to
encode into text.  If we pull the name/namespace of the top level element of
the stanza out into text world, that problem becomes easier to deal with:

XML;NAME=my-prop;NS=http://example.com/extensions/my-vcard:<ext:my-prop\n \
    ext:xmlns="http://example.com/extensions/my-vcard">\n  <parameters>\n \
    <pref>1</pref>\n  </parameters>                 <!-- Core vCard elemen\
 ts  -->\n  <text>value goes here</text>  <!-- are still accessible -->\n<\
 /ext:my-prop>

8) Nit: "A vCard XML parser MUST ignore XML data qualified by a namespace it
does not understand."  We might want to add new names to an existing
namespace in the future.  If you say "MUST ignore XML data with an element
name/namespace combination that it does not understand", we'll be a little
better off.

On 10/21/09 9:00 AM, "[email-masked]" <[email-masked]>
wrote:

> A New Internet-Draft is available from the on-line Internet-Drafts
> directories.
> This draft is a work item of the vCard and CardDAV Working Group of the IETF.
> 
> 
> Title           : vCard XML Schema
> Author(s)       : S. Perreault
> Filename        : draft-ietf-vcarddav-vcardxml-01.txt
> Pages           : 15
> Date            : 2009-10-21
> 
> This document defines the XML schema of the vCard data format.
> 
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-ietf-vcarddav-vcardxml-01.txt
> 
> Internet-Drafts are also available by anonymous FTP at:
> ftp://ftp.ietf.org/internet-drafts/
> 
> Below is the data which will enable a MIME compliant mail reader
> implementation to automatically retrieve the ASCII version of the
> Internet-Draft.
> _______________________________________________
> VCARDDAV mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/vcarddav

-- 
Joe Hildebrand

---

From: Joe Hildebrand <[email-masked]>
Date: Mon, 23 Nov 2009 19:33:10 -0700

And I made the rookie mistake of replying to the I-D announce list and .
Please edit your to addresses before replying.

-- 
Joe Hildebrand

---

From: Simon Perreault <[email-masked]>
Date: Tue, 24 Nov 2009 08:30:58 -0500

Thank you very much for your review!

> for unknown names, I have nothing to map into.

Fair point. A few questions:

- What if X-FOO doesn't have an XML mapping?
- If we define a generic mapping for X-FOO, can we use it for everything else?
- What about the reverse direction? How do you translate a generic XML tree? You
just use the "XML" property? If so, then why not have the equivalent of the
"XML" property in XML? e.g. <vctext>X-FOO:Bar baz</vctext>
- What do you propose as a solution?

>   <c1><text>Simon</text></c1>

This seems to be addressing my second question above.

My main objection to this is that it imposes on the XML format the same
constraints as the vCard format. You don't want eventual XML-only properties to
be constrained like that.

> processors don't have to *also* implement all of the XML logic.

On the contrary! What we want is to ensure that XML-based processors don't have
to *also* implement all of the legacy vCard logic.

> the XML world; you might have meant "fragment".

Thanks, that's exactly what I meant.

I couldn't find an official definition of "fragment", although I found a
definition of "DocumentFragment" in DOM 2
<http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-B63ED1A3>. Should I cite
that or is there a better reference?

>  It's probably better to say

What is the rationale for limiting to just one element per property instance?

> unspecified.  Presumably they get un-wrapped and inserted in order.

True. It will be more explicit in the next version.

> NICKNAME:Dazed&amp;Confused

Ah, right. Just so we understand each other, in this case the text value is
"Dazed&amp;Confused" (pronounced "dazed and amp confused"). In XML it would become:

<nickname>
  <text>Dazed&amp;amp;Confused</text>
</nickname>

I'll put this example in the next version. This is one very good case where
interoperability could be trashed if we're not careful.

>  ts  -->\n  <text>value goes here</text>  <!-- are still accessible -->\n<\

Yeouch. My gut reaction is to fear duplication because of out-of-sync problems.

What would a text vCard processor do with the NAME and NS parameters?

> name/namespace combination that it does not understand", we'll be a little

Yes, that's also mentioned in the email I just forwarded from Paul E. Jones.

For now I'm thinking of this: "A vCard XML parser MUST ignore XML elements and
attributes for which it does not understand the qualified name."

Can XML "things" other than elements and attributes have a qualified name?

Thanks again,
Simon
-- 
DNS64 open-source   --> http://ecdysis.viagenie.ca
STUN/TURN server    --> http://numb.viagenie.ca
vCard 4.0           --> http://www.vcarddav.org

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Nov 2009 14:47:04 +0100

Simon Perreault wrote:
> ...
> ...

Citing an API definition here appears to be bad.

Either the XML spec or the XML Infoset spec should define what you need; 
for instance:

<http://www.w3.org/TR/REC-xml/#NT-content>.

> Can XML "things" other than elements and attributes have a qualified name?

Actually, the *qualified* name doesn't matter (that's prefix + local 
name). What's relevant is the *expanded* name (namspace uri + local name).

Only elements and attributes use namespaces, but make sure you don't 
forbid things you want to allow (such as processor-specific PIs).

BR, Julian

---

From: Peter Saint-Andre <[email-masked]>
Date: Tue, 24 Nov 2009 16:02:36 -0700

> <http://www.w3.org/TR/REC-xml/#NT-content>.

I'd reference this:

http://www.w3.org/TR/2001/CR-xml-fragment-20010212

> name). What's relevant is the *expanded* name (namspace uri + local name).

Right:

http://www.w3.org/TR/REC-xml-names/#dt-expname

> forbid things you want to allow (such as processor-specific PIs).

Do we want to allow those?

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Joe Hildebrand <[email-masked]>
Date: Wed, 25 Nov 2009 02:50:09 -0700

> - What if X-FOO doesn't have an XML mapping?

We need to be able to generate something generic for X- as well as IANA
properties.  One possible approach would be:

X-FOO;bar=baz;boo=goo:some text

Could become:

<property>
  <name>X-FOO</name>
  <value><unknown>;bar=baz;boo=goo:some text</unknown></value>
</property>

or:

<property>
  <name>X-FOO</name>
  <parameters><unknown>bar=baz;boo=goo</unkown></parameters>
  <value><unknown>some text</unknown></value>
</property>

or:

<property>
  <name>X-FOO</name>
  <parameters>
    <unknown>bar=baz</unkown>
    <unknown>boo=goo</unkown>
  </parameters>
  <value><unknown>some text</unknown></value>
</property>

Depending upon how regular we think extensions are going to be.

> - If we define a generic mapping for X-FOO, can we use it for everything else?

Yes.  But it would mean that the schema would have to change pretty
radically to remove all of the property names.  It might be more natural to
use attributes for some of the annotation in that case.

> "XML" property in XML? e.g. <vctext>X-FOO:Bar baz</vctext>

I think that the XML property should be reserved for things you just have no
other way of dealing with.  It will cause text processors to not be able to
use that data easily.

> - What do you propose as a solution?

Let's work on how to render X-FOO: into XML first, then see if we want to
change the other parts of the schema.

> constraints as the vCard format. You don't want eventual XML-only properties
> to be constrained like that.

Agree.  XML-only properties would get rendered into text format as XML:,
since there is no textual representation for them.  How we get the text
format for properties that *do* have a text format is the question, however.

> On the contrary! What we want is to ensure that XML-based processors don't
> have to *also* implement all of the legacy vCard logic.

In my mind, the XML property is only used in the text format.  XML
processors will just use XML.  Given that, I don't understand what would be
left of legacy vCard logic that the XML processor would have to deal with.

If I'm writing a text processor, however, having to deal with the XML bits
is going to be pretty difficult, particularly if there are two different
ways of encoding well-loved old properties like N.

> What is the rationale for limiting to just one element per property instance?

Relatively-naïve text processors could throw the element into a
document-based XML parser, giving it the content-encoding that is known for
the text format, and you're likely to get usable data out.  If these are
fragments, or worse, incomplete elements, dealing with XML properties is
going to require much more sophisticated processing, such as gathering all
of the XML properties together and wrapping them in a <vcards><vcard> pair.

If we expect folks to do this naïve parsing, we should change the
recommended namespacing on elements that go into an XML property, so that
the default namespace is urn:ietf:params:xml:ns:vcard-4.0.  Example:

<ext:my-prop 
  xmlns="urn:ietf:params:xml:ns:vcard-4.0"
  ext:xmlns="http://example.com/extensions/my-vcard">
  <parameters>
...

This way, the <parameters/> element ends up in the correct namespace with a
naïve parse.  We can recommend removing the (then)redundant namespace
declaration when converting text format to XML format.

>   <text>Dazed&amp;amp;Confused</text>

Yes.

> Yeouch. My gut reaction is to fear duplication because of out-of-sync

If we say that each XML property is exactly one element, then we don't need
to pull out the name and namespace, however it does seem like a nice
convenience.

> What would a text vCard processor do with the NAME and NS parameters?

Decide if it needed to XML parse the property, because it contains an
extension that this text processor knows about.

-- 
Joe Hildebrand

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Nov 2009 11:09:22 +0100

> http://www.w3.org/TR/2001/CR-xml-fragment-20010212

This has been a "Candidate Rec" for 8 years with no work since; not sure 
whether it's the right thing to quote.

What's wrong with just citing the XML spec?

> Do we want to allow those?

They are IMHO harmless and sometimes moderately useful. I don't see a 
good reason to forbid them.

Best regards, Julian

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 25 Nov 2009 09:02:54 -0700

> What's wrong with just citing the XML spec?

Because it doesn't define "XML fragment". The CR I pointed to is the
best reference I've found for that concept.

> good reason to forbid them.

I'm just trying to envision the use cases here. Perhaps I'm not
imaginative enough, but nothing is coming to mind.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Nov 2009 17:10:14 +0100

> best reference I've found for that concept.

I followed up on xml-dev, where David Carlisle mentioned the CR as well.

> imaginative enough, but nothing is coming to mind.

I think when discussing the use of XML, what should be relevant is 
whether a specific feature would be problematic. In doubt, do not 
profile the format. So what would be a reason to *forbid* PIs?

BR, Julian

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 25 Nov 2009 09:43:47 -0700

> profile the format. So what would be a reason to *forbid* PIs?

Fair enough. We forbid them in XMPP, but we have a different usage
profile of XML...

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Joe Hildebrand <[email-masked]>
Date: Wed, 25 Nov 2009 11:33:53 -0700

> good reason to forbid them.

Because a text processor is less likely to be able to parse the XML.  It
harms interoperability to allow them.

-- 
Joe Hildebrand

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Nov 2009 19:39:42 +0100

> harms interoperability to allow them.

That doesn't compute. Are you suggesting to parse the XML with anything 
except an XML parser????

BR, Julian

---

From: Ned Freed <[email-masked]>
Date: Sun, 29 Nov 2009 11:16:36 -0800 (PST)

>   <value><unknown>some text</unknown></value>

FWIW, more or less the same issue exists when representing Sieve in XML. We
solved the problem by writing:

   <control name="if">
     <test name="exists>
       <str>X-Whatever</str>
     </test>
     <action name="keep"/>
   </control>

Instead of writing something like:

   <if>
     <exists>
       <str>X-Whatever</str>
     </exists>
     <keep>
   </if>

There is absolutely no doubt that the second form is easier to read. But this
approach requires changing the schema every time there's an extension, which in
the case of Sieve is "often".

More generally, the first question that needs to be asked isn't how to
represent extension elements, but rather whether there should be a separate
representation for extension elements version normally defined elements. In the
case of Sieve the fact that an extension can add pretty much anything that
doesn't change the core syntax to the language makes a strong argument for
a single mechanism. In the case of vCard, the fact that extensions are
relegated to what amounts to a separate namespace argues for something along
the lines of what you're proposing, although  I have to say I think judicious
use of attributes would make it more readable, as in:

  <property name="X-Foo">
    <parameter name="bar">baz</parameter>
    <parameter name="boo">goo</parameter>
    <value><unknown>some text</unknown></value> 
  </property>

> Depending upon how regular we think extensions are going to be.

Actually, I don't think that's the criteria that should be used. For one thing,
past experience has shown that it is very difficult to predict to what extent a
given extension mechanism will be employed. But more to the point, even
supposing extensions are rare, that's hardly an argument for failing to
come up with the cleanest representation possible.

I have to say the  thing I really don't like about your proposed format
is the leakage of ical text syntax elemnts into the XML. I should not have
to write code to look for the equqls sign separate in something like:

So, regardless of how things end up in the eternal debate between the use of
attributes and elements, I think the syntax elements in the regular
represenation need to be mapped to XML structures, not encapsulated.

> use attributes for some of the annotation in that case.

That is not, in and of itself, a reason not to opt for the route we took for
representing Sieve in XML. The main reason I see for having specific mappings
for well known properties, parameters, and so on is that it lets the schema
perform much more extensive type checking. This was mostly a nonissue in Sieve
since extensions have the abiltiy to add or change arguments, meaning that if
we wanted this level of type checking in the schema we're back to having
extensions change the schema. But AFAIK vCard doesn't allow extensions that
change core fields around, so there's considerable potential value in having an
XML representation that does the additional checks.

> change the other parts of the schema.

That seems reasonable to me.

				Ned