vcard-notes.html 20.3 KB

Raw Blame History Permalink

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="generator" content=
  "HTML Tidy for Mac OS X (vers 1st December 2004), see www.w3.org" />
  <meta http-equiv="content-type" content=
  "text/html; charset=us-ascii" />

  <title>Notes on the vCard format</title>
  <link rel="stylesheet" href="/People/Berners-Lee/general.css"
  type="text/css" /><!-- Changed by: tbl 19990524 -->
</head>

<body>
  <p><a href="../"><img alt="W3" border="0" src=
  "/Icons/WWW/w3c_home" width="72" height="48" /></a></p>

  <h1>Notes on vCard, LDIF and mappings to RDF</h1>

<p>$Id: </p>

  <h2>Introduction</h2>
<p>This note discusses a common ontology for the interoperable
interchange of contact information, in the light of
various pieces of software, the standards which they purport
to import nand export, and their interpretations of that software.
</p>
<h2>VCARD</h2>
  <p>Here is an example of contact infromation in vCard.</p>
  <pre>
BEGIN:VCARD
VERSION:3.0
N:Doe;John;;;
FN:John Doe
ORG:Example.com Inc.;
TITLE:Imaginary test person
EMAIL;type=INTERNET;type=WORK;type=pref:johnDoe@example.org
TEL;type=WORK;type=pref:+1 617 555 1212
TEL;type=CELL:+1 781 555 1212
TEL;type=HOME:+1 202 555 1212
TEL;type=WORK:+1 (617) 555-1234
item1.ADR;type=WORK:;;2 Example Avenue;Anytown;NY;01111;USA
item1.X-ABADR:us
item2.ADR;type=HOME;type=pref:;;3 Acacia Avenue;Newtown;MA;02222;USA
item2.X-ABADR:us
NOTE:John Doe has a long and varied history\, being documented on more police files that anyone else. Reports of his death are alas numerous.
item3.URL;type=pref:http\://www.example/com/doe
item3.X-ABLabel:_$!&lt;HomePage&gt;!$_
item4.URL:http\://www.example.com/Joe/foaf.df
item4.X-ABLabel:FOAF
item5.X-ABRELATEDNAMES;type=pref:Jane Doe
item5.X-ABLabel:_$!&lt;Friend&gt;!$_
CATEGORIES:Work,Test group
X-ABUID:5AD380FD-B2DE-4261-BA99-DE1D1DB52FBE\:ABPerson
END:VCARD
</pre>

  <h3>vCard and icalendar</h3>

  <p>These share a basic line syntax style. vCard came first, <a href="rfc2426.html">RFC2426</a> issued
  concurrently with the generic syntax <a href=
  "rfc2425.html">RFC2425</a>. Later came iCaledar, <a href=
  "rfc2426.html">RFC2445</a>, building on but not using all the
  types of vcard and using some new ones. Therefore an iCal parser
  will not necessarily parse a vCard.</p>

  <h4>Only in vCard</h4>

  <ul>
    <li>Groups (in base)</li>
  </ul>

  <h4>Only in iCalendr</h4>

  <ul>
    <li>Recurrence rules (added)</li>

    <li>DateTimes (in base)</li>
  </ul>

  <p>etc</p>

  <h2>Issues with vCard</h2>

  <h3>Escaping</h3>

  <p>The following escaping is done.</p>

  <ul>
    <li>Newlines within feilds within a line are escaped as \n
    <strong>or \N</strong></li>

    <li>Colons in a value appear (why?) to be escaped</li>

    <li>Semicolons within a semicolon-delimied thing are
    escaped</li>

    <li>Commas within a comma-delimited thing are escaped.</li>
  </ul>

  <p>(It wasn't clear to me whether theese are at the same level or
  not. This affects whether you have to encode a backslash as \\
  (if there is one level) or as 2^n backslahes if there are n
  levels of escaping applied to the same data. I conclude that it
  is a single level)</p>

  <p>Another question is whether all the escapes are used when a
  given syntax doesn't happen to include any comma delimiting. Yes,
  they are: colons, semicolons, and commas are escaped in all
  values.</p>

  <h3>N-values</h3>

  <p>Rfc2426 in the BNF says:</p>
  <pre>
   n-value      = 0*4(text-value *("," text-value) ";")
                  text-value *("," text-value)
        ; Family; Given; Middle; Prefix; Suffix.
        ; Example: Public;John;Quincy,Adams;Reverend Dr. III
