The full name of a person is given with the FN type. This is one of the required fields in any Version 3.0 vCard. Its value is simply the name of the person in 8-bit text:

FN: Justin Case, Ph.D.

The full name of a person may include title information if it is desired. Note the backslash-escaped comma in the name.

In contrast to the full name is the N (structured name) type; used to provide a structured set of components that make up the user’s name. This is also a required field. Elements in the name are separated by semicolons, some of which may be further separated by commas. The elements are:

As a complex example, try this one:

FN: Captain Sir Justin Quentin Case, Ph.D., FRCS, KB
N:  Case;Justin;Quentin;Captain,Sir;Ph.D.,FRCS,KB

Several vCard types, including the N type, allow for parsing of different naming conventions found in the world. In the West, for example, family names normally come last, whereas in the East they may come first. Structured directory types help the reader to properly parse names regardless of their origin.

Many people do not use their full and proper legal name in the course of their daily lives. The NICKNAME type allows vCards to hold such information. Whereas the FN and N types should hold a person’s legal name, the NICKNAME type can hold a familiar or shortened version or a different name altogether:

FN:        James N. Casselwary
NICKNAME:  Jim, Jimmy

Multiple nicknames may be given, comma separated.

In some cases, it may not be clear to the recipient of a vCard how to file the subject’s name. This may be true for either a human reader or a program attempting to store a vCard in a data store. Take for example the name “Kim Jan Wan.” Is the surname Kim or Wan? In this case it is Kim, so the vCard should be filed in the data store under “Kim,” and a search for surnames beginning with “K” should return the card. To facilitate this kind of proper storing and searching, the SORT-STRING type has been made available. SORT-STRING may be used to inform a recipient (human or otherwise) of the sender’s family name, as in this example:

FN:           Miguel Campos de Carvalho
N:            Campos de Carvalho;Miguel
SORT-STRING:  Campos

Identification of a person’s job title and a description of what they actually do are provided in the TITLE and ROLE types. TITLE specifies a person’s job title (e.g., Chief Information Officer), and ROLE specifies the occupation or business category of the subject (e.g., Network hack extraordinaire). For example:

TITLE:    ROLE: Director, International Sales
ROLE:     Door to door salesman

Now let’s look at something more interesting. Earlier, we mentioned that vCard may hold more than textual data. The PHOTO type, used to provide an image of the person a vCard represents, has a value that may take one of two forms: a URI or an inline binary image.

If an image is referenced by a URI, the PHOTO type looks just like any of the ones shown previously, except that it makes uses of an embedded type (VALUE) to denote its use of a URI:

PHOTO;VALUE=URI:    http://www.shicho.com/photos/gdalf.jpg

If, on the other hand, an inline binary image is used, the type is more complex. First, an ENCODING subtype must be specified to override the default of 8-bit text. The encoding for an inline binary is always base64, as described in Chapter 3, Multipurpose Internet Mail Extensions. This is marked in vCard as “ENCODING=b”. Next, the image type is given (e.g., TYPE=JPEG shows that the encoded image is a JPEG format). An embedded image might look like this:

PHOTO;ENCODING=b;TYPE=JPEG:/9j/4AAQSkZJRgABAgEASABIAAD/7QG4UGhvd
 G9zaG9wIDMuMAA4QklNA+kAAAAAAHgAAwAAAEgASAAAAAAC2gIo/+H/4QL5AkUD
 RwUoA/wAAgAAAEgASAAAAAAC2AIoAAEAAABkAAAAAQADAwMAAAABJw8AA…

Note that when more than one subtype is used (here, ENCODING and TYPE), they are separated by semicolons.

Closely related to the IMAGE type is LOGO. LOGO is used to provide a corporate logo or other artwork that represents the subject of the vCard. Like IMAGE, a LOGO’s value may be a URI or an embedded image. The ENCODING and TYPE subtypes are used exactly in the same manner.

Another multimedia type is SOUND. SOUND is generally used to provide the proper pronunciation of the sender’s name, although it can be used for any audio recording that provides information about the sender. Sound content, like embedded images, is either a URI or an embedded binary encoded with base64. The audio format type is provided with a TYPE subtype that should be one of the lANA-registered audio formats.

If a sound is referred to as a URI, it might look like this:

SOUND;TYPE=BASIC;VALUE=URI:    http://www.northernice.net/-jpennce/s
 ounds/mynarne.au 

An embedded sound file looks very similar to an image and needs to have the encoding changed to base64 just as an embedded image does:

SOUND; TYPE=BASIC; ENCODING=b:HCAcHBgkJCgoJCQwMDAwMDAwMDAwMDAwMDAE
 DAwMFBAUJBgYJDQoJCgOPDg40Dg8PDAwMDAwPDwwMDAwMDA8MAwMDAwMDAwM…

