Subject: [VCARDDAV] vCard parameters in XML: attributes or elements?

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 10:23:35 -0400

Hello,

First, check out the two attached examples of proposed vCard XML syntax. Which
one do you prefer?

At IETF 73 in Minneapolis it was argued that the parameters-as-elements proposal
was superior because it made searching on multi-valued parameters easier. For
example, to get all the cell phones in XSLT 2.0, you'd do the following:

<xsl:variable name="cells" select="//tel[type='cell']"/>

Whereas with the parameters-as-attributes proposal you'd do the following:

<xsl:variable name="cells" select="//tel[matches(type,'(^|,)cell(,|$)')]"/>

I'm not sure what to make of this argument in light of this example.

Note also that of all the vCard parameters we have, only TYPE can be multi-valued.

I, for one, find the parameters-as-elements proposal silly-looking and overly
complicated.

I'm looking for some direction here.

Thanks,
Simon
-- 
STUN/TURN server    --> http://numb.viagenie.ca
Interplanetary news --> http://reeves.viagenie.ca
vCard 4.0           --> http://www.vcarddav.org
<?xml version="1.0" encoding="UTF-8"?>
<vcard xmlns="urn:ietf:params:xml:ns:vcard-4.0">
  <fn>Simon Perreault</fn>
  <n>
    <surname>Perreault</surname>
    <given>Simon</given>
    <suffix>ing. jr.</suffix>
    <suffix>M.Sc.</suffix>
  </n>
  <bday>--0203</bday>
  <gender>M</gender>
  <lang pref="1">fr</lang>
  <lang pref="2">en</lang>
  <group name="work">
    <org><name>Viagenie</name></org>
    <adr>
      <ext>Suite 625</ext>
      <street>2600 boul. Laurier</street>
      <locality>Quebec</locality>
      <region>QC</region>
      <postal>G1V 4W1</postal>
      <country>Canada</country>
    </adr>
    <tel type="voice">tel:+1-418-656-9254;ext=102</tel>
    <tel type="cell,voice,video,text">tel:+1-418-262-6501</tel>
    <tel type="fax">tel:+1-418-656-9257</tel>
    <email>[email-masked]</email>
    <geo>geo:46.772673,-71.282945</geo>
    <key value="uri">
      http://www.viagenie.ca/simon.perreault/simon.asc
    </key>
  </group>
  <tz>-0500</tz>
  <class>public</class>
</vcard>
<?xml version="1.0" encoding="UTF-8"?>
<vcard xmlns="urn:ietf:params:xml:ns:vcard-4.0">
  <fn>
    <text>Simon Perreault</text>
  </fn>
  <n>
    <surname>Perreault</surname>
    <given>Simon</given>
    <suffix>ing. jr.</suffix>
    <suffix>M.Sc.</suffix>
  </n>
  <bday>
    <date>--0203</date>
  </bday>
  <gender>M</gender>
  <lang>
    <pref>1</pref>
    <language-tag>fr</language-tag>
  </lang>
  <lang>
    <pref>2</pref>
    <language-tag>en</language-tag>
  </lang>
  <group name="work">
    <org>
      <name>Viagenie</name>
    </org>
    <adr>
      <ext>Suite 625</ext>
      <street>2600 boul. Laurier</street>
      <locality>Quebec</locality>
      <region>QC</region>
      <postal>G1V 4W1</postal>
      <country>Canada</country>
    </adr>
    <tel>
      <type>voice</type>
      <uri>tel:+1-418-656-9254;ext=102</uri>
    </tel>
    <tel>
      <type>cell</type>
      <type>voice</type>
      <type>video</type>
      <type>text</type>
      <uri>tel:+1-418-262-6501</uri>
    </tel>
    <tel>
      <type>fax</type>
      <uri>tel:+1-418-656-9257</uri>
    </tel>
    <email>
      <text>[email-masked]</text>
    </email>
    <geo>
      <uri>geo:46.772673,-71.282945</uri>
    </geo>
    <key>
      <uri>http://www.viagenie.ca/simon.perreault/simon.asc</uri>
    </key>
  </group>
  <tz>
    <utc-offset>-0500</utc-offset>
  </tz>
  <class>
    <text>public</text>
  </class>
