.VCF File Format – Syntax, extensions and other forms

Content lines

contentline = [group "."] name *(";" param) ":" value CRLF
group       = 1*(ALPHA / DIGIT / "-")
param-value = *SAFE-CHAR / DQUOTE *QSAFE-CHAR DQUOTE
any-param   = (iana-token / x-name) "=" param-value *("," param-value)
x-name      = "x-" 1*(ALPHA / DIGIT / "-")

• Folding. A line that begins with white space continues the previous one; the CRLF and that one white space character are removed (unlike RFC 5322, the sequence is removed anywhere). Lines longer than 75 characters should be folded.
• Case. Group, property and parameter names are case-insensitive (write them upper-case). A parameter value is case-insensitive unless its definition says otherwise.
• Quoting. A parameter value that contains a colon, semicolon or comma is put in double quotes (the quotes are not part of the value); an unquoted value may not contain control characters, ", ; or : (SAFE-CHAR); a quoted one may not contain " or controls (QSAFE-CHAR).
• Groups only say that properties with the same prefix belong together; a reader that ignores them can strip the prefix.
• Cardinality: 1 exactly one must be present; *1 at most one; 1* one or more; * any number. A property with several values is normally written as several lines; only some value types (dates, times, integers, floats, text lists) allow comma lists on one line.
• Escaping. A comma in a value is always escaped as \, (even where lists are not allowed). A semicolon is escaped as \; in fields of compound properties (N, ADR, ORG, GENDER) and may be elsewhere. A backslash is \\; a line break is \n or \N. No other escapes are allowed. A compound property that may occur several times must not be put on one line.
• Media type text/vcard, with an optional version parameter that must equal the VERSION of every card in the body; only UTF-8 is allowed as charset.

Value types

text      = *TEXT-CHAR          ; backslash, comma and newline must be escaped
component = text without ";" unescaped    ; a field of a structured value
list-component = component *("," component)
boolean   = "TRUE" / "FALSE"           ; case-insensitive
integer   = [sign] 1*DIGIT             ; 64-bit signed range
float     = [sign] 1*DIGIT ["." 1*DIGIT]   ; no exponent; binary64 precision at least
utc-offset = sign hour [minute]        ; +hhmm basic format, hour 00-23, minute 00-59
date          = year [month day] / year "-" month / "--" month [day] / "--" "-" day
date-noreduc  = year month day / "--" month day / "--" "-" day
time          = hour [minute [second]] [zone] / "-" minute [second] [zone] / "-" "-" second [zone]
date-time     = date-noreduc "T" time-notrunc
timestamp     = date-complete "T" time-complete        ; no truncation
date-and-or-time = date-time / date / "T" time
zone = "Z" / utc-offset

The same value type names appear in the VALUE parameter (text, uri, date, time, date-time, date-and-or-time, timestamp, boolean, integer, float, utc-offset, language-tag). Dates, times and date-times use ISO 8601 basic format, with truncation allowed in the forms above: 19961022T140000, --1022T1400, ---22T14, 19850412, 1985-04, 1985, --0412, ---12, T102200Z, T-2200, T--00; a stand-alone time in date-and-or-time always has a leading T. Timestamps: 19961022T140000Z, 19961022T140000-0500. A URI value stands for what the URI points to (a data: URI embeds the data). A Language-Tag follows RFC 5646.

Value syntax and parameters, property by property

From the ABNF of RFC 6350 section 6. Every property except BEGIN, END, XML and CLIENTPIDMAP also takes any extension parameter (any-param); CLIENTPIDMAP takes only those. VALUE is allowed only with the value type(s) shown. ALTID, PID, PREF, TYPE, LANGUAGE, MEDIATYPE have the meaning of the parameters table.

Parameter value syntax: LANGUAGE= Language-Tag; VALUE= value type; PREF= 1 or 2 digits or 100; ALTID= any param-value (properties with the same ALTID and name count as one for cardinality); PID= one or more 1*DIGIT ["." 1*DIGIT] values separated by commas; TYPE= a comma list of type values; MEDIATYPE= a media type; CALSCALE=gregorian; SORT-AS= sort keys; LABEL= param-value; GEO= and TZ= as for the properties. The TYPE values work and home are allowed on FN, NICKNAME, PHOTO, ADR, TEL, EMAIL, IMPP, LANG, TZ, GEO, TITLE, ROLE, LOGO, ORG, RELATED, CATEGORIES, NOTE, SOUND, URL, KEY, FBURL, CALADRURI and CALURI.