The birthday of a person may be advertised with the BDAY type. This takes a date or a date-time group as a value. A BDAY entry might look like either of these:

BDAY:19630828
BDAY:          1963-08-28T06:22Z

The vCard format allows for physical address information, as well as electronic. Physical delivery addresses may be given using the ADR type. Since physical addresses vary widely from country to country, a structured format is used to ensure that all information can be properly parsed. Physical address information is separated by semicolons and consists of the following mandatory (although possibly empty) fields:

If a given entry has multiple values, they may be separated by commas.

A vCard may include multiple address lines (e.g., one for home and another for work). Each line may include TYPE parameters to further inform the reader, which may be combined as needed. Possible types are:

If a person has a P.O. box for parcels, a home address, and a work address, and they prefer to get mail at their work address, the corresponding three ADR lines might look like this:

ADR;TYPE=intl,home,parcel:PO Box 4130;;1443 Fillmore St.;San
 Francisco;CA;94115-4130;USA
ADR;TYPE=dom,home,postal:;Apartment 4;510 Beach St.;San
 Francisco;CA;94115;
ADR;TYPE=intl,work,postal,pref:;IT Department, Bean
 Corporation;4325 San Mateo Rd;San Mateo;CA;94103;USA

To be even more specific as to postal delivery instructions, the LABEL type may be used to specify the content of an address label for postal deliveries. The value is a formatted text field that should be used as the verbatim content of a postal address label. Text formatting includes linebreaks, given as “ ”. Multiple labels may be defined in the same way as in the ADR type.

An address label for the parcel address given previously might look like this:

LABEL;TYPE=intl,home,parcel:Mr. J. Smythe, c/o MailBoxes, Etc.

 PO Box 4130
1443 Fillmore St.
San Francisco, CA
USA 94115-4130

I have already given some insight into the way telephone numbers are represented. Like physical addresses, multiple telephone numbers may be given in a single vCard. The valid TYPEs are:

A telephone service is presumed to be a voice number unless otherwise announced (e.g., fax, modem).

If one chose to advertise three telephone numbers—one each for work, mobile service, and facsimile, as is common on business cards—TEL lines in a vCard could look like this:

TEL;TYPE=work,voice,pref,msg: +61 7 3865 1543
TEL;TYPE=cell,voice,msg:      +61 411 989 348
TEL;TYPE= fax,work:           +61 7 3865 1544

Electronic mail addresses in a vCard are given in an EMAIL line. The currently defined TYPEs of email addresses are Internet (SMTP) and x.400. Other types may be specified as a nonstandard TYPE. The “pref” marker may be used here as well, in the case of multiple address listing:

EMAIL;TYPE=internet:[email protected]
EMAIL;TYPE=internet.pref:[email protected]

Related to the EMAIL type is MAILER, which optionally provides the name of the MUA that the subject uses. This is analogous to the X-Mailer SMTP header commonly used by MUAs today and should carry the same value. This type is used only when it provides some useful information, such as restrictions on receiving MIME attach ments.

Since it has become common to place URLs on business cards, either to point to a person’s personal or corporate home page, it is also possible to refer to URLs from a vCard. The URL type provides a URL as a text value:

URL:     http://staff.plugged.net.au/dwood

Two types provide information on the geographical location of a vCard’s subject, TZ (time zone) and GEO (a latitude and longitude location). TZ is especially useful for those using the telephone for calls outside of their own time zone.

A TZ value is either a formatted offset from Universal Time, Coordinated (UTC) , either plus or minus a number of hours and minutes, or a textual representation of the same information. For example, these are equivalent:

TZ:+10:00
TZ;VALUE=text:+10:00; EST; Queensland, Australia

The first example shows that the vCard owner is in the +10 time zone, which is ten hours earlier than Zulu, or UTe. The second one shows the same information in tex tual format and adds the location description.

The GEO type goes overboard to provide a precise latitude and longitude position (down to a single meter!) of the subject. Anyone that can find a use for this level of granularity in a vCard is encouraged to send an email to the author.

Each GEO value specifies a number of decimal degrees latitude (positive for north and negative for south) and a number of decimal degrees longitude (positive for east and negative for west). The two values are semicolon separated, and each should be specified to six decimal places. For example, the approximate location of Brisbane, Australia, could be given in the GEO line:

GEO:-27.506419;+153.172356

Organizational information can be represented in a vCard by use of the ORG, CATEGORIES and AGENT types. ORG specifies the name of an organization (and its specific subparts like a department). CATEGORIES provides information as to the type of business the organization does. AGENT gives contact details for the vCard subject’s personal assistant.

The ORG type names the organization for which the subject works. Each suborganization is separated from the last by a semicolon, like so:

