Subject: [Jcardcal] Structured property values

From: Michael Angstadt <[email-masked]>
Date: Sun, 24 Mar 2013 19:52:13 -0400

Thanks for creating the Etherpad document, Philipp.  After looking it
over, there seems to be some uncertainty with regards to how
structured property values should be represented in both jCard and
jCal.  It appears that the question can be divided up into 3
sub-questions:

(1) Representation of entire value:
    (1a) ["adr", {}, "text", ";;Mystreet 1;Hamburg;;22523;Germany" ]
    (1b) ["adr", {}, "text", "", "", "Mystreet 1", "Hamburg", "",
"22523", "Germany" ]
    (1c) ["adr", {}, "text", ["", "", "Mystreet 1", "Hamburg", "",
"22523", "Germany"] ]
    (1d) ["adr", {}, "text", { "street": "Mystreet 1", "city":
"Hamburg", "postcode": "22523", "country": "Germany" } ]
(2) Empty components:
    (2a) ["adr", {}, "text", null, null, "Mystreet 1", ... ]
    (2b) ["adr", {}, "text", "", "", "Mystreet 1", ... ]
(3) Multi-valued components:
    (3a) ["adr", {}, "text", "", "a,b,c", "Mystreet 1", ... ]
    (3b) ["adr", {}, "text", "", ["a", "b", "c"], "Mystreet 1", ... ]

I think (1b-2b-3b) is the best approach.

(1a) and (3a) add complexity, since escaped semi-colon and comma
characters must be taken into account.

(1c) wraps the value in an array, which I don't see as adding any
benefit.  This does distinguish the structured property from a
multi-valued property (like CATEGORIES), but I'm not sure what benefit
this has.

Maybe the spec could allow for both (2a) and (2b) to be used, since
they are so similar.  Allowing both would make it easier to create
jCards/jCals, since it's one less thing to worry about.

Would be interested in hearing what the group thinks. :)

Thanks,
-Mike
http://code.google.com/p/ez-vcard

---

From: Philipp Kewisch <[email-masked]>
Date: Mon, 25 Mar 2013 09:50:15 +0100

I know the b-proposal is my favorite, but let me tell you about the
downsides: As you mentioned, it is the same construct for properties
with multiple values, i.e compare:

["categories", {}, "text", "work", "play"]

["adr", {}, "text", "", "", "Mystreet 1", "Hamburg", ""]

A naive parser might not know the difference between the "adr" and
"categories" property. This would mean special casing is required for
every structured value.

This is even more true for  properties that are unknown, i.e added in an
extension:

["frobnicator", {}, "text", "work", "play"] // Lets say this is multi-valued
["twiddle", {}, "text", "", "", "Mystreet 1", "Hamburg", ""] // ... and
this is structured

FROBNICATOR;VALUE=TEXT:work,play
TWIDDLE;VALUE=TEXT:,,Mystreet 1,Hamburg,,

If we use the array-based value, then we could mandate that semicolons
will always be used in that case:

["frobnicator", {}, "text", "work", "play"]
["twiddle", {}, "text", ["", "", "Mystreet 1", "Hamburg", ""]]

FROBNICATOR;VALUE=TEXT:work,play
TWIDDLE;VALUE=TEXT:;;Mystreet 1;Hamburg;;

>From the jCal perspective, my arguments for b would be that the number
of properties handled this way are low in number anyway so its totally
fine to special case here. Also this means one less JS object for such
properties, which is better for perf. It saves the implementer from
checking the value type of either being an array or a text value, older
browsers don't have a builtin method for this.

I'm pretty much on the fence with this decision, I've brought this up so
many times within calconnect that others are probably annoyed. I'd be
happy to hear other folks thoughts on this too.

I would decide for one or the other to keep the spec clear, otherwise
implementers will have to battle with others doing it differently.

Philipp

---

From: Simon Perreault <[email-masked]>
Date: Mon, 25 Mar 2013 10:43:10 +0100

> TWIDDLE;VALUE=TEXT:;;Mystreet 1;Hamburg;;

Yes, this is important, and the solution is good.

