Subject: [VCARDDAV] seeking consensus on KIND

From: Peter Saint-Andre <[email-masked]>
Date: Tue, 15 Mar 2011 21:27:18 -0600

<hat type='AD'/>

Folks, we need to finish the vcard4 core spec.

I've reviewed draft-ietf-vcarddav-vcardrev-16 and I think it closes all
of the issues that were raised on this list over the last few months.

As our long-suffering document editor has noted, there is one exception:
the KIND property.

Late last week I reviewed the December discussion thread about KIND.
Based on that reading, I see three possible ways forward (in order from
least invasive to most invasive with regard to the core spec):

1. Leave "KIND:group", "KIND:location", and "KIND:org" in the core but
define them more carefully and completely.

2. Define "KIND:individual" in the core but move "KIND:group",
"KIND:location", and "KIND:org" to extension documents.

3. Remove the KIND property entirely.

It seems to me that #3 is a non-starter, because the WG has had
consensus to include the KIND property since before the core spec was
accepted as a WG item (draft-resnick-vcarddav-vcardrev-01, published
February 4, 2008).

I would agree with those who argue that "KIND:group", "KIND:location",
and "KIND:org" are underspecified in the core spec, because all we have
in Section 6.1.4 is this:

      The value may be one of: "individual" for a single
      person, "group" for a group, "org" for an organization,
      "location" for a named geographical place, an x-name or
      an iana-token.

Whether we move those values of the KIND property to extension specs or
keep them in the core, they need to be specified more carefully and
completely. Therefore I ask for a volunteer to post text to the list
that describes these values in more detail.

Once that is done, we can decide whether the proposed text belongs in
the core spec or in extension specs. (Naturally, discussion of that
topic is welcome before text is posted.)

I would like to make two related points:

a. I think the text in Section 6.1.4 needs to be adjusted regarding the
default value. It currently says the following about the KIND property:

   If this property is absent, "individual" MUST be assumed as default.

I think it would be more accurate to say:

   If this property is absent or an application does not understand the
   provided value (e.g., an x-name or an iana-token), then a value of
   "individual" MUST be assumed (i.e., "individual" is the default).

My reasoning is that we can't expect an application that supports the
KIND property to understand all possible values of the property (even
x-names and iana-tokens).

b. The spec is unclear about which values MUST be understood by an
implementation that supports the KIND property. Does it need to
understand all values defined in the core spec? Only "individual"? This
needs to be clarified (and might be a consideration in deciding whether
values other than "individual" belong in the core spec).

Let's get this done!

Peter

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

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 02:12:36 -0400

> 3. Remove the KIND property entirely.

I wasn't sure about KIND:thing, and I'm still ambivalent about its
removal (I mostly approve), but I think the remaining KINDs should
stay, and should stay in the base spec.

> and "KIND:org" are underspecified in the core spec

I'm not as sure -- see below: when I tried to write something better,
I had a hard time.  We do rather know what they mean, even if it's
hard to put it into specification language.  But I've made a stab.

> that describes these values in more detail.

I've done so below; consider it a starting point that we can
wordsmith.  Simon, if you want the XML for the fragment below, send me
private email.

>   "individual" MUST be assumed (i.e., "individual" is the default).

I didn't quite like that, but I've said something like it in my
proposed re-write.  See what you think.

> values other than "individual" belong in the core spec).

I don't think it's unclear, but I think my rewritten version is quite specific.

Barry

