Version differences

This page briefly describes the differences between the three vCard versions (2.1, 3.0, and 4.0), and how ez-vcard deals with them.

1 Address labels

1.1 Versions 2.1 and 3.0

Address labels are stored in a LABEL property. This property is expected to have the same TYPE parameters as its associated ADR property. Below is an example of such a pairing.

ADR;TYPE=home:;;123 Main St;New York;NY;12345;USA
LABEL;TYPE=home:123 Main St\nNew York, NY 12345

1.2 Version 4.0

Address labels are stored in a LABEL parameter, which is assigned to its associated ADR property. Below is an example of an ADR property with a LABEL parameter.

ADR;TYPE=home;LABEL="123 Main St\nNew York, NY 12345":;;123 Main St;New York;NY;12345;USA

Note that escaped newline characters (\n) cannot normally be included in parameter values, but the specification makes an exception for the LABEL parameter.

1.3 ez-vcard's approach

ez-vcard takes version 4.0's approach and stores an address's label as a LABEL parameter. Therefore, to assign a label to an address, call the Address.setLabel() method (newline characters are automatically escaped when written).

Address adr = new Address();
adr.setStreetAddress("123 Main St");
adr.setLocality("New York");
adr.setRegion("NY");
adr.setPostalCode("12345");
adr.setCountry("USA");
adr.setLabel("123 Main St\nNew York, NY 12345");

Similarly, to get an address's label, call the Address.getLabel() method.

VCard vcard = ...
Address adr = vcard.getAddresses().get(0);
String label = adr.getLabel();

When parsing version 2.1 and 3.0 vCards, ez-vcard automatically converts all LABEL properties to LABEL parameters and assigns the parameter to its associated ADR property. A LABEL is assigned to an ADR property if its list of TYPE parameters is identical to the ADR property's list of TYPE parameters.

When writing a version 2.1 or 3.0 vCard, ez-vcard automatically creates LABEL properties for each LABEL parameter, and assigns the appropriate TYPE parameters to them.

Note that, when parsing a vCard, if ez-vcard cannot determine which ADR property a LABEL property belongs to, it saves the LABEL property as an "orphaned label". To get the orphaned labels in a vCard, call the VCard.getOrphanedLabels() method.

2 "TYPE=pref" vs "PREF" parameters

If you have multiple instances of a specific kind of contact information, such as multiple email addresses, it is possible to specify which one is the most preferred. The way this is done varies between versions.

2.1 Versions 2.1 and 3.0

In versions 2.1 and 3.0, this is done by assigning a "TYPE=pref" parameter to the property. This parameter signifies that the contact information stored in this property is the most preferred out of all the other properties with the same name.

In the example below, the user has marked his work email as his most preferred email address, and his work phone number as his most preferred phone number.

EMAIL;TYPE=home:johndoe@gmail.com
EMAIL;TYPE=work;TYPE=pref:jdoe@company.com
EMAIL:john.doe@college.edu
TEL;TYPE=home:555-111-2222
TEL;TYPE=work;TYPE=pref:555-222-333

2.2 Version 4.0

Version 4.0 uses a PREF parameter to signify preference. This parameter takes a number as its value. The lower the number, the more preferred the contact information is.

In the example below, the user has marked his work email as his most preferred email address, followed by his home email, followed by his school email. Similarly, he has marked his work phone number as his most preferred phone number. His home phone number does not have a PREF parameter, which means it is the least preferred phone number (since there are only two phone numbers, that makes it the second-most preferred phone number).

EMAIL;TYPE=home;PREF=2:johndoe@gmail.com
EMAIL;TYPE=work;PREF=1:jdoe@company.com
EMAIL;PREF=3:john.doe@college.edu
TEL;TYPE=home;PREF=1:555-111-2222
TEL;TYPE=work:555-222-333

2.3 ez-vcard's approach

ez-vcard allows the use of both parameters in its data model and will automatically switch between them as best it can when serializing the vCard.

If a property uses the "TYPE=pref" parameter, and the vCard is being written under version 4.0, then all "TYPE=pref" parameters will be converted to "PREF=1" parameters.

