jCard is now a thing
Last week jCard became rfc7095. jCard specifies a way to serialize the elusive vCard as Json.
I’m a big fan of this format. vCards have been around since 1995, and even though we’ve had a pretty significant update in 2011 in the form of vCard 4.0, the format is still complicated to parse, has a number of problems that go all the way back to the early days.
Worse, a lot of people don’t really see the value of upgrading, and thus stick to using vCard 3. Or even 2.1 if you’re microsoft.
The biggest problem with vCards, is that upon a first glance, the format seems extremely easy to parse and generate with just a couple of string manipulation functions. When you dig deeper into the specifications though, you’ll notice that it’s actually really complex and hosts a ton of edge cases.
The result of this, is that there are a ton of broken vCard generators in the wild, and even more broken vCards.
jCard should solve a lot of that. The serialization rules for json are really simple, and most programming languages ship with a correct implementation. Serializing vCards as json means that there’s no longer a worry about things like escaping, new lines, and character encoding (it’s UTF-8).
So I’m hoping that the benefits of jCard will be big enough for people to eventually abandon vCard altogether. The ‘clean break’ in the format, rather than a progressive update should help ensuring that all newly generated jCards are in a much better state than some of the vCards we’re seeing.
Using it in PHP
sabre/vobject already has support for jCard for some time. To parse jCard:
<?php
$input = file_get_contents('jcard.json');
$jCard = Sabre\VObject\Reader::readJson($input, 'r');
?>
How it looks
Here’s a sample of my vCard (generated by OS X Contacts.app, but significantly shortened).
BEGIN:VCARD
VERSION:3.0
PRODID:-//Apple Inc.//Mac OS X 10.9.1//EN
N:Pot;Evert;;;
FN:Evert Pot
EMAIL;type=INTERNET;type=HOME:evert@rooftopsolutions.nl
EMAIL;type=INTERNET;type=WORK:evert@fruux.com
TEL;type=CELL;type=VOICE:+1 647 471 2661
ADR;type=HOME:;;24 Settles Street;London;;E1 1JP;United Kingdom
NOTE:Foo
item2.URL;type=pref:http://evertpot.com/
BDAY:1985-04-07
X-JABBER;type=HOME;type=pref:evertpot@gmail.com
UID:35269e7016a018e3
END:VCARD
Convering it can be done so, if you have the vObject command line utility installed:
$ vobject convert --pretty input.vcf output.json
What follows is the output, pretty-printed. As you can see the output is a lot larger, and arguably less readable. This is also the one benefit the old mime-dir based format has, it’s easy for a human to process.
[
"vcard",
[
[
"version",
{
},
"text",
"4.0"
],
[
"prodid",
{
},
"text",
"-\/\/Sabre\/\/Sabre VObject 3.1.3\/\/EN"
],
[
"n",
{
},
"text",
[
"Pot",
"Evert",
"",
"",
""
]
],
[
"fn",
{
},
"text",
"Evert Pot"
],
[
"email",
{
"type": [
"INTERNET",
"HOME"
]
},
"text",
"evert@rooftopsolutions.nl"
],
[
"email",
{
"type": [
"INTERNET",
"WORK"
]
},
"text",
"evert@fruux.com"
],
[
"tel",
{
"type": [
"CELL",
"VOICE"
]
},
"text",
"+1 647 471 2661"
],
[
"adr",
{
"type": "HOME"
},
"text",
[
"",
"",
"24 Settles Street",
"London",
"",
"E1 1JP",
"United Kingdom"
]
],
[
"note",
{
},
"text",
"Foo"
],
[
"url",
{
"pref": "1",
"group": "ITEM2"
},
"uri",
"http:\/\/evertpot.com\/"
],
[
"bday",
{
},
"date-and-or-time",
"1985-04-07"
],
[
"x-jabber",
{
"type": "HOME",
"pref": "1"
},
"unknown",
"evertpot@gmail.com"
],
[
"uid",
{
},
"text",
"35269e7016a018e3"
]
]
]
Comments
Brandon Corbin •
Ugh, is it just me or does this seem overly complicated? I was hoping for something more concise and elegant.
Evert •
Yea it does look a bit complicated ;)
This was absolutely required for a 1:1 mapping from vCard to jCard. The top-level array couldn't just be an object with properties such as 'N' and 'FN', because almost every one of them can appear more than once.
Furthermore, many properties can have multiple values, etc.. It really makes sense once you dig into the jCard and vCard formats.
It doesn't make it very human-readable, but parsing it from within javascript is from experience extremely easy.
Brandon Corbin •
Thanks for the details Evert. I am fairly well versed in the vCard format, and have always hated it. Help me understand this - If the objective was to have a clean break from the vCard format, why not just create a better JSON format that can easily be translated? I believe the human readability element is being understated, and we're just passing on the initial inelegant solution to the next evolution.
Evert •
One of the key objectives was to provide a way to allow a round-trip from vCard to jCard without loss of information, including support for things like custom properties.
A lot of discussion went into the exact structure of this. An alternative included making the top-level properties (FN, NAME and such) as real object properties, and making their values arrays in cases where they appeared more than once in the original vcard.
This would have resulted in very deep object structures. Often harder to read, and definitely harder to use when you do actually start using the format.
Completely departing from the original data model with tight rules around conversion would also have been possible, but this would have either not allowed full round-tripping, or would have added a level of complexity to the format because you need A) a simple object model for common properties, and B) a generic way to encode any custom or future property.
Basically.. it's hard.. if you have specific ideas on how this should have been done instead, I would very likely be able to point out why that didn't happen (for better or worse).
Brandon Corbin •
I have no doubt your solution was the most optimal for the requirements, nor would I be foolish enough to challenge you to a technical dual.
My issue falls more on the requirement of 1:1 round-tripping without potential loss.
Evert •
A 'technical dual' was not really my intended tone ;) Just wanted to explain the motivations really.
I agree, if round-tripping was not a requirement, I imagine the format would have looked very different.
David Chang •
We've came across the same issue on a group. This came out as a potential solution:
https://github.com/rauchg/r...
Christophe Coevoet •
@Evert FYI, the permalink is also broken for this article in the RSS feed
Evert •
It looks like it may have to do with the double // in the feed. Lets hope that that fixes things :)
Christophe Coevoet •
your new article works fine in the feed
elMestre •
I founded PHP and python libraries for vobject, but not the command line tool.
Could you say where its located please?
Evert •
The commandline tool is in the bin/ directory of the php project. We have no association with the python project.
Daniel •
It doesn’t look so bad after Python's pretty-print:
>>> print pformat(a, width=120).replace("'", '"').replace('\\\\/', '/')
["vcard",
[["version", {}, "text", "4.0"],
["prodid", {}, "text", "-//Sabre//Sabre VObject 3.1.3//EN"],
["n", {}, "text", ["Pot", "Evert", "", "", ""]],
["fn", {}, "text", "Evert Pot"],
["email", {"type": ["INTERNET", "HOME"]}, "text", "evert@rooftopsolutions.nl"],
["email", {"type": ["INTERNET", "WORK"]}, "text", "evert@fruux.com"],
["tel", {"type": ["CELL", "VOICE"]}, "text", "+1 647 471 2661"],
["adr", {"type": "HOME"}, "text", ["", "", "24 Settles Street", "London", "", "E1 1JP", "United Kingdom"]],
["note", {}, "text", "Foo"],
["url", {"group": "ITEM2", "pref": "1"}, "uri", "http://evertpot.com/"],
["bday", {}, "date-and-or-time", "1985-04-07"],
["x-jabber", {"pref": "1", "type": "HOME"}, "unknown", "evertpot@gmail.com"],
["uid", {}, "text", "35269e7016a018e3"]]]
Sahil •
hey can i find the source code for card anywhere? the parsing from card to j and back
Evert •
Well there's no source code in my post. I am just talking about the standard.
I have a PHP implementation that you can check out: http://sabre.io/vobject/json/