Every line in a VCF file follows the pattern PROPERTY;PARAMETER=VALUE:content. The property name comes first, followed by optional semicolon-separated parameters, then a colon, then the actual value. Lines starting with a space or tab are continuations of the previous line (line folding). Special characters are escaped with backslashes. Contacts are delimited by BEGIN:VCARD and END:VCARD markers. If you are new to the VCF format itself, start with our VCF file format overview.
Introduction
Open any VCF file in a text editor and you see lines of text that look almost readable but not quite. Names and phone numbers are there, but they are surrounded by property names, semicolons, parameters, and occasionally blocks of encoded data that fill hundreds of lines. To work with VCF files programmatically, to debug import errors, or to manually fix a corrupted contact, you need to understand the syntax rules that govern every line.
This guide reads a VCF file the way a parser reads it: one line at a time, breaking down the syntax rules that apply to each element. By the end, you will be able to open any VCF file in a text editor and understand exactly what every line means, why it is structured that way, and what to look for when something is wrong.
Anatomy of a vCard Property Line
Every property in a vCard file follows this structure:
PROPERTYNAME;PARAM1=VALUE1;PARAM2=VALUE2:content-value
The three components are separated by specific delimiters. The property name (like FN, TEL, EMAIL) identifies the type of data. Parameters after semicolons modify or qualify the property. The colon separates the property declaration from the actual data value. Everything after the first unescaped colon is the content.
A simple property looks like this: FN:Maria Garcia. The property is FN (formatted name), there are no parameters, and the value is “Maria Garcia”. A complex property looks like this: TEL;TYPE=CELL;VALUE=uri:tel:+1-555-234-5678. The property is TEL, with two parameters (TYPE=CELL and VALUE=uri), and the value is “tel:+1-555-234-5678”.
Understanding Parameters and TYPE Values
Parameters appear between the property name and the colon, separated by semicolons. The most common parameter is TYPE, which classifies the data. A phone number can be TYPE=HOME, TYPE=WORK, TYPE=CELL, or TYPE=FAX. An email address can be TYPE=HOME or TYPE=WORK. An address uses TYPE=HOME or TYPE=WORK to distinguish between residential and office locations.
Multiple TYPE values can be combined. The property TEL;TYPE=WORK,VOICE,PREF:+1-555-100-2000 means this is a work voice number that is also the preferred contact number. In vCard 2.1, the syntax is slightly different: TEL;WORK;VOICE;PREF:+1-555-100-2000 (TYPE= prefix is omitted). Both forms are encountered in real-world files.
Other common parameters besides TYPE include CHARSET (character encoding, used in vCard 2.1), ENCODING (how the value is encoded, like QUOTED-PRINTABLE or BASE64), LANGUAGE (the language of the value), and VALUE (the data type of the value, like URI, DATE, or TEXT).
Line Folding: When One Property Spans Multiple Lines
The vCard specification limits logical line length by allowing a single property to be split across multiple physical lines. When a line is folded, the continuation line starts with exactly one space character or one horizontal tab character. During parsing, the line break and the leading whitespace are removed, and the continuation is joined to the previous line.
For example, a long note might appear as:
NOTE:This is a very long note that contains important information
about the contact and spans multiple lines in the file because
the content exceeds the recommended line length.
When parsed, this becomes a single property: NOTE:This is a very long note that contains important information about the contact and spans multiple lines in the file because the content exceeds the recommended line length.
Line folding is the single most common cause of parsing errors in manual text processing. If you extract properties using grep or simple line-by-line reading, folded lines appear as orphan lines without a property name, and the parent property is truncated. Any VCF parser must handle line unfolding as its first step before processing individual properties.
Escaped Characters in Property Values
Because semicolons and commas have structural meaning in vCard syntax, literal semicolons and commas within property values must be escaped with a backslash. The rule is: \; represents a literal semicolon, \, represents a literal comma, \\ represents a literal backslash, and \n or \N represents a line break within the value.
This matters most in the NOTE and ADR properties. A note that contains the text “Meeting at 3pm; bring laptop” is stored as NOTE:Meeting at 3pm\; bring laptop. Without the backslash, the parser would interpret everything after the semicolon as a parameter rather than part of the note content.
The \n escape is used for multi-line text within a single property. A note with two paragraphs is stored as NOTE:First paragraph\nSecond paragraph. This is different from line folding: \n represents an intentional line break in the content, while line folding is a formatting mechanism that does not affect the content itself.
Structured Values: How ADR and N Work
Most properties have a single text value, but two important properties use semicolon-separated structured values with a fixed number of components: N (name) and ADR (address).
The N property has five components: N:LastName;FirstName;MiddleName;Prefix;Suffix. The example N:Garcia;Maria;Elena;Dr.; means last name “Garcia”, first name “Maria”, middle name “Elena”, prefix “Dr.”, and no suffix. Empty components are indicated by consecutive semicolons. The line N:Smith;John;;; means no middle name, no prefix, and no suffix.
The ADR property has seven components: ADR:POBox;ExtAddress;Street;City;Region;PostalCode;Country. The example ADR;TYPE=HOME:;;42 Oak Lane;Portland;OR;97201;USA has an empty PO Box, empty extended address, and then the street through country. The first two components are almost always empty in modern usage, which is why most addresses start with two semicolons after the colon.
Quoted-Printable and Base64 Encoding
In vCard 2.1 files, non-ASCII characters are often stored using quoted-printable (QP) encoding. Each byte outside the ASCII range is represented as an equals sign followed by two hexadecimal digits. The property FN;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:M=C3=BCller decodes to “Muller” (with the umlaut). The =C3=BC sequence is the UTF-8 byte representation of the u-umlaut character.
In QP encoding, a line ending with = (equals sign as the last character) indicates a soft line break, meaning the value continues on the next line. This is different from vCard line folding (where the continuation starts with a space). Both mechanisms can appear in the same file, and they must be processed in the correct order: unfold vCard lines first, then decode QP encoding.
Base64 encoding is used for binary data, primarily contact photos. The ENCODING=b or ENCODING=BASE64 parameter signals that the value is Base64-encoded binary data. This encoding converts binary data into ASCII text using a 64-character alphabet, making it safe to store in a text file. See the next section for how photos use Base64 in practice.
How Photos Are Stored in VCF Files
Contact photos appear as PHOTO properties with Base64-encoded image data. In vCard 3.0, the syntax is: PHOTO;ENCODING=b;TYPE=JPEG: followed by the Base64 string. This string can be thousands of characters long, spanning dozens of folded lines. A single contact photo can account for 80% or more of a contact’s total data in the VCF file.
In vCard 4.0, photos can also be stored as URL references: PHOTO;MEDIATYPE=image/jpeg:https://example.com/photo.jpg. Google Contacts exports use this format. The photo is not embedded in the file; instead, the URL points to the image hosted online. This keeps the VCF file small but means the photo is unavailable without internet access and is lost if the URL becomes invalid.
Grouped Properties: The item1 Prefix Pattern
Apple’s contact system uses a grouping mechanism where related properties share a numeric prefix. The line item1.TEL:+1-555-300-4000 is paired with item1.X-ABLabel:Emergency to indicate that this phone number has a custom label “Emergency”. The “item1.” prefix groups the two properties together.
This pattern is not part of the core vCard specification but is allowed by it (the spec permits group prefixes). Apple uses it extensively for custom labels, social profiles, and related names. Non-Apple platforms generally ignore the group prefix and process the property as if it were TEL:+1-555-300-4000, which means the custom label is lost during import. This is one of the main causes of missing fields after VCF import between Apple and other platforms.
Multi-Contact Files: BEGIN/END as Delimiters
A VCF file can contain any number of contacts. Each contact is wrapped between BEGIN:VCARD and END:VCARD markers. A multi-contact file simply places these blocks one after another with no separator between them. The end of one contact (END:VCARD) is immediately followed by the beginning of the next (BEGIN:VCARD).
When parsing a multi-contact file, the parser reads lines sequentially and uses BEGIN:VCARD to start a new contact record and END:VCARD to close it. Any property encountered between these markers belongs to that contact. If a file is missing an END:VCARD marker, the parser cannot determine where one contact ends and the next begins, which typically causes all subsequent contacts to fail or be merged into one. For techniques to handle multi-contact files, see our guide on splitting VCF files.
How Version Affects Property Syntax
The VERSION property (which must be the first or second line after BEGIN:VCARD) determines which syntax rules apply to the rest of the contact. In vCard 2.1, TYPE parameters omit the TYPE= prefix (TEL;CELL: instead of TEL;TYPE=CELL:), and non-ASCII values use ENCODING=QUOTED-PRINTABLE with CHARSET declarations. In vCard 3.0, TYPE= prefixes are used, encoding is assumed to be UTF-8, and ENCODING=b is used for binary data. In vCard 4.0, UTF-8 is mandatory, VALUE=uri is used for phone numbers and URLs, and MEDIATYPE replaces the TYPE parameter for photos.
Mixing syntax from different versions in a single contact is a common source of parsing errors. If a vCard 3.0 file contains vCard 2.1-style properties (without TYPE= prefixes), strict parsers may reject the contact. If you encounter a file with mixed version syntax, converting to a consistent version resolves most issues. Our vCard version conversion guide covers this process.
Frequently Asked Questions
How can I tell which version a VCF file uses?
Look for the VERSION property near the top of each contact block. It will be VERSION:2.1, VERSION:3.0, or VERSION:4.0. In multi-contact files, different contacts can use different versions, so check each BEGIN:VCARD block individually.
Why does my VCF file have lines starting with a space?
Lines starting with a space or tab are continuation lines (line folding). The content belongs to the property on the previous line. When processing the file, join the continuation to the previous line after removing the leading whitespace and the line break.
What does the equals sign at the end of a line mean?
In quoted-printable encoding (vCard 2.1 files), a trailing equals sign is a soft line break indicating the value continues on the next line. This is separate from vCard line folding. Decode by removing the equals sign and the line break, then joining the lines before decoding the QP sequences.
Can I safely edit a VCF file in a text editor?
Yes, but be careful with encoding and escaping. Save the file with UTF-8 encoding (without BOM). Escape semicolons and commas in values with backslashes. Do not break Base64 photo blocks. Keep the BEGIN:VCARD and END:VCARD structure intact. Use a VCF viewer to verify the file after editing.
Why do some properties have “item1.” or “item2.” prefixes?
These are group prefixes used by Apple’s contact system to associate related properties. For example, item1.TEL and item1.X-ABLabel are grouped to assign a custom label to a phone number. Non-Apple platforms usually ignore the group prefix and may lose the associated label during import.
Conclusion
Last verified: February 2026. Syntax examples verified against RFC 6350 (vCard 4.0), RFC 2426 (vCard 3.0), and vCard 2.1 specification. Parsing behavior tested with real VCF files exported from Google Contacts, iCloud, Outlook 365, and Samsung Galaxy devices.
Every VCF file follows the same structural rules: properties with parameters separated by semicolons, values after the colon, line folding for long lines, backslash escaping for special characters, and BEGIN/END markers for contact boundaries. Understanding these rules lets you debug import errors by inspecting the raw file, write correct parsers for automated processing, and manually fix corrupted contacts when software tools cannot.
The five things that trip up most people when reading VCF files: line folding (continuation lines start with a space), escaped semicolons (\; is a literal semicolon, not a parameter separator), quoted-printable encoding (=C3=BC is not garbled text but encoded bytes), structured values (N and ADR have fixed component positions separated by semicolons), and grouped properties (item1. prefixes link related properties together).