ORG:The university of California;Lawrence Livermore National
 Laboratory;TISP

The CATEGORIES type provides a general industry category for the business. Values are given as comma-separated keywords for the industry:

CATEGORIES: INTERNET,SOFTWARE,INFORMATION TECHNOLOGY

The AGENT type is used to provide contact details (either in full or in part) for a person’s agent (or secretary or personal assistant). An AGENT’s details are generally given as an embedded vCard, although only a subset of the vCard need be given. Alternately, a URI may be given that provides the same information. An embedded vCard looks like this:

AGENT:begin:vcard
fn:Brad Marshall
n:Marshall;Brad
email;TYPE=
 internet:[email protected]
tel;TYPE=work,voice,msg,pref:+
 61 7 3876 7140
version:3.0
end:vcard

An embedded vCard must have all of the requirements for any other vCard, such as BEGIN, FN, N, VERSION, and END types. Note the linebreaks in the embedded vCard represented as s. Also, embedded semicolons must be escaped so that they are not confused with a subtype delimiter.

Since an embedded vCard is the default, an AGENT speCified via a URI would need to use the VALUE subtype:

AGENT;VALUE=URI:http://staff.plugged.net.au/bmarshal

Supplemental information and general comments may be placed into a vCard as plain text using the NOTE type. Programs that parse or display vCard information may display this information to a user but aren’t expected to understand it. One can say almost anything in a NOTE:

NOTE:  I have returned from the Land of Many Sorrows and no longer
 abide software which mostly sucks. Penguins grace this stable
 domain.

If the sender of the vCard wants to ensure that he is never mistaken for anyone else in the world, he may include a globally unique identifier for himself using the DID type. This type could be used to clearly identify someone with a common name within a large corporation, for example. Any form of unique identifier may be used, but the form should be noted with a TYPE subtype. Preferably, the type of format used will be registered with the Internet Assigned Numbers Authority (lANA) or marked as a nonstandard form.

If we wanted to assign unique identifiers to all employees in a company and include that information on their vCards so that they would be easy for a machine to parse, we might do something like this:

UID;TYPE=X-XYZCORP-UID: 1999-02-29_john_smith_42

In this case, we at the XYZ Corporation made up our own DID format, called XXYZCORP-UID, and assigned a date, name, and number to each employee.

A better and more common way to prove the identity of a vCard’s owner is by using public cryptographic keys (e.g., PGP) or certificates (e.g., X.509). The KEY type allows vCards to hold either of these. Interestingly, a key or certificate must be embedded inside a vCard; URIs may not be used to refer to them elsewhere.

Subtypes used with KEY include ENCODING, which must be et to either “b” for base64 or “text”, and TYPE, which optionally provides the type of certificate or key that is embedded. An X.509 certificate embedded in a vCard and encoded with base64 might look like this:

KEY;ENCODING=b;TYPE=X509:KQoKYXVkaW8vYmFzaWMJCQkoc25kKQphdWRpby91bGF3CQ
kJKGF1KQphdWRpby94LFpZmYJCQkoYWlmIGFpZmMgYWlmZikKYXVkaW8veC1wbi1yZWF...

Like most of the other types, more than one KEY may exist in a vCard, so that one may embed both an X.509 certificate and a PGP public key if one so desired.

Naturally, vCards may contain some information not for public consumption (such as a home telephone number). How is one supposed to control the flow of data? In short, this is not a problem for the vCard format itself, but for the creator of the vCard. This line of reasoning shows how closely the concept of a vCard is related to the development of directory services: You don’t need a directory service in order to create and use vCards, but the two dovetail nicely for certain applications. If you use a directory service to hold information about people and other objects, vCard information can be extracted as a subset. In fact, different vCards can be created for different uses. Each person is presented only with the information that they are allowed to see.

Levels of security classification may be represented in a vCard with the CLASS type. These may be any textual values (e.g., Confidential, Secret, Top Secret or Personal, and Public). IfvCards are generated from a directory service (which presumably understands the classification scheme used), then different vCards may be created for different people. That is, my boss might have access to a vCard including my home telephone number, but a sales representative might be issued another vCard without it.

The CLASS type is useless by itself; it must be associated with a directory service that understands its meaning. An example CLASS line showing that the vCard in hand contains personal information could look like this:

CLASS: Personal

Other types may be created for use by specific applications by prepending an “X-” to the type name. One company (myVcard.com) on the Web uses a custom type to store the name of a person’s spouse:

X-MYVCARD-SPOUSE: Husband O. Wifey

Each vCard 3.0 type is summarized in Table 6-1. Where the value of a type is marked as <structured text>, a specific format applies. Where the value is marked <escaped text>, it means that the text is of a given format and needs to be decoded by replacing all instances of “ ” with a linebreak.