</vcard>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 29 Apr 2009 17:08:34 +0200

Simon Perreault wrote:
> ...

Ha, an XML bikeshed. What a welcome distraction :-)

> <xsl:variable name="cells" select="//tel[matches(type,'(^|,)cell(,|$)')]"/>

Sort of, because that requires XSLT 2.0.

Having multiple *whitespace* (not comma) separated tokens in an 
attribute value is a relatively frequent pattern in XML based languages 
(such as XHTML class names).

In which case, you can match (even in XSLT 1.0) using

	select="//tel[contains(concat(@type,' '), 'cell ')"

which I think is good enough as long as people realize that a simple 
"contains" will not be correct.

> ...

BR, Julian

---

From: Joseph Smarr <[email-masked]>
Date: Wed, 29 Apr 2009 08:24:21 -0700

I *strongly* prefer using NO attributes in the XML representation because it
makes it much easier to represent the data structure in JSON and in dynamic
programming languages (php, python, ruby, etc.) whose data structures are
naturally lists and maps. If you mix attributes and sub-elements, you
essentially have two overlapping and potentially conflicting key-value maps,
which doesn't do anyone any favors. If you look at the way we handle
essentially vCard XML serialization in Portable Contacts, we ONLY use
sub-elements. It's clean and simple and easy to program for.

