vCard to JSON Converter

How vCard properties map to JSON

A vCard is a line-oriented format: each line is a property name, an optional list of parameters, and a value, and the whole card sits between BEGIN:VCARD and END:VCARD. Two of those values are structured rather than plain text. N carries five semicolon-separated components in a fixed order — family, given, additional, prefix, suffix — and ADR carries seven: post office box, extended address, street, locality, region, postal code and country. Splitting them correctly is most of what a converter has to get right, because a comma in "Ms. Ada Lovelace, PhD" is data and a semicolon is a separator.

The converter maps every card to one object. The structured name becomes a nested `name` object; the address components become `street`, `city`, `region`, `postalCode` and `country`, with the post office box and extended address folded into the street line when a card uses them. Repeatable properties — TEL, EMAIL, URL — become arrays in the order they appear, so a contact with a work line, a mobile and a fax keeps all three. Escaped characters are decoded on the way through: `\n` becomes a real line break, and `\,` and `\;` become literal commas and semicolons.

Version quirks the converter smooths over

vCard has been revised twice, and exporters disagree in ways that break naive parsers. Version 2.1 (RFC-era, still produced by older handsets and some Outlook exports) writes parameters without names — `TEL;WORK;VOICE:` and `EMAIL;INTERNET:` — and encodes accented characters as quoted-printable, so "electrónico" arrives as `electr=C3=B3nico`. Version 3.0 (RFC 2426) introduced the explicit `TYPE=` form and made FN mandatory. Version 4.0 (RFC 6350) allows quoted parameter lists such as `TYPE="work,voice"`, and writes telephone numbers as URIs: `VALUE=uri:tel:+1-202-555-0184`.

All of that is normalized here. Bare 2.1 parameters and 3.0/4.0 TYPE lists produce identical `type` strings; quoted-printable values are decoded back to UTF-8; a `tel:` or `mailto:` prefix is stripped so the value stays human-readable; and a quoted parameter containing a comma is not mistaken for a list separator. Property groups — the `item1.TEL` prefix Apple Contacts adds — are stripped, and the property name is matched case-insensitively, because exporters disagree about capitalization too.

A few things are intentionally left out. Vendor extensions (anything starting with `X-`), plus GEO, TZ, CATEGORIES, IMPP and REV, are skipped rather than dumped into the output; a PHOTO payload is dropped and flagged as described above, and LOGO is skipped entirely. If a file's last card is missing its END:VCARD — a common symptom of a truncated export — the contact is still converted rather than discarded. If the input contains no BEGIN:VCARD at all, you get an error instead of an empty array, so a wrong paste is obvious.

What to do with the JSON

The typical reason to convert a .vcf file is that something downstream speaks JSON: a CRM import, a seed file for a test database, a contact-merge script, or a deduplication pass over an address book that has drifted across three phones. Because the output is a flat array with a stable shape, it drops straight into `Array.prototype.map`, `jq`, a spreadsheet or a database import without any per-record special casing.

Two habits make the result much easier to work with. First, normalize phone numbers before you compare anything: vCard stores them exactly as the user typed them, so "+44 20 7946 0958", "020 7946 0958" and "+442079460958" are three spellings of one number, and any deduplication that skips this step will keep all three. Second, decide early which contact identity you trust — fullName is what the card displays, but the structured name object is what you sort and merge on, and plenty of exports fill in one without the other. The converter always gives you both: when a card has no FN, the display name is assembled from the structured components instead.

From here, format or re-indent the array, browse it as a tree in the JSON viewer to spot the contacts with missing fields, or push it through JSON to CSV for a spreadsheet. Everything runs in your browser — contact files are personal data, and this one never leaves the page.