If a property uses PREF parameters, and the vCard is being written under versions 2.1 or 3.0, then it will convert the PREF parameter with the lowest value to a "TYPE=pref" parameter. All other PREF parameters will be removed.

3 ALTID

Version 4.0 supports the alternative representation of properties. This means that you can have multiple instances of the same property whose values all the mean the same thing, but are just represented differently. Properties with the same name and the same ALTID parameter value are considered to have alternative representations of the same value.

For example, a vCard may contain multiple NOTE properties that each have the same ALTID. This means that each NOTE contains a different representation of the same information. In the example below, the first three NOTEs have the same ALTID. They each contain the same message, but each is written in a different language. The other NOTEs have different (or absent) ALTIDs, which means they are not associated with the top three.

NOTE;ALTID=1;LANGUAGE=en:Hello world!
NOTE;ALTID=1;LANGUAGE=fr:Bonjour tout le monde!
NOTE;ALTID=1;LANGUAGE=es:¡Hola, mundo!
NOTE;ALTID=2;LANGUAGE=de:Meine Lieblingsfarbe ist blau.
NOTE;ALTID=2;LANGUAGE=en:My favorite color is blue.
NOTE:This vCard will self-destruct in 5 seconds.

Properties that support alternative representations have methods in the VCard class that allow you to add groups of alternative representation property instances. The names of these methods end in "Alt" and accept a collection of property objects (for example VCard.addNoteAlt()). When these methods are used, an appropriate ALTID parameter value is automatically generated and assigned to each of the properties. The example below adds some alternative representation NOTE properties to a vCard.

VCard vcard = new VCard();

Note hello1 = new Note("Hello world!");
hello1.setLanguage("en");
Note hello2 = new Note("Bonjour tout le monde!");
hello2.setLanguage("fr");
Note hello3 = new Note("¡Hola, mundo!");
hello3.setLanguage("es");
vcard.addNoteAlt(hello1, hello2, hello3);

Note color1 = new Note("Meine Lieblingsfarbe ist blau.");
color1.setLanguage("de");
Note color2 = new Note("My favorite color is blue.");
color2.setLanguage("en");
vcard.addNoteAlt(color1, color2);

Note selfDestruct = new Note("This vCard will self-destruct in 5 seconds.");
vcard.addNote(selfDestruct);

4 Syntax Differences

All vCard versions have similar, but not identical, syntax. The table below describes the differences.

Description	2.1	3.0 and 4.0
Newlines in property values	Encoded newline sequences are not allowed in property values. A workaround is to encode the property value in quoted-printable encoding.	Newlines can be encoded as \n.
Folding whitespace	Multiple whitespace characters can be used at the beginning of a line to denote that it is a continuation of the previous line.	Exactly one whitespace character must be used at the beginning of a line to denote that it is a continuation of the previous line.
Whitespace in property syntax	Any whitespace surrounding the = character that separates a parameter name from its value should be ignored. Similarly, any whitespace surrounding the : character in the BEGIN:VCARD and END:VCARD lines should also be ignored.	Such whitespace should be treated as part of the value (though, spaces are not allowed to be part of property or parameter names).
Nameless parameters	Parameter values that are unambiguous can be specified without a name. For example: ADR;HOME;PARCEL instead of ADR;TYPE=HOME;TYPE=PARCEL.	All parameters must have names.
Multi-valued parameters	Each value must be specified as an individual name/value pair. For example: ADR;TYPE=HOME;TYPE=PARCEL.	Values can be specified in a comma-delimited list. For example: ADR;TYPE=HOME,PARCEL.
Escaped characters in parameter values	Semicolon characters are escaped with a backslash (\;). No other character can be escaped.	If a parameter value contains characters that have meaning in the vCard syntax, the value must be enclosed in double quotes. For example: ADR;LABEL="123 Main Str, Apt: 2B".
Characters permitted in groups, property names, and parameter names	Any printable, 7-bit ASCII character except: []=:.,;	-, 0-9, A-Z, a-z
Characters permitted in parameter values	Any printable, 7-bit ASCII character except: []=:.,	Any printable character except: ".