Skip to content

vCard Overview

Jump to bottom
Mike Angstadt edited this page Jan 1, 2016 · 1 revision

vCards can be described as "electronic business cards". They are typically used for encoding contact information about an individual, such as their name, address, and phone number. Most email clients and address book applications provide at least basic support for vCards. This makes vCard an ideal choice for transferring contacts between applications or for sharing contacts with others.

vCards can also be used to represent entities other than individuals, such as groups and organizations. However, they are most commonly used to represent individuals.

vCard files end with a ".vcf" extension. The latest vCard specification is defined in RFC 6350.

The vCard data model consists of a collection of properties. Each property consists of a name, an optional group name (a way of saying that certain properties belong together), a list of parameters (key/value attributes), and a value.

Each vCard starts with "BEGIN:VCARD" and ends with "END:VCARD". Each line of text between these two markers is a property. The property's name is located at the beginning of the line. If the property belongs to a group, then the line begins with the group name, followed by a dot, followed by the property name. The property's parameters are located in between the property name and the first colon character. The property's value is located after the first colon character.

Properties with large values are typically folded, meaning their values are split across multiple lines. Folded lines are identified by the fact that they begin with a whitespace character (a space or a tab). Most vCard producers fold lines when they get to be between 70-80 characters long (the vCard specification recommends 75 characters).

The vCard below contains an individual's name in both formatted and structured formats. The EMAIL property belongs to a group named "group1". The NOTE property has a large value, and is folded across three lines. The comma character in this property value is escaped with a backslash because commas have a special meaning in some property values.

BEGIN:VCARD
VERSION:4.0
N:Doe;John;;Mr;
FN:Mr. John Doe
group1.EMAIL;TYPE=home:jdoe@example.com
NOTE:Lorem ipsum dolor sit amet\, consectetur adipiscing elit. Donec at lac
 us justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspen
 disse suscipit eleifend molestie.
END:VCARD

Multiple vCards can exist inside of the same data stream. The text below contains two vCards.

BEGIN:VCARD
VERSION:4.0
FN:Mr. John Doe
END:VCARD
BEGIN:VCARD
VERSION:4.0
FN:Mrs. Jane Doe
END:VCARD

vCards can also be encoded in XML ("xCard"), JSON ("jCard"), and HTML ("hCard") formats.

XML

<vcards xmlns="urn:ietf:params:xml:ns:vcard-4.0">
  <vcard>
    <n>
      <surname>Doe</surname>
      <given>John</given>
      <prefix>Mr</prefix>
    </n>
    <fn>
      <text>Mr. John Doe</text>
    </fn>
    <group name="group1">
      <email>
        <parameters>
          <type><text>home</text></type>
        </parameters>
        <text>jdoe@example.com</text>
      </email>
    </group>
    <note>
      <text>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at lacus justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspendisse suscipit eleifend molestie.</text>
    </note>
  </vcard>
</vcards>

JSON

["vcard",
  [
    ["version", {}, "text", "4.0"],
    ["n", {}, "text", ["Doe", "John", "", "Mr", ""]],
    ["fn", {}, "text", "Mr. John Doe"],
    ["email", {"group":"group1", "type":"home"}, "text", "jdoe@example.com"],
    ["note", {}, "text", "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at lacus justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspendisse suscipit eleifend molestie."]
  ]
]

HTML

<html>
  <head>
    <link rel="profile" href="http://microformats.org/profile/hcard" />
  </head>
  <body>
    <div class="vcard">
      <h1 class="fn n">
        <span class="prefix">Mr</span>. 
        <span class="given-name">John</span> 
        <span class="family-name">Doe</span>
      </h1>
      
      Email:
      <a class="email" href="mailto:jdoe@example.com">
        <span class="value">jdoe@example.com</span>
        (<span class="type">home</span>)
      </a>

      <p class="note">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at lacus justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspendisse suscipit eleifend molestie.
      </p>
    </div>
  </body>
</html>

ez-vcard is maintained by Michael Angstadt

Table of Contents

Getting started
Examples
FAQ
Javadocs
Downloads

1 An Overview of the vCard data format

2 Reading and Writing vCard data with ez-vcard
2.1 Plain-text (traditional)
2.2 XML-encoded (xCard)
2.3 JSON-encoded (jCard)
2.4 HTML-encoded (hCard)

3 Differences between the vCard versions

4 Dealing with Non-standard Data
4.1 Working with non-standard properties and parameters
4.2 Property scribe

5 Project Information
5.1 News
5.2 Dependencies
5.3 Supported Specifications
5.4 Changelog

6 Reference
6.1 vCard Property Reference
6.2 Javadocs

Clone this wiki locally