----------------------------------------------------------------
6.1.4.  KIND

   Purpose:  To specify the kind of object the vCard represents.

   Value type:  A single text value.

   Cardinality:  *1

   Special notes:  The value may be one of the following:

       *   "individual", for a vCard representing a single person or
           entity.  This is the default kind of vCard.

       *   "group", for a vCard representing a group of persons or
           entities.  The group's member entities can be other vCards or
           other types of entities, such as email addresses or web
           sites.  A group vCard will usually contain MEMBER properties
           to specify the members of the group, but it is not required
           to.  A group vCard without MEMBER properties can be
           considered an abstract grouping, or one whose members are
           known empirically (perhaps "IETF Participants" or "Republican
           U.S. Senators").

       *   "org", for a vCard representing an organization.  An
           organization vCard will not (in fact, MUST NOT) contain
           MEMBER properties, and so these are something of a cross
           between "individual" and "group".  An organization is a
           single entity, but not a person.  It might represent a
           business or government, a department or division within a
           business or government, a club, an association, or the like.

       *   "location", for a named geographical place.  A location vCard
           will usually contain a GEO property, but it is not required
           to.  A location vCard without a GEO property can be
           considered an abstract location, or one whose definition is
           known empirically (perhaps "New England" or "The Seashore").

       *   An x-name. vCards MAY include private or experimental values
           for KIND.  Remember that x-name values are not intended for
           general use, and are unlikely to interoperate.

       *   An iana-token.  Additional values may be registered with IANA
           (see Section 10.3.4).  A new value's specification document
           MUST specify which properties make sense for that new kind of
           vCard, and which do not.

       Implementations MUST support the specific string values defined
       above.  If this property is absent, "individual" MUST be assumed
       as the default.  If this property is present but the
       implementation does not understand its value (the value is an
       x-name or iana-token that the implementation does not support),
       the implementation SHOULD act in a neutral way, which usually
       means treating the vCard as though its kind were "individual".
       The presence of MEMBER properties MAY, however, be taken as an
       indication that the unknown kind is an extension of "group".

[ABNF and Examples unchanged; feel free to add examples.]
----------------------------------------------------------------

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 16 Mar 2011 10:24:56 -0500

Hi Barry,

Peter had asked me to expand on the definition, but it looks like you beat 
me to it - thanks. Some comments:

1) I want to add one other "dimension" to this - which relates directly to 
how clients actually use kind today. Many contact clients make a UI 
distinction between these different "kinds" by using icons, or segregating 
each kind into its own UI pane etc. For example clients will use an outline 
of a single person to represent an "individual", an outline of multiple 
people to represent a "group" and an outline of buildings for "org". So 
perhaps the following could be added to you text:

    Clients often need to visually distinguish contacts based on what they
    represent, and the KIND property provides a direct way for them to do
    so. For example, when displaying contacts in a list an icon could be
    displayed next to each one: clients might use an outline of a single
    person to represent an "individual", an outline of multiple people to
    represent a "group", an outline of buildings for "org", an outline of
    the globe for "location".

2) For "group" I think we should clarify that any properties other than 
MEMBER refer to the group as a whole. e.g., an EMAIL property value might 
be the address of a mailing list associated with the group, or IMPP might 
refer to a group chat room.

3) "location" - I would be willing to have this definition and the one for 
"thing" punted to the calendar resource schema draft: 
<http://tools.ietf.org/html/draft-cal-resource-schema-03> -at the very 
least that draft is going to want to define "thing" or "resource" to match 
the scheduling expectations.

Comment for Simon:

4) There are a number of places where we use the term "individual" as in 
"individual associated with the vCard", or "individual or resource ...", 
where in actual fact it refers to any "KIND" of vCard. In those cases it 
would be better to replace "individual" with, say, "entity". Here are some 
that I found:

  - Section 6.2: "person or resource" -> "entity"
  - Section 6.4.4 "individual" - "entity"
  - Section 6.6.6 "individual" - "entity" (x2), "individual or resource" -> 
"entity", "person" -> "entity"
  - Section 6.7.6 "individual or resource" -> "entity"
  - Section 10.2.6 "individual" -> "entity" (x2)

-- 
Cyrus Daboo

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 10:50:35 -0400

>   the globe for "location".

Sure, that makes sense; I'll add that to my fragment.

This highlights, though, the importance of the advice on what to do
about an unsupported KIND (x-name or iana-token).  Peter suggested
treating it as "individual", and my text advises "neutral" treatment.
It'll need some thought by the client implementors, and this spec
shouldn't tell them what to do, but I can see that if you use icons
you might want, say, a big "?" icon for the unknown ones, but if you
segregate them into UI panes you might want to put these with the
individuals.  So they're kind of both fish and fowl, as it were.