However, there's another piece missing: each component can be a list of 
values (see e.g., ADR). So we need an array of arrays. Maybe a string 
can be used directly instead of an array containing a single string.

> happy to hear other folks thoughts on this too.

We need to do something. The current text is not good, for this reason: 
a user agent needs to implement special processing for component-valued 
properties, so it needs to know all properties that are 
component-valued. This does not work well with extensibility, as you 
highlighted.

Simon

---

From: Philipp Kewisch <[email-masked]>
Date: Mon, 25 Mar 2013 11:35:41 +0100

On 3/25/13 10:43 AM, Simon Perreault wrote:
> However, there's another piece missing: each component can be a list
> of values (see e.g., ADR). So we need an array of arrays. Maybe a
> string can be used directly instead of an array containing a single
> string.
You read the part on the etherpad at "Also need to decide how to handle
multi-value elements inside a structured value:" right?

Similar to how I've handled it with parameters, I agree that a string
should be used if there is only one value. For parameters I've used this
wording: "Single-value parameters SHOULD be represented using a single
string value, but an array with one element MAY also be used."

Philipp

---

From: Simon Perreault <[email-masked]>
Date: Mon, 25 Mar 2013 11:52:31 +0100

> multi-value elements inside a structured value:" right?

No, but now that I did I think we're in full agreement.

> string value, but an array with one element MAY also be used."

+1

Simon

---

From: Evert Pot <[email-masked]>
Date: Mon, 25 Mar 2013 11:58:01 +0000

On Mar 25, 2013, at 8:50 AM, Philipp Kewisch <[email-masked]> wrote:

> I know the b-proposal is my favorite, but let me tell you about the downsides: As you mentioned, it is the same construct for properties with multiple values, i.e compare:
> 
> A naive parser might not know the difference between the "adr" and "categories" property. This would mean special casing is required for every structured value.
> 
> This is even more true for  properties that are unknown, i.e added in an extension:
> 
> ["twiddle", {}, "text", "", "", "Mystreet 1", "Hamburg", ""] // ... and this is structured 
> 
> If we use the array-based value, then we could mandate that semicolons will always be used in that case:
> 
> From the jCal perspective, my arguments for b would be that the number of properties handled this way are low in number anyway so its totally fine to special case here. Also this means one less JS object for such properties, which is better for perf. It saves the implementer from checking the value type of either being an array or a text value, older browsers don't have a builtin method for this.
> 
> I'm pretty much on the fence with this decision, I've brought this up so many times within calconnect that others are probably annoyed. I'd be happy to hear other folks thoughts on this too.
> 
> I would decide for one or the other to keep the spec clear, otherwise implementers will have to battle with others doing it differently.

For what it's worth. I maintain a PHP library[1] that deals with parsing iCalendar and vCard objects.

It has a pretty major design flaw regarding value-typing handling and multiple values, so I recently started planning third version of this lib fixing this, and also paving the way that will make it easy to generate xCal / xCard and jCard / jCal.

I will treat every property and parameter value as if they may contain either 1 or more values. Any value may be represented as either strings or arrays.

Over:

> ["twiddle", {}, "text", "", "", "Mystreet 1", "Hamburg", ""]

The former will be slightly easier to parse. It's true that the latter is one array less, but in my case I need that array anyway, so I need to create it myself by slicing the array. So the former syntax will save me some memory and cpu time.

That said, I don't feel very strongly about it.. as long as it's not 1a.

I also slightly prefer the encoding empty values as "" over null. There's some benefits over null values. It's often slightly cheaper, and allows us to distinguish between a not-specified value and literal empty string. But neither the xml representation nor the mimedir representation has this concept, and most clients treat the empty string already as a missing value.

So for me: 1c, 2b.

As for #3. I couldn't find any reference to multi-valued components in the vcard spec. Is there language that specifically describes this, or is this a newly introduced here. If the vCard spec does not define multiple-valued components, I'd also strongly advocate against it here.. if I missed it, can someone hook me up with a link? :)

  [1]: https://github.com/evert/sabre-vobject

Evert

---

From: Simon Perreault <[email-masked]>
Date: Mon, 25 Mar 2013 13:37:30 +0100