Registered extensions

IANA's vCard Elements registry (last updated 2026-01-13, read 2026-11-13) lists these beyond RFC 6350: properties BIRTHPLACE, DEATHPLACE, DEATHDATE (RFC 6474), EXPERTISE, HOBBY, INTEREST, ORG-DIRECTORY (RFC 6715), CONTACT-URI (RFC 8605), CREATED, GRAMGENDER, LANGUAGE, PRONOUNS, SOCIALPROFILE (RFC 9554), JSPROP (RFC 9555); parameters INDEX, LEVEL (RFC 6715), GROUP (RFC 7095), CC (RFC 8605), AUTHOR, AUTHOR-NAME, CREATED, DERIVED, LABEL, PHONETIC, PROP-ID, SCRIPT, SERVICE-TYPE, USERNAME (RFC 9554), JSPTR, JSCOMPS (RFC 9555); the value data type UNKNOWN (RFC 7095); property values KIND application (RFC 6473) and device (RFC 6869), and the GRAMGENDER values below; parameter values TYPE=main-number on TEL (RFC 7852), LEVEL, TYPE=billing and delivery on ADR, and PHONETIC values. RFC 6473, 6869 and 8605 are on the properties page.

Birth and death (RFC 6474)

• BIRTHPLACE and DEATHPLACE: at most one each; a single text (default) or a single URI (VALUE=text or VALUE=uri, which must match the value); parameters VALUE, LANGUAGE, ALTID. Examples: BIRTHPLACE:Babies'R'Us Hospital, BIRTHPLACE;VALUE=uri:geo:46.769307,-71.283079.
• DEATHDATE: at most one; date-and-or-time (default) or text; parameters VALUE, CALSCALE (only with a date or date-time), LANGUAGE (only with text), ALTID. Its presence says the subject is known to be dead; its absence says nothing. Examples: DEATHDATE:19960415, DEATHDATE:--0415, DEATHDATE;VALUE=text:circa 1800.

Expertise, hobbies and interests (RFC 6715)

• EXPERTISE, HOBBY, INTEREST: any number; one free-form text value each, meant for people (no vocabulary is defined); parameters LEVEL, INDEX, LANGUAGE, PREF, ALTID, TYPE. A hobby is something one actively does; an interest one merely finds interesting.
• ORG-DIRECTORY: any number; a URI for an organisation-directory lookup; parameters PREF, INDEX, LANGUAGE.
• INDEX= an integer, to order items. LEVEL= is beginner, average or expert on EXPERTISE and high, medium or low on HOBBY and INTEREST. Example: EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature.

TEL type main-number (RFC 7852)

An additional TYPE value on TEL for the main number of an enterprise, as opposed to a direct-dial number; the RFC defines it for xCard in emergency-call additional data.

Updated and new elements (RFC 9554)

• N gains two components after the five: secondary surname and generation (II, XVI, Jr.); the value is list-component 6(";" list-component). Writers should also keep the old counterparts (secondary surname inside family names, generation inside honorific suffixes); readers should ignore a value in the old component if an equal one is in the new one. Example: N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.;;Jr.. SORT-AS applies to the new components too.
• ADR gains eleven components after the seven, in this order: room, suite or identifier; apartment, extension or box number; floor or level; street number; street name; building, tower or condominium; block; subdistrict; district; landmark; cardinal direction or quadrant. Writers should still write the combined value in the street component; readers should ignore that component if any new one is set. Example: ADR;GEO="geo:12.3457,78.910":;;123 Main Street;Any Town;CA;91921-1234;U.S.A;;;;123;Main Street;;;;;;.
• CREATED (at most one): a timestamp of when the vCard was created, unchanged by copying; parameter VALUE=timestamp. GRAMGENDER (any number): the grammatical gender to use in salutations; animate, common, feminine, inanimate, masculine, neuter, iana-token or x-name; copies are told apart by the LANGUAGE parameter. LANGUAGE (at most one): the default Language-Tag of text values in the card; a property's own LANGUAGE parameter overrides it; this property takes no LANGUAGE parameter. PRONOUNS (any number): free text such as xe/xir; parameters LANGUAGE, PREF, TYPE, ALTID. SOCIALPROFILE (any number): a URI (default) or text; with a text value SERVICE-TYPE is required; at most one SERVICE-TYPE; names are equal if they match case-insensitively.
• Parameters. AUTHOR (a quoted URI) and AUTHOR-NAME (non-empty text) say who wrote a property value; CREATED (a timestamp) when a property was created; DERIVED (true or false, default false) marks a value computed from other properties (clients must not update it when true); LABEL (formatted address, now registered); PHONETIC (ipa, jyut, piny, script; for ADR and N) says the property holds the pronunciation of another property of the same name, linked by an equal ALTID, with a component at the same position wherever one is set, and with SCRIPT set when the value is script; SCRIPT (a four-letter script subtag such as Latn); PROP-ID (1 to 255 of A-Za-z0-9, -, _; identifies a property among same-named siblings); SERVICE-TYPE and USERNAME (case-sensitive; on IMPP and SOCIALPROFILE; with USERNAME the value must be a URI).
• Values. TYPE=billing and TYPE=delivery on ADR.