</pre>

  <p>The example in the comment is presumably wrong and should IIUC
  be</p>
  <pre>
        Quincy,Adams;;John;Reverend,Dr.;III
or
        Adams;John;Quincy;Reverend,Dr.;III
</pre>

  <p>There was a discussion on #swig on 2007-01-26 about how to
  represent this in RDF. One compromise is to use spaces to
  separate the comma-separated valeus, to cut down on the
  structure.</p>

  <p>Of course, the whole thing could be represented at lists:</p>
  <pre>
  (("Quincy" "Adams") () ("John") ("Reverend" "Dr.")("III"))
</pre>

  <p>but that isn't so much in the RDF spirit and would take a lot
  of space in RDF/XML. A version with spaces for the multiple
  values</p>
  <pre>
  [ v:familyName "Quincy Adams"; givenName "John"; v:middleName "";
    v:honorificPrefix "Reverend Dr.", v:suffix "III"]
</pre>

  <p>seems to be a compromise. Giving an empty middle name (or
  anything else) would be optional.</p>

  <h3>Modeling issue: Whether to make the name itself a
  concept</h3>

  <p>The n filed in vCard seems to echo the dn (distinguished name)
  field in vcard. The idea f a distinguished name is that it allows
  one to distinguish (indirectly identify) the person involved. In
  x.500 systems, DN's often have organizational names and
  organization units. In Mozilla Thunderbird, the dn is the common
  name and email adddress pair, which is what is sent in email. In
  most cases the email address is personal: FOAF uses it as a
  distinguisher by itself -- it is a nverse functional property. So
  while people may share an email address, it is going to be a
  pathological case in which who people share the common name and
  email adderss pair. (One could imagine a shared family email
  where the father and son have the same common name.)</p>

  <p>Should the name itself be a concept, or should the subfields
  of the name be attributed to the person? In the first case in RDF
  it becomes a bnode. This is quite easy, but makes the data more
  complicated.</p>

  <p>The actual parts of the DN are in FOAF and Thunderbird all
  separate fields anyway. You can't have two different family
  names, titles, suffxies, etc. Suppose we remove the bnode and the
  abstrction of the 'name' as a complex object itself.</p>

  <p>Do people validly have multiple alternative names? Yes, they
  can have in the case of nom de plume, names befroe and after
  acquiring a peerage, and so on. However, none of the contct list
  software I have come across alows one person to have two names.
  One could in AB (and in RDF) use a relation field to specify that
  one name (Persona) is in fact the same person as another. vCards
  would then represent information about personas. These personas
  have names, if we are to be strictly accurate. This would make
  the subject of all these arcs a persona rather than a person. If
  we are not, then we would get a situation where to personas are
  identified as being the same person, and</p>

  <ol>
    <li>Restrict a person to only having one name in the model</li>

    <li>Allow two names for any person</li>

    <li>Change the domain of the name (and vcard in general) to
    persona, restrict the persona to having one name, and allow a
    person to have more than persona.</li>
  </ol>In this case I feel that these are in the order from
  pragmatic to

  <h3>Modeling issue: Whether to make the contact point a
  concept</h3>

  <p>The contact ontology, of all the ontologies cosidered, is the
  only one which allows you to have two workplaces, with an address
  and phone number for each, and hang onto whih goes with which.
  That is because it has a abstraction con:ConcatLocation, or
  perhaps better contactPoint or even Role, which is the thing
  which is labelled 'home' or 'work' typically, or sometimes
  'vacation' or 'emergency'. Of these, home and work outnuber the
  others by far. Some systems allow you just one set of home and
  one set of work details (thunderbird). AB allows you to have
  work, home, other and even to set you own relationships and also
  to have more than one of each. The UI would not be that
  complicated to attach URLs etc to work or home groupings.</p>

  <p>vCard allows groups, and the spec shows them being used in
  exactly this way. However, AB does not use groups in this
  way.</p>

  <a name="adrpic">
<img src="notes/address.png" alt="circles and arrows" />
</a>
<p>
<em>Relations between different properties used to model adresses in
the con: (brown), prooposed vCard RDF (dk. blue), ldif (green) and mozilla-extended LDIF (cyan). </em>