Le 2013-03-25 12:58, Evert Pot a écrit :
> I also slightly prefer the encoding empty values as "" over null.
> There's some benefits over null values. It's often slightly cheaper,
> and allows us to distinguish between a not-specified value and
> literal empty string. But neither the xml representation nor the
> mimedir representation has this concept, and most clients treat the
> empty string already as a missing value.

Yes, and I'll go further: the text should explicitly say that null MUST 
NOT be used.

> As for #3. I couldn't find any reference to multi-valued components
> in the vcard spec.

 From section "6.3.1. ADR":

       Where it makes semantic sense, individual text
       components can include multiple text values (e.g., a "street"
       component with multiple lines) separated by the COMMA character
       (U+002C).

Simon

---

From: Evert Pot <[email-masked]>
Date: Mon, 25 Mar 2013 14:09:47 +0000

On Mar 25, 2013, at 12:37 PM, Simon Perreault <[email-masked]> wrote:

> Yes, and I'll go further: the text should explicitly say that null MUST NOT be used.
> 

I missed that, thank you.

Cheers,
Evert

---

From: Michael Angstadt <[email-masked]>
Date: Mon, 25 Mar 2013 11:42:14 -0400

On Mon, Mar 25, 2013 at 7:58 AM, Evert Pot <[email-masked]> wrote:
> As for #3. I couldn't find any reference to multi-valued components in the vcard spec. Is there language that specifically describes this, or is this a newly introduced here.

N also supports multi-valued components.

>From section 6.2.2:

      Individual text components can include multiple text values
      separated by the COMMA character (U+002C).

-Mike

---

From: Philipp Kewisch <[email-masked]>
Date: Wed, 27 Mar 2013 14:48:47 +0100

Hello Folks,

This is my first shot at WG work, so please correct me if I am doing
something out of procedure. I'd like to call for a final round of
possible objections before I make changes to the structured property
values text in the draft. From discussion here, these are the final results:

- Proposal A for Structured Property Values: ["adr", {}, "text", ["",
"", "Mystreet 1", "Hamburg", "", "22523", "Germany"] ]
- Proposal II for multi-valued structured property values: ["adr", {},
"text", ["", "", ["Mystreet", "right side", "third light"], "Hamburg",
... ] ]

Michael, I've taken your non-reply as consent, please shout if you still
think a different proposal makes more sense.

If there are no objections by Saturday, I'm going to modify the text and
upload a new version of the draft.

Thanks,
Philipp

---

From: Simon Perreault <[email-masked]>
Date: Wed, 27 Mar 2013 16:19:00 +0100

I agree with the proposal below.

Simon

Le 2013-03-27 14:48, Philipp Kewisch a écrit :
> _______________________________________________
> jcardcal mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/jcardcal
>

---

From: Michael Angstadt <[email-masked]>
Date: Wed, 27 Mar 2013 11:53:22 -0400

Will this draft update include whether null or empty-string should be
used for empty values?

Thanks,
Mike

On Wed, Mar 27, 2013 at 9:48 AM, Philipp Kewisch <[email-masked]> wrote:
> something out of procedure. I'd like to call for a final round of possible
> objections before I make changes to the structured property values text in
> the draft. From discussion here, these are the final results:
>
> - Proposal A for Structured Property Values: ["adr", {}, "text", ["", "",
> "Mystreet 1", "Hamburg", "", "22523", "Germany"] ]
> "text", ["", "", ["Mystreet", "right side", "third light"], "Hamburg", ... ]
> ]
>

---

From: Philipp Kewisch <[email-masked]>
Date: Wed, 27 Mar 2013 17:02:25 +0100

Yes, I will go with empty value for this.

Thanks,
Philipp

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 27 Mar 2013 10:14:35 -0600

On 3/27/13 7:48 AM, Philipp Kewisch wrote:
> Hello Folks,
> 
> This is my first shot at WG work, so please correct me if I am
> doing something out of procedure.

You're doing fine so far! :-)

Peter

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

---

From: Michael Angstadt <[email-masked]>
Date: Wed, 27 Mar 2013 12:24:46 -0400

Ok +1