At IETF74 we discussed the desire to align vCard 4.0 XML and Portable
Contacts as closely as possible, since many large webmail and social network
providers are already exposing contact info in this format, and it
round-trips 1:1 with traditional vCard. So if this is an active topic again,
please consider the careful design trade-offs we made in PoCo (see
http://portablecontacts.net/draft-spec.html) and if you decide you want to
do things differently, let's please at least have a discussion so I can
explain the rationale coming out of our community and at least we can make
sure we're not diverging "just because"...

Thanks! js

On Wed, Apr 29, 2009 at 8:08 AM, Julian Reschke <[email-masked]>wrote:

>> <xsl:variable name="cells"
>> select="//tel[matches(type,'(^|,)cell(,|$)')]"/>
>>
>
> Having multiple *whitespace* (not comma) separated tokens in an attribute
> value is a relatively frequent pattern in XML based languages (such as XHTML
> class names).
>
> _______________________________________________
> VCARDDAV mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/vcarddav
>

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 11:24:23 -0400

> Sort of, because that requires XSLT 2.0.

Or Perl, or C, or whatever you use to process XML. Just not XSLT 1.0.

> "contains" will not be correct.

Cool! This would work with commas too, right?

We could even use that snippet in an examples section.

Simon

---

From: Julian Reschke <[email-masked]>
Date: Wed, 29 Apr 2009 17:32:16 +0200

> We could even use that snippet in an examples section.

I'd recommend using whitespace, because that's what XML's NMTOKENS use, 
and people already know as design pattern.

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 29 Apr 2009 17:33:52 +0200

Joseph Smarr wrote:
> I *strongly* prefer using NO attributes in the XML representation 
> because it makes it much easier to represent the data structure in JSON 
> and in dynamic programming languages (php, python, ruby, etc.) whose 
> data structures are naturally lists and maps. If you mix attributes and 
> sub-elements, you essentially have two overlapping and potentially 
> conflicting key-value maps, which doesn't do anyone any favors. If you 
> look at the way we handle essentially vCard XML serialization in 
> Portable Contacts, we ONLY use sub-elements. It's clean and simple and 
> easy to program for.
> ...

Understood; on the other hand, optimizing an XML vocabulary for 
representation in object IMHO is the wrong approach; readability *is* 
important.

BR, Julian

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 11:40:37 -0400

> Portable Contacts, we ONLY use sub-elements. It's clean and simple and

In the parameters-as-attributes proposal, sub-elements are only used for
compound types (i.e. N, ADR, ORG). In all other cases, the value is directly the
content of the property element. So there is nothing to mix in the majority of
cases, and to mix stuff in the other cases you really have to want to.

I fail to see how a vCard representation in XML would imply anything about a
vCard  representation in JSON.

> Contacts as closely as possible, since many large webmail and social
> network providers are already exposing contact info in this format, and
> it round-trips 1:1 with traditional vCard. So if this is an active topic
> again, please consider the careful design trade-offs we made in PoCo
> (see http://portablecontacts.net/draft-spec.html) and if you decide you
> want to do things differently, let's please at least have a discussion
> so I can explain the rationale coming out of our community and at least
> we can make sure we're not diverging "just because"...

This is the discussion now. I'm not sure what else you'd like...

Simon

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 29 Apr 2009 12:12:35 -0400

Hi Simon,

--On April 29, 2009 10:23:35 AM -0400 Simon Perreault 
<[email-masked]> wrote:

> First, check out the two attached examples of proposed vCard XML syntax.
> Which one do you prefer?
>
>
> At IETF 73 in Minneapolis it was argued that the parameters-as-elements
> proposal was superior because it made searching on multi-valued
> parameters easier. For example, to get all the cell phones in XSLT 2.0,
> you'd do the following:
>
> I, for one, find the parameters-as-elements proposal silly-looking and
> overly complicated.

There will be an iCalendar-in-XML spec published in the next few days that 
does parameters-as-elements. We went through all the arguments and 
determined this was the best approach (many of the considerations that 
Joseph described in his reply were relevant). Whether the XML looks "silly" 
or not to a human really isn't the point - its what makes more sense to the 
kinds of manipulations that you want to do with the XML.

Of course consensus needs to be achieved on the iCalendar spec within IETF 
too. But I think it is critical that both specs take the same approach 
given how their "normal" data formats are so close.

-- 
Cyrus Daboo

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 29 Apr 2009 12:18:26 -0400

Hi Simon,

--On April 29, 2009 11:40:37 AM -0400 Simon Perreault 
<[email-masked]> wrote:

> compound types (i.e. N, ADR, ORG). In all other cases, the value is
> directly the content of the property element. So there is nothing to mix
> in the majority of cases, and to mix stuff in the other cases you really
> have to want to.

So that does not work in iCalendar because properties can have different 
value types. e.g. the ATTACH property can be VALUE=URI or VALUE=BINARY. 
Having an element for each value type makes things much clearer as to what 
is being dealt with rather than having an attribute determine what the 
value is in the element. For consistency of transformation we felt that 
even the properties only defined to support one value type should still 
encapsulate that value in the corresponding element.

-- 
Cyrus Daboo

---

From: Zahhar Kirillov <[email-masked]>
Date: Wed, 29 Apr 2009 19:23:15 +0300

Just the 2 cents from a developer's point of view: it is really no big
difference for machine to deal with attributes or elements. And thus
XML is not supposed to be edited by end-user, representation style is
not relevant for him too.

What is relevant? Extensibility and interoperability: if iCal and PoCo
use different approaches, the PoCo one should be choosen to my mind
(as it deals with the same class data).

And for sure, attribute value dividers should be SPACES only, as it is
de-facto standard of the industry. No commas! And why "tel." is shown
there? Value should be value only without any other data bits.

So, wrong one:

Right one:
<tel type="cell voice video text">+1-418-262-6501</tel>

To simplify parsing, phone prefixes (country codes, ext. numbers, etc)
should be also separated from the phone numbers.

Regards,

Zahhar Kirillov
Baltic IT Solutions OÜ
Nodi.ee: kingitused ja disainesemed, e-pood

Tel.: 5650 2282 / Skype: zahharkirillov
[email-masked] / http://nodi.ee

2009/4/29 Cyrus Daboo <[email-masked]>:
> too. But I think it is critical that both specs take the same approach given
> how their "normal" data formats are so close.
>
> --
> Cyrus Daboo
>

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 12:32:17 -0400

Cyrus Daboo wrote, on 29/04/09 12:12 PM:
> There will be an iCalendar-in-XML spec published in the next few days
> that does parameters-as-elements. We went through all the arguments and
> Joseph described in his reply were relevant).

Is this in the archives somewhere? I searched but didn't find anything.

> Whether the XML looks
> "silly" or not to a human really isn't the point - its what makes more
> sense to the kinds of manipulations that you want to do with the XML.

By "silly" I did not mean a judgement of aesthetics.

I meant a judgement based on the technical merits of the syntax.

e.g. It generates a tree that is too deep for our needs and which is more
complicated to use.

> Of course consensus needs to be achieved on the iCalendar spec within
> IETF too. But I think it is critical that both specs take the same
> approach given how their "normal" data formats are so close.

+1

Simon

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 12:34:53 -0400

Cyrus Daboo wrote, on 29/04/09 12:18 PM:
> Having an element for each value type makes things much clearer as to
> what is being dealt with rather than having an attribute determine what
> the value is in the element. For consistency of transformation we felt
> that even the properties only defined to support one value type should
> still encapsulate that value in the corresponding element.

Good point. I struggled with that too and picked one option, but I see value in
the other. Take a look at the <key> element in the two examples, you'll see the
two possibilities.

Simon

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 12:38:02 -0400

Zahhar Kirillov wrote, on 29/04/09 12:23 PM:
> And why "tel." is shown

The value for TEL is a URI. The tel: part is the URI scheme. In the
parameters-as-elements proposal you'll see that it is enclosed in a <uri> element.

> should be also separated from the phone numbers.

The URI is opaque to vCard. It really is up to the tel URI parser.

Simon

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 29 Apr 2009 12:46:55 -0400

Hi Zahhar,

> <tel type="cell voice video text">+1-418-262-6501</tel>

So here is the problem: vcard uses comma separators. What if a new vcard 
type was defined with the name "mobile phone" - that would be perfectly 
legitimate according to vcard, but the space would have to be mapped to 
something else in the XML. Having to special case that would be a pain. 
Forcing a new restriction on vcard is also inappropriate. Hence my 
preference for parameters-as-elements because that very easily takes care 
of multi-valued parameters.

-- 
Cyrus Daboo

---

From: Simon Perreault <[email-masked]>
Date: Wed, 29 Apr 2009 12:51:29 -0400

Cyrus Daboo wrote, on 29/04/09 12:46 PM:
> legitimate according to vcard

Actually that wouldn't be valid. A type value must be an iana-token or x-name.
Here's the ABNF:

  iana-token = 1*(ALPHA / DIGIT / "-")
    ; identifier registered with IANA

  x-name = "x-" 1*(ALPHA / DIGIT / "-")
    ; Names that begin with "x-" or "X-" are
    ; reserved for experimental use, not intended for released
    ; products, or for use in bilateral agreements.

Simon

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 29 Apr 2009 13:01:58 -0400

Hi Simon,

--On April 29, 2009 12:51:29 PM -0400 Simon Perreault 
<[email-masked]> wrote:

> Actually that wouldn't be valid. A type value must be an iana-token or
> x-name. Here's the ABNF:
>

OK, missed that sorry. But in general there is nothing that says a new 
parameter can't have spaces in its value and be multi-valued.

Speaking of which, in the current -06 draft section 6, iana-param and 
x-param are mentioned in the last sentence but not defined anywhere.

-- 
Cyrus Daboo

---

From: Joseph Smarr <[email-masked]>
Date: Wed, 29 Apr 2009 10:51:20 -0700

IMO, the whole point of an XML serialization of vCard is so that consumers
*don't* have to do any special parsing of the wire format (they way they do
for traditional vCard syntax). So any multi-param-value encoding that
requires additional string parsing runs counter to the goals of this
project, and is unnecessary and annoying. And given that you might expect to
have mutiple param values, I think that argues strongly for sub-elements
instead of attributes in XML. That's how XML is designed, and trying to
shoe-horn multiple values into a comma/space-sparated value is abusing XML
and its intended use. :)

Thanks, js

On Wed, Apr 29, 2009 at 10:01 AM, Cyrus Daboo <[email-masked]> wrote:

> Hi Simon,
>
> --On April 29, 2009 12:51:29 PM -0400 Simon Perreault <
> [email-masked]> wrote:
>