vCard 4.0 basics: the text/vcard format for exchanging contacts

What it is

A vCard (RFC 6350, media type text/vcard) is a sequence of CRLF-terminated content lines between BEGIN:VCARD and END:VCARD, each of the form NAME;PARAM=value:value. VERSION:4.0 must follow BEGIN:VCARD immediately; FN (the formatted display name) is the only other mandatory property. N holds the structured name as five semicolon-separated components (family names; given names; additional names; honorific prefixes; honorific suffixes). TEL, EMAIL, ADR, URL, ORG, TITLE, PHOTO, BDAY, NOTE, UID and REV are optional, most of them repeatable, with TYPE (work, home) and PREF parameters to distinguish and rank them. The charset is UTF-8 and cannot be overridden; a comma, semicolon or backslash inside a value is escaped with a backslash; content lines should be folded at 75 octets by inserting CRLF plus one whitespace character. RFC 7095 defines jCard, the same data model as a JSON array structure.

Why it matters

vCards travel through QR codes, email signatures, CardDAV synchronisation and CRM imports. Most failures are format-level: a missing FN, an unescaped comma in a company name that splits the value, version 3.0 syntax mixed with 4.0 parameters, or a photo embedded as multi-megabyte base64 that no QR code can hold.

How to apply

• Emit VERSION:4.0, FN and N at minimum; build N from structured fields rather than splitting a display name on spaces, which fails for many naming conventions.
• Write TEL as a tel: URI in international form (TEL;TYPE=work;VALUE=uri:tel:+41…), EMAIL with a TYPE, and ADR with its seven components in order (post office box; extended address; street; locality; region; postal code; country), leaving empty components as empty strings between the semicolons.
• Set UID (a stable URN or URL per contact) and REV (a timestamp) so synchronising clients update instead of duplicating.
• Reference photos by URL in cards meant for QR codes; embed them only in files exchanged directly.
• Validate by importing into two different contact applications; escaping and folding mistakes show up as truncated or merged fields.

Pitfalls

Assuming every importer speaks 4.0: many still expect 3.0 conventions, so stay with widely supported properties and parameter spellings. Line endings converted to LF by a text editor. Fixed Western name order in FN for names that do not follow it. Storing contacts with the vCard as the source of truth instead of structured fields that generate it.