I'll come up with some proposed text.

> MEMBER refer to the group as a whole. e.g., an EMAIL property value might be
> the address of a mailing list associated with the group, or IMPP might refer
> to a group chat room.

Yes, a good idea.  I'll add that.

> <http://tools.ietf.org/html/draft-cal-resource-schema-03> -at the very least
> that draft is going to want to define "thing" or "resource" to match the
> scheduling expectations.

I would rather keep it.  It's handy to be able to have, say an
organization vCard for "Huawei U.S.", and location vCards for
"Huawei's Dallas office" and "Huawei's Santa Clara office".  The last
two provide distinct anchors for geo URIs for the offices.  I think
this is reasonable base functionality.

I won't fight very hard for this, if there's a swell of desire to move
it out.  But keeping it's my (fairly strong) preference.

Barry

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 15:02:53 +0000

> define them more carefully and completely.

+1 - The hCard microformat distinguishes person/ vs organisation (or
location) , and mirroring them in vCard will ensure that there is no
round-trip data loss.

-- 
Andy Mabbett
@pigsonthewing
http://pigsonthewing.org.uk

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 15:15:09 +0000

On 16 March 2011 06:12, Barry Leiba <[email-masked]> wrote:

>> I ask for a volunteer to post text to the list
> wordsmith.

>           entity.  This is the default kind of vCard.

My draft, before I read yours, was:

"A named person (e.g. Sir Tim Berners-Lee); or a role undertaken by a
single person whose name is not known (examples Chairman,  editor,
occupant)"

>           known empirically (perhaps "IETF Participants" or "Republican

"A set to which one or more individual, org or group belong, but which
is not formally an organisation (examples: the Mabbett family, people
who cycle")

How does this differ from CATEGORY?

>           business or government, a club, an association, or the like.

"A company, team, band or other collective (examples: British Airways,
Boston Red Sox, Pink Floyd, the W3C)"

>           known empirically (perhaps "New England" or "The Seashore").

"A named geographical place, venue/ building or settlement (examples:
Yellowstone Park, The Albert Hall, Paris)"

[...]

I also recall that a "mailing list" type was wanted, so that such
addresses do not appear in certain auto-complete fields. Is that still
the case?

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 11:29:37 -0400

Second iteration, after incorporating Cyrus's comments:

           All properties in a group vCard apply to the group as a
           whole, and not to any particular MEMBER.  For example, an
           EMAIL property might specify the address of a mailing list
           associated with the group, and an IMPP property might refer
           to a group chat room.

           All properties in an organization vCard apply to the
           organization as a whole, as is the case with a group vCard.
           For example, an EMAIL property might specify the address of a
           contact point for the organization.

           All properties in an location vCard apply to the location
           itself, and not with any entity that might exist at that
           location.  For example, in a vCard for an office building, an
           ADR property might give the mailing address for the building,
           and a TEL property might specify the telephone number of the
           receptionist.

       Clients often need to visually distinguish contacts based on what
       they represent, and the KIND property provides a direct way for
       them to do so.  For example, when displaying contacts in a list,
       an icon could be displayed next to each one; a client might use
       an outline of a single person to represent an "individual", an
       outline of multiple people to represent a "group", an outline of
       buildings for "org", and an outline of the globe for "location".
       Alternatively, or in addition, a client might choose to segregate
       different kinds of vCards to different panes, tabs, or selections
       in the user interface.

       When designing those sorts of visual distinctions, client
       implementations have to decide how to fit unsupported kinds into
       the scheme.  What icon is used for them?  The one for
       "individual"?  A unique one, such as an icon of a question-mark?
       Which tab do they go into?  It is beyond the scope of this
       specification to answer these questions, but these are things
       implementors need to consider.
----------------------------------------------------------------

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 15:40:49 +0000

>       buildings for "org", and an outline of the globe for "location".

I'm wary of suggesting a building icon for an ORG, when buildings
might be best represented by TYPE:LOCATION

