A vCard Address Has Seven Parts, and a CSV Column Has One

The semicolon that is not a separator

In a vCard the structure is carried by bare semicolons and the content escapes its own. A company called Sarl Dupont, Martin et fils is written Sarl Dupont\, Martin et fils, backslash and all, precisely so that a reader can tell that comma from a separator. The same goes for semicolons inside a value and for line breaks inside a note. Split a vCard line on a plain semicolon or comma and you tear names in half — which is why the parser here walks the line and honours the backslashes rather than calling split.

Line folding is the second trap and it is invisible in an editor. A long property is wrapped at 75 octets and continued on the next line with a leading space, so a note of 149 characters can sit across three lines and read as three broken fields to anything that splits on newlines. Unfolded properly it comes back whole, escaping intact, which is what the viewer shows and what the CSV then carries.

Which direction to take, and when

Take the CSV when the answer you want is a list: who is at which company, how many contacts have no email, which numbers still start with an old area code. A spreadsheet is the right shape for those questions and a vCard is a poor one. Take the JSON export when something else is going to read it — it keeps the phone and email lists as lists rather than joining them into one cell, which is the difference between a script that works and a script that guesses where to split.

Frequently asked questions

My imported contacts have no city or postcode. Why?

Because they went through a spreadsheet. One address column becomes one address component, and the component a rebuilt vCard uses is the street — so the city, region, postcode and country fields arrive empty even though every word is still there. If you need those fields filled, either keep the original .vcf or split the address into separate columns yourself and fill them in the destination after import.

Will the accented characters survive?

Through the tools, yes — everything is read and written as UTF-8. Where they usually break is in a spreadsheet that opens the CSV as some other encoding, which turns é into two characters before you have done anything. Open the file through your spreadsheet's import dialogue and choose UTF-8 rather than double-clicking it, and check one accented name before you edit two hundred.

Is there a version of vCard I should prefer?

3.0 is what most address books export and what everything reads, so it is the safe choice for moving contacts between applications. 4.0 is the current standard and writes some values as URIs — a phone can arrive as tel:+33612345678, prefix included — while 2.1, still produced by older phones and mail clients, marks types without an equals sign, as TEL;CELL rather than TEL;TYPE=CELL. The tools read all three; when you write, 3.0 travels furthest.