JSContact conversion (RFC 9555)

RFC 9555 defines how a vCard maps to a JSContact card (JSON, RFC 9553). The vCard side adds:

• JSPROP (any number): a JSContact property that has no vCard equivalent, written as the compact JSON text of its value; JSPTR is required, and VALUE=TEXT and extension parameters are allowed. Example: JSPROP;JSPTR="example.com:foo":{"bar":1234}. The pointer is relative to the card and may not reach into an array. All JSPROP lines together form a patch object applied after everything else is converted.
• JSPTR: a quoted JSON pointer (RFC 6901). JSCOMPS: a quoted, semicolon-separated list that preserves the order and separators of name or address components: the first entry is the default separator (s, followed by its text, or empty), then entries that are positions (index or index,subindex into the structured value) or separators (s, then text, with comma and semicolon escaped, RFC 6868 encoding). It is valid only if every index exists and the number of position entries equals the number of component values after removing the duplicates caused by backward-compatible copies (secondary surname, generation, street).

The mapping of each vCard property to JSContact is the subject of that RFC and not part of the vCard file format.

vCard in XML: xCard (RFC 6351)

Namespace urn:ietf:params:xml:ns:vcard-4.0 (the version is in the namespace, so there is no VERSION element); media type application/vcard+xml (charset UTF-8 strongly recommended).

• The root is vcards and contains one or more vcard elements. Property and parameter names become lower-case element names (FN becomes fn). A property element contains an optional parameters element and then its value inside a typed value element (text, uri, ...); parameters with lists repeat the value element.
• Structured values become element trees with named children (surname, given, ...); the names are positional in plain vCard and have no vCard equivalent. A group is the group element with a name attribute.
• Folding does not exist in XML: convert after unfolding and fold after converting back.
• Extensions: X- and VND-...- names become x- and vnd-...- elements; extension elements with no plain-vCard form should use an XML namespace and are kept in vCard as the XML property (only direct children of the card are converted). A reader ignores elements and attributes whose expanded name it does not know. The schema cannot check cardinalities, which must still be respected, and some enumerations have a fixed order.
• A property of unknown default value type and no VALUE parameter, and any unrecognised parameter, is written with the value element unknown holding the raw text.

vCard in JSON: jCard (RFC 7095)

Media type application/vcard+json (optional version parameter).

• Order of conversion: unfold, remove vCard escaping, apply JSON escaping; reverse on the way back, then fold long lines.
• Card: a two-element array, "vcard" and an array of properties; BEGIN and END are not written. Several cards: a JSON array of them. version must be the first property and keeps the value 4.0.
• Property: an array of lower-case name, parameter object ({} if none), lower-case value type, then the value (four elements for a single value, more for several values). Parameter keys are lower-case, values keep their case, list values are arrays of strings (single values may be strings). VALUE is not written (the type string replaces it) and is added back when the type differs from the default and the type is not unknown.
• Groups are the parameter group (lower-case string), never a name prefix; the parameter is registered but must not appear in vCard.
• Structured values (N, ADR, GENDER, ORG) are arrays with one element per component, an empty string for an empty component; a component with several values is a nested array. ["adr", {}, "text", ["", "", "123 Main Street", "Any Town", "CA", "91921-1234", "U.S.A."]].
• Dates and times use the ISO 8601 extended format (1985-04-12, 1985-04, --04-12, ---12); where the extended format does not apply the basic format is used. Other values are JSON strings, numbers and booleans by type.
• Unknown properties (default type not known, no VALUE) are written with type unknown and the raw string value (using text would add escaping and break the round trip); an unrecognised parameter is converted to a string. The type name UNKNOWN is reserved and never appears in a real vCard. When converting back, VALUE is left out for unknown and may be left out when the type is the default.