>       different kinds of vCards to different panes, tabs, or selections

[continue] ...and might treat vCards of different TYPE in different
ways, such reminding users of Individuals' birthdays, but not those
for ORGs.

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 16 Mar 2011 11:51:06 -0500

Hi Andy,

> addresses do not appear in certain auto-complete fields. Is that still

In my case I actually want to be able to auto-complete mailing list 
addresses (e.g. type in "vcard" and have the auto-complete list include the 
vcarddav mailing list as one option).

In reality this is a more complicated problem because different types of 
clients are likely going to want to "filter" vCards for auto-complete in 
different ways (e.g. email client would likely always exclude locations, 
but calendar clients may want those).

Now in CalConnect when we were discussing the calendar resource schema work 
(<http://tools.ietf.org/html/draft-cal-resource-schema-03>) we had actually 
discussed the possibility of adding further granularity to the KIND 
property via a parameter, e.g.:

KIND;detail=projector:thing
KIND;detail=convention-center:location
KIND;detail=hotel:location
KIND;detail=bar,restaurant:location

Those types could come from a registry such as the one defined by 
<http://tools.ietf.org/html/rfc4589> for locations. With that extra level 
of granularity clients can make smarter decisions about "filtering" vCards 
during auto-completes, CardDAV searches etc

However, I believe this extra level of granularity is best left for an 
extension - not the base.

-- 
Cyrus Daboo

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 11:51:52 -0400

> might be best represented by TYPE:LOCATION

I don't understand.  TYPE isn't a property that applies to a vCard;
it's a parameter that applies to a property.  And there's no
"TYPE:LOCATION" parameter defined for any properties in the base spec.

The only thing that specifies the "type" of the vCard is the KIND
property.  A vCard doesn't have a TYPE.

Barry

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 11:57:06 -0400

> discussed the possibility of adding further granularity to the KIND property
> via a parameter, e.g.:
>
> <http://tools.ietf.org/html/rfc4589> for locations. With that extra level of
> granularity clients can make smarter decisions about "filtering" vCards

I fully agree.  I like the idea, but, while I want to keep
"KIND:location" in the base spec, I'd much rather put this sort of
extension into an extension, if I may speak redundantly.

Barry

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 16 Mar 2011 09:57:08 -0600

> property.  A vCard doesn't have a TYPE.

Perhaps Andy meant "KIND:location".

Peter

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

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Mar 2011 11:58:56 -0400

> Perhaps Andy meant "KIND:location".

Ah.  Duh.  Sorry; that was dense of me.
That's the problem when we define specific terms, and then don't use
them precisely.  Con-FU-sion.

Barry

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 16:11:04 +0000

> different ways (e.g. email client would likely always exclude locations, but
> calendar clients may want those).

Accepted.

> KIND;detail=bar,restaurant:location

Again, this sounds very similar to CATEGORY.

> extension - not the base.

But CATEGORY is in the base, is it not?

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 16:12:06 +0000

> Perhaps Andy meant "KIND:location".

Yes; apologies.

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 16 Mar 2011 12:39:27 -0500

Hi Andy,

> But CATEGORY is in the base, is it not?

Except that CATEGORIES has "free-form" unregistered values, whereas in this 
case we want to use specific registered ones. Now, I am not saying that we 
can't use CATEGORIES for this - but that debate should be left for the 
extension and not be part of the base spec discussion.

-- 
Cyrus Daboo

---

From: Mike Douglass <[email-masked]>
Date: Wed, 16 Mar 2011 12:55:28 -0400

And that's the core of the issue: I don't want to import a vcard and 
suddenly find it's inserted itself into a group.

Groups match constructs that already exist and we use widely, ldap 
groups for one which represent departments.

As we expose our directory system through vcard I need a specific kind 
of vcard to represent those groups.

The need for this was recognised years back at the vcard workshop.

On 03/16/2011 01:39 PM, Cyrus Daboo wrote:
> Except that CATEGORIES has "free-form" unregistered values, whereas in 
> this case we want to use specific registered ones. Now, I am not 
> saying that we can't use CATEGORIES for this - but that debate should 
> be left for the extension and not be part of the base spec discussion.
>

-- 

Mike Douglass                           [email-masked]
Senior Systems Programmer
Communication&  Collaboration Technologies      518 276 6780(voice) 2809
(fax)
Rensselaer Polytechnic Institute 110 8th Street, Troy, NY 12180

---

From: Andy Mabbett <[email-masked]>
Date: Wed, 16 Mar 2011 17:03:47 +0000

> extension and not be part of the base spec discussion.

OK; that makes sense, Thanks for the clarification.

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 17 Mar 2011 13:49:57 -0600

With my AD hat still firmly planted...

> define them more carefully and completely.

So far my sense is that we are converging on option #1. Convergence is
good. :)