</p>
<p>
In this case, my conclusion is that the generality of modelling the
contact-point as a node in the graph is important.
</p><p>
(It is interesting to ask whether a contact-point has some of the  attributes of
a role, or of a persona mentioned above.  It seems to.  One can imagining
being addresses at a different address, for example, in a role.
(The Hon. Basil Graham, Chair, Happytown Town Council, vs.
Bas Graham, 23 Accacia Avenue, Happytown).
This not, however, what the software we are dealing with supports.
</p>
<p>As multiple workplaces and homes are not uncommon,
The author's conclusion is for a common ontology it is valuable
to model the contact-point.
</p>The argument against modeling the contact point is the complexity
of the user interface for editing.  The user interface for
output is straightforward.<p>
</p><p>
There is considerable tension throughout the ontologies reviewed between
associating things with people, or their work.
</p>
<p>

 </p>
  <h4>Work email?</h4>
  <pre>
EMAIL;type=INTERNET;type=WORK;type=pref:Libby.Miller@bristol.ac.uk
</pre>

  <p>In Apple's address book a type can be WORK, but in the spec, but WORK is not in email-type.
   I
  extended the VCARD spec in the implementation vcard2n3.py to cover this.
  </p>
<p>FOAF just uses a personal mailbox, with the constraint that (no two people
can share it), with no attribution of work or home. If v:work-email and foaf:mailbox
are both subproperties of general email property, but not of each other, then
there ill be limited interoperability.</p>
<p>Many commercial systems seem to make rash assumptions when importing
data, deciding, sometimes under user guideance and sometimess without asking,
whether to decide tha an unknown address is a work or home one.
This addition of random false data can make a database very dirty.
To avoid this, the ontology used for interoperability must have sufficient delicacy
to represent just what is known, no more and no less. users should be in the
loop when it is necessary to classify names and addresses
for input into a particular system.
</p>
<p></p>
<p></p>


  <h3>Group semantics</h3>

  <p>There seem to be two different assumptions about the grouping
  system. In the spec, an example gives the group name some
  semantics.</p>
  <pre>
home.tel;type=fax,voice,msg:+49 3581 123456
home.label:Hufenshlagel 1234\n
</pre>

  <p>but in Apple AB it doesn't, the semantics comes from a type=
  on the address, and phone numbers cannot be attributed to
  specific addresses. (That is an AB bug IMHO).</p>
  <pre>
item1.ADR;type=HOME;type=pref:;;3 Acacia Avenue;Newtown;MA;02222;USA
item1.X-ABADR:us
item2.ADR;type=WORK:;;2 Example Avenue;Anytown;NY;01111;USA
item2.X-ABADR:us
</pre>

<h2>Age-old modeling issue: First/Given/Last/Surname</h2>

<p>It is a fact that some cultures (such as Japan) normally put names in the order
(family, given), and some (like the US) in the order (given, family).
(There are also cultures who don't use either of these simple schemes,
but that is another question.)
It is therefore unreasonable and politically incorrect to assume that
a first name  is a family anme or a given name in general,
except within a local community.
</p>
<p>
In the ontologies and software reviewed, MacAB and Thunderbird both use
"first" and "last" in the user interface.

</p>
<p>
</p>
<p>
</p>
<!--      ///////////////////////////////  -->

  <h2>Apple AddressBook extensions</h2>

  <p>Some extensions noticed in real data from an Apple AddressBook
  (AB)</p>

  <h3>X-ABADR</h3>

  <p>Guessing, as the country name is covered, this field is the
  foratting and editing convention, for example where the potscode
  comes in the address and whether it called a postcode, zipcode
  etc.. In AddressBook program, this is a global preference. I
  don't know whther you can create some cards with a US fromat and
  some with a french format. It would be useful if the format was a
  function of the country.</p>
  <pre>
item1.ADR;type=HOME;type=pref:;;3 Acacia Avenue;Newtown;MA;02222;USA
item1.X-ABADR:us
</pre>

  <h3>X-ABShowAs</h3>

  <p>This is a nice feature. It makes the item sort and sisplay as
  primarily the organization, secondarily the person.</p>
  <pre>
FN:AMC Theatres Burlington Cinema 10
ORG:AMC Theatres Burlington Cinema 10;
item1.ADR;type=WORK;type=pref:;;20 South Avenue;Burlington;MA;01803;
item1.X-ABADR:us
X-ABShowAs:COMPANY
</pre>

  <h3>X-ABLabel</h3>
  <pre>
item3.URL;type=pref:http\://www.robots.ox.ac.uk/~acme/joe.htm
item3.X-ABLabel:_$!&lt;HomePage&gt;!$_
</pre>

  <h3>x-abrelatednames</h3>

  <p>The ABLabel gives the relation, either apple standard in ehich
  case surrounded by weird characters, or else user-generated.
  Apple values in apple-special namespace. User-generated field in
  user-namespace, maybe a parameter to be passed to the translator.
  These are used to override the predicate linking the person and
  the group. It may be that when the group is a 2-item thing, just
  something and label it should be de-reified to a single
  prediate-object statement. This is necessary to be able to use
  homepage for example as an inverse functional property to
  identify people</p>
  <pre>
item1.X-ABRELATEDNAMES;type=pref:Jane Doe
item1.X-ABLabel:_$!&lt;Spouse&gt;!$_
</pre>

  <p>This would be represented in N3, sing a special namespace for
  AB relative names,</p>
  <pre>
   abl:spouse "Jane Doe";
</pre>

  <p>Meanwhile, a different namepscae should be used (per user?)
  for user-generated names. these are more like tags, very
  user-specific.</p>
  <pre>
item1.X-ABRELATEDNAMES;type=pref:Jane Doe
item1.X-ABLabel:coauthor
</pre>

  <p>This would be represented in N3 more like: names,</p>
  <pre>
   user:coathor "Jane Doe";
</pre>

  <h2>Issues with the <cite>Representing vCard Objects in
  RDF/XML</cite></h2>

  <h3>Use of Seq</h3>

  <p>I prefer lists (RDF collections) instead.</p>

  <h3>Property name conventions</h3>

  <p>Good pratice is initial <strong>lower</strong> case on
  property names, as in vcard:family not vcard:Family. Use upper
  case for classes, as in foaf:Person.</p>

  <p>postOfficeBox not post-office-box, or prerably shorter
  <strong>poBox</strong> as these are only codes whose mnemonic
  value is for developres, not users. organization-name is too
  long: orgName, orgUnit would be fine IMHO.</p>

  <h3>Direct mapping</h3>

  <p>v:work-email can be generated from EMAIL:TYPE=WORK:
  automatically, in a way which can be extended for new orms of
  endpoint (AIM, Skype, etc) and new forms of location (vacation,
  emergency, etc). Having longer names makes this impossible, or
  more complicated.</p>

  <h3>Unlabelled</h3>

  <p>The existence of the v:unlabeledTel Property as an
  (explicitly) unlabeled phone number of a person suggests that an
  unlabelled phone number has extra semantics in its being un
  labelled. I think it is safest to model that a lack of label
  means a lack of informtion, and that a label could be inferred or
  added elsewhere.</p>
  <hr />

  <h2>LDIF: LDAP Data Interchange format</h2><a href=
  "http://tools.ietf.org/html/rfc2849">LDIF</a> is is the format
  which Mozilla (e.g. Thunderbird) takes for import/export of an
  address book. <a href=
  "http://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format">LDIF
  in Wikipedia</a>

  <p>Here is a fairly full ldif file exported from Thunderbird
  <small>version 1.5.0.9 (20061207)</small>:</p>
  <pre>
dn: cn=Zackery Zephyr,mail=zac@example.com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: mozillaAbPersonAlpha
givenName: Zackery
sn: Zephyr
cn: Zackery Zephyr
mozillaNickname: testnick
mail: zac@example.com
mozillaSecondEmail: zackery@example.org
nsAIMid: zaco
mozillaUseHtmlMail: false
modifytimestamp: 0Z
telephoneNumber: +1 202 250 2525
homePhone: +1 202 250 2526
fax: +1 202 250 2527
pager: +1 202 555 2525
mobile: +1 202 555 2526
homeStreet: 1 Zephyr Drive
mozillaHomeStreet2: Apt 26
mozillaHomeLocalityName: Zoaloc
mozillaHomeState: MA
mozillaHomePostalCode: 02999
mozillaHomeCountryName: USA
street: 1 Enterprise Way
mozillaWorkStreet2: Suite 260
l: Zoaloc Heights
st: MA
postalCode: 02998
c: USA
title: Chief Test dataset
department: Testing
company: Zacme Widgets
mozillaWorkUrl: http://example.com/test/zac
mozillaHomeUrl: http://zac.example.net/zac
mozillaCustom1: custom1 value
mozillaCustom2: custom2 value
mozillaCustom3: custom3 value
mozillaCustom4: custom4 value
description: This is a n imaginary person.
</pre>

  <h3>Escaping</h3>

  <p>In LDIF, the following backslah-escaped</p>

  <ul>
    <li>space or "#" character occurring at the beginning of the
    string</li>

    <li>a space character occurring at the end of the string</li>

    <li>one of the characters ",", "+", """, "\", "&lt;", "&gt;" or
    ";"</li>
  </ul>

  <p>ans also a \XX form of hex-escaping.</p>

  <h3>Issues with LDIF</h3>

  <p>The names obviously have a varied and long history, resuting
  in certain inconsisetncy which need not bother us.</p>

  <p>Apart from the 'dn' Distinguished Name field, the structure is
  completely flat. The vCard MIME profile was, I gather, orginally
  designed to be compatible with the x.509 directry structures.
  However, the fields used in a thunderbird dn don't map to the
  fields in a vCard N fields.</p>

  <table>
    <tr>
      <td></td>

      <td></td>

      <td></td>

      <td></td>

      <td></td>
    </tr>
  </table>

  <h2>References</h2>

  <p>See the following for more background.</p>

  <h3>vCard</h3>

  <p><a href="http://tools.ietf.org/html/rfc2425.html">RFC2425: A
  MIME Content-Type for Directory Information</a> Defines
  text/directory . the line-folding and basic record type
  structure.</p>

  <p><a href="http://tools.ietf.org/html/rfc2426.html">RFC2426:
  vCard MIME Directory Profile</a> defines most of the vocabulary
  specific.</p>

  <p>An RDF vcard namespace currently (2007) being developed in
  Namespace <a href=
  "http://www.w3.org/2006/vcard/ns">http://www.w3.org/2006/vcard/ns</a></p>

  <p>Harry Halpin, Brian Suda, Norman Walsh <a href=
  "http://www.w3.org/2006/vcard/ns.html">An Ontology for vCards</a>
  is an ontology which is the latest mapping, to which this is a
  set of comments.</p>

  <p>History: The obsolete <cite><a href=
  "http://www.w3.org/TR/vcard-rdf">Representing vCard Objects in
  RDF/XML</a></cite> is a W3C Note on this from Renato Iannella of
  IPR Systems in 2001. <em>Harry took an action to contact Renato
  <a href=
  "http://swig.xmlhack.com/2006/11/03/2006-11-03.html#a1162567619.883910">
  in the 2006-11-03 #swig meeting</a>.</em> A <a href=
  "http://chatlogs.planetrdf.com/swig/2007-01-26.html#T17-06-09">chat</a>
  on #SWIG was held on 2007-01-26, at which Harry presented a
  <a href=
  "http://www.ibiblio.org/hhalpin/homepage/notes/vcardtable.html">conversion
  table</a> betwen thse fromats</p>

  <h3>LDIF</h3>

  <p><a href=
  "http://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format">LDIF
  in Wikipedia</a> is a good place to start.</p>

  <p><a href="http://tools.ietf.org/html/rfc2849">RFC2840, The LDAP
  Data Interchange Format (LDIF) - Technical Specification</a> This
  is the spec.</p>

  <p><a href="http://tools.ietf.org/html/rfc2253">RFC2253:
  Lightweight Directory Access Protocol (v3): UTF-8 String
  Representation of Distinguished Names</a> defines the format of
  the distinguishes name string.</p>

  <p><a href="http://tools.ietf.org/html/rfc4525">Lightweight
  Directory Access Protocol (LDAP) Modify-Increment Extension</a>
  only affects updates to LDAP stores, so we don't need to worry
  about this.</p>

  <p><a href="http://tools.ietf.org/html/rfc4510">RFC4510: Lightweight
  Directory Access Protocol (LDAP): Technical Specification Road
  Map</a> is the master spec pointing to the bits of LDAP. LDIF was
  defined for LDAP, but does not depend on it.</p>

  <p>Python iCalendar (vcard?) implementtions which may work for
  vCard include</p>

  <ul>
    <li>http://www.schooltool.org/products/schooltool-calendar</li>

    <li>http://www.w3.org/2002/12/cal/icslex.py</li>

    <li><a href="http://lesscode.org/projects/kid/">Kid</a> is a
    project used by <a href=
    "http://www.w3.org/2002/12/cal/vcardin.py">vcardin.py</a>is a
    python program using kid,written by danc</li>
  </ul>

  <address>
    Tim BL, 2007-01
  </address>
</body>
</html>