vcard-implementations

vCard implementations

In the development of hCard and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the vcard-errata.

Conventions

Conventions for this page. When documenting a specific implementation, use the name of the implementation as the header including minimal version information. Provide an abbreviation of the implementation name (in parantheses) for use in subheadings for property names and other general subsections. Prefix subheadings with aforementioned abbreviation followed by vCard property name (if applicable) in ALL CAPS as vCard properties are typically fully uppercased in both vCard files and implementations (but are actually case-insensitive per RFC 2426).

General Suggestions

General implementation guidelines and suggestions for vCard implementations. (Note: it might be useful to separate the more generic aspects of of these general vCard implementation suggestions into a "contact application" section on the user-interface page.)

1. Fully implement RFC 2426, including all properties, sub-properties, and type values for properties, on both import and export with 100% roundtrip fidelity.
2. Support subscribing to vCard URLs on the Web in addition to importing so that your local address book can have automatically current (fresh) information of the contacts that you've added from the Web.
3. Use a rendering engine (e.g. Trident, Gecko, Webkit) to render PHOTO URLs and other properties which have URL values live from the Web for similar freshness.
4. When syncing to another device that supports contact information (iPod, iPhone, BlackBerry etc.), downsample PHOTOs (and other images or binary data) to whatever small size works best on those devices so as to not bloat the space on those devices. Note that such downsampling is best done closest to the point of synchronization, e.g. by the Address Book application when syncing, instead of upfront by a web service like X2V, so that maximum data fidelity is maintained until the last minute when the data can be compressed for the specific device purely for efficiency reasons.

Microsoft Outlook

Microsoft Outlook (MSOutlook). version? platform?

MSOutlook single import

Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some third-party products that attempt to fix this [1]

MSOutlook URL handling

URL without non-standard TYPE parameter seems to be ignored.

MSOutlook ADR handling

Appears to not support the post-office-box sub-property of ADR.

MSOutlook escaped commas

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

Microsoft Outlook 2003

Microsoft Outlook 2003 (MSOutlook2k3) The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

MSOutlook2k3 URL

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

MSOutlook2k3 ADR

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:

ADR;CHARSET=utf-8:;;address1;city;state;zip;

is changed to:

ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip

MSOutlook2k3 N

When exporting a vCard, copies FN into N when N is blank. Does not do this when importing a vCard.

Outlook 2003 does not handle comma separation in the properties of N. For this vCard.

BEGIN:VCARD
FN;CHARSET=UTF-8:Mr. Dr. John Maurice Benjamin Doe Ph.D.\, J.D.
N;CHARSET=UTF-8:Doe;John;Maurice,Benjamin;Mr.,Dr.;Ph.D.,J.D.
END:VCARD

The result in Outlook is:

Mr.,Dr. Mr. Dr. John Maurice Benjamin Doe Ph.D.\, J.D.

MSOutlook2k3 TEL

Drops TEL if TYPE is not explicitly specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

MSOutlook2k3 GEO

Unsupported. GEO is unsupported and is ignored.

MSOutlook2k3 LOGO

Unsupported. Will not import nor export vCard image references, but does support images internally in it's own contact management system.

Windows Address Book

Windows Address Book (WAB) Version 6.00.X Win98 and Win XP Pro

WAB vCard ENCODING

UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

WAB ADR

If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

WAB TEL

If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

WAB PHOTO

Unsupported. Does not support images.

WAB NOTE

According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

Microsoft Entourage

On Mac OS X. Entourage versions 10 and 11.

Entourage general comments

• Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.
• Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).
• Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

Apple Address Book

Apple Address Book (AAB) on Mac OS X 10.3 (Panther) and 10.4 (Tiger).

AAB general comments

• There are issues with importing UTF-8 vCards. Apple Address Book appears to treat .vcf files in the file system NOT as UTF-8, but rather perhaps Mac Roman?
  • Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters. This is allowed per vcard-errata, and encouraged to enable higher fidelity character set handling.
• Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
  • Workarounds:
    • Only markup one hCard per person, per page (has potential implications for hResume).
    • Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
• Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

Several properties appear to have no or limited support, see below for specifics.

AAB organization vs individual

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

AAB GEO

Unsupported. The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

AAB SOURCE

Unsupported. The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

AAB LOGO

Unsupported. The LOGO property is totally ignored and not even saved as part of the NOTE.

AAB PHOTO

Partial support. The PHOTO property is only supported when it has inline encoded data. URL values appear to be ignored.

AAB URL

Lack of support for aim protocol. URLs starting with "aim:" are imported but then when clicked, Address Book prepends them with http:// before "activating" them thus rendering them non-functional.

Non-standard restriction to one value. (Version 3.0 and below only. Works fine in v4.0+): Only ONE URL property value is supported for vCard import (whereas multiple *should* be supported, just like EMAIL).

AAB ADR

Quirky. If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address, whereas vCard specifies that the default type for adr is all of: INTL, POSTAL, PARCEL, WORK.

AAB CATEGORIES

Quirky. Behavior confirmed on versions:

• default on OSX.3
• Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.

1. It does not add vCards with a category that matches a current Group to that Group.
2. It does not create new Groups for vCards with new categories.
3. It does not even add the CATEGORIES to the end of the notes field.

Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

Evolution

Evolution (Evo) On Linux.

Evo GEO

Unsupported.

• ichigo, Frederic to fill in details

Evo KEY

Evolution uses GnuPG to manage GPG/PGP keys

Nokia series 60 address book

Nokia series 60 address book (N60AB).

N60AB line endings

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behavior because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

Palm Desktop 4.1.4

Palm Desktop 4.1.4 (PD414).

PD414 vCard import

Palm Desktop 4.1.4 appears to fail importing a vcard if it has a NAME specified in the vcard.

CSV to vCard

CSV to vCard web service takes CSV (or tab-delimited) contacts and turns them into vCard format. This was originally written to take information from Outlook Express for Mac OS 9 and bring it into the address book in OS X.

contributors

• Tantek Çelik
• Brian Suda
• Steve Robillard

related pages

• hCard
• hCard cheatsheet - hCard properties
• hCard creator (feedback) - create your own hCard.
• hCard authoring - learn how to add hCard markup to your existing contact info.
• hCard examples - example usage of various classes within hCard.
• hCard examples in the wild - an on-going list of websites which use hCards.
• hcard-supporting-user-profiles - sites with user profiles marked up with hCard - a very common example.
• hCard FAQ - if you have any questions about hCard, check here.
• hCard implementations - websites or tools which either generate or parse hCards.
• hCard parsing - normative details of how to parse hCards.
• hCards and pages - semantic distinctions between different hCards on a page, and how to identify each
• hcard-user-interface - techniques and issues surrounding user-interfaces to author, publish, and display hCards.
• hCard profile - the XMDP profile for hCard
• hCard singular properties - an explanation of the list of singular properties in hCard.
• hCard tests - a wiki page with actual embedded hCards to try parsing.
• hCard advocacy - encourage others to use hCard
• hCard "to do" - jobs to do

The hCard specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.

• hCard brainstorming - brainstorms and other explorations relating to hCard.
  • hcard-parsing-brainstorming - brainstorming specific to parsing of hCard
  • geo brainstorming
• hCard feedback - general feedback (as opposed to specific issues).
• hCard issues - specific issues with the specification.
• vCard errata - corrections to the vCard specification, which underlies hCard.
• vCard suggestions - suggested improvements to the vCard specification.