Many thanks to Barry Leiba for proposing text and quickly revising it to
incorporate feedback:

http://www.ietf.org/mail-archive/web/vcarddav/current/msg02090.html

We have a little more than 2 weeks before the VCARDDAV WG session at
IETF 80. Folks are going to be really busy during IETF week, and many
will be travelling to Prague late next week, so please send in your
feedback as soon as you can.

Thanks!

Peter

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

---

From: Joseph Smarr <[email-masked]>
Date: Thu, 17 Mar 2011 13:23:40 -0700

I still think KIND:GROUP is an "ugly hack" that shouldn't be part of the
official vCard standard and that will harm backwards-compatibility and
complicate implementations in practice. I would vote to only specify KIND
values that serve as "FYI category values" on normal existing contacts (e.g.
to decorate with special icons or provide filtering options), but NOT any
KIND values that introduce new semantics and jam in non-contact data (since
any unaware implementations will then be doing the wrong thing by ignoring
it).

Specifically, my understanding is (please correct me if I'm wrong): Cyrus et
al needed a way of storing additional metadata about contact groups in
Apple's address book, but they didn't have a good place to stick that data,
so they decided to make "contacts" for each group where the "contact fields"
are the group meta-data, and they decorate them with KIND:GROUP so they can
pull them out and apply them as group meta-data and not show them to the end
user.

That may be a necessary (or even fine) implementation choice for a specific
address book, but IMO it's a poor choice for an official standard. It's a
form of "overloading" in that in mashes together actual contacts and extra
non-contact meta-data that looks like contacts unless you pay close
attention to something just introduced in the latest rev of vCard. In
practice, I'm quite confident these "group contacts" will end up showing up
in people's address books like actual contacts (because not all clients,
servers, sync protocols, etc. will know to hide them) and then users will
either end up with polluted address books, or worse they'll delete this
"garbage" and it will mess up their group info. It's always dangerous to
overload data, and it's even more dangerous to overload it in a way that
does the wrong thing "by default" to clients that weren't expecting this
overloading. Yet that's exactly what we're doing here. And I think
it's unprincipled and will get us into trouble.

It's also confusing for developers, since groups ARE such a common feature
of address books, and yet they're being "jammed in" to the spec in this odd
and unintuitive way. Why not define a separate BEGIN:VGROUP for instance and
put metadata in there, and then provide some way to annotate each contact
with which VRGOUP ID(s) it belongs to? I'm sure there are plenty of decent
ways we can implement this important feature, but I don't like the current
approach, either in theory or in practice.

Tantek/Kevin/Rohit-I remember you having similar feelings on this subject,
so I'd encourage you to chime in before it gets set in stone here.

Thanks,js

On Thu, Mar 17, 2011 at 12:49 PM, Peter Saint-Andre <[email-masked]>wrote:

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

---

From: Andy Mabbett <[email-masked]>
Date: Thu, 17 Mar 2011 20:31:06 +0000

> http://www.ietf.org/mail-archive/web/vcarddav/current/msg02090.html

I think that pre-dates the comments I made earlier in this thread; I
think it would be helpful to future readers to add at least some of
the clarifications and examples contained in them.

(Note that I'm not suggesting my draft wording be adapted wholesale.)