Introduction
jCard is vCard 4.0 written as JSON. It is defined by RFC 7095 (January 2014) as a one-to-one
mapping from the vCard data model to JSON arrays and objects, so a card converts to jCard and back without losing a property or
parameter. The media type is application/vcard+json. RFC 7095 gives no file extension, so a jCard file is usually
called .json; it is told from other JSON by its first array, ["vcard", …].
jCard is a separate format from vCard, not a variant of it: the same data, but another syntax, media type and value writing. The explorer
opens a .json file, or one with no extension, that starts with ["vcard", (or an array of such arrays), in the
jCard viewer.
Structure
A card is a two-element array: the name "vcard" and an array of properties. BEGIN and END do not
appear: the array is the card. The first property MUST be version. A property is an array of at least four elements: its
lower-case name, an object of parameters, the lower-case value type, and one or more values. A structured value (n,
adr, org, gender) is one array inside the property, with an element for each component; a component with
several values is itself an array. The group prefix of vCard becomes the group parameter.
0["vcard", [properties]]1 array…["version", {}, "text", "4.0"] first1…["fn", {}, "text", "…"] and the other propertiesrepeated
N:Perreault;Simon;;;ing. jr,M.Sc.
BDAY:--0203
TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
["n", {}, "text", ["Perreault", "Simon", "", "", ["ing. jr", "M.Sc."]]]
["bday", {}, "date-and-or-time", "--02-03"]
["tel", { "type": ["work", "voice"], "pref": "1" }, "uri", "tel:+1-418-656-9254;ext=102"]
In RFC 7095 appendix B, the jCard has ["tz", {}, "utc-offset", "-05:00"] for the vCard line TZ:-0500. The default type of
TZ is text, so converting back by section 3.4.1 gives TZ;VALUE=utc-offset:-0500, which
RFC 6350 allows (it lets TZ be reset to a UTC offset). The viewer converts it that way and shows the added VALUE in the Mapping tab.
Converting
- vCard to jCard (RFC 7095 section 3): unfold the lines, remove the vCard escapes and the RFC 6868 escapes of parameter values, then apply
JSON escaping. Names are lower case, the type comes from
VALUEor the property's default (unknownwhen neither is known), dates and times are in ISO 8601 extended form (--02-03,2009-08-08T14:30:00-05:00), the group prefix is thegroupparameter, and the structured values are arrays. - jCard to vCard (section 4):
BEGIN:VCARDandEND:VCARDare added, names written in upper case, thegroupparameter put back as a prefix (it MUST NOT appear in the vCard), vCard escapes applied, lines folded, andVALUEadded when the type is not the property's default (never forunknown).
The viewer does this conversion and reads the resulting text with the vCard viewer, so the Contacts and Properties tabs work; its Mapping tab sets each array against the content line it becomes.
Not described
The pages follow RFC 7095, read in full from rfc-editor.org (the text, the ABNF of appendix A and the example). The array mapping page has every value type and the special cases.
Known, not yet covered
- Viewer: the JSON is read with the explorer's JSON reader (its tree, its Text tab and its syntax problems), each array is checked
against RFC 7095 (the two elements of a card, the first
versionproperty, the length of a property, the lower-case names, the value types, the shape of each value, the group parameter, the components of the structured values), and the whole is converted to vCard 4.0 text and read by the vCard viewer, whose problems are shown at the array that made each line. Not done: the multi-valued parameters are checked as arrays of strings but not against the list of parameters that take a list; the dates and times are checked against the patterns of RFC 7095 section 3.5 and not against the ISO 8601 text; a file over 24 MiB is shown as JSON only. - Reference: how jCard writes a structured property that RFC 6350 does not define (
clientpidmap, with an integer and a URI) is not stated by RFC 7095; the viewer reads it as an array of two components.
Unknown
- Reference: RFC errata for RFC 7095 were not read.
Also used for
- Browser extension manifest – The JSON manifest of a browser extension: its name, permissions and scripts.
- GeoJSON – Map points, lines and areas with properties, written as JSON.
- Hugging Face model config (config.json) – config.json: a model’s architecture and sizes, read before the weights.
- Hugging Face tokenizer (tokenizer.json) – tokenizer.json: a language model’s vocabulary and tokenising rules.
- JSON Schema – A JSON document that describes and validates other JSON documents.
- JavaScript Object Notation – Text format for objects, arrays, strings, numbers and booleans.
- Lottie animation – Vector animations as JSON, exported from After Effects and played in apps and web pages.
- Visual Studio Code settings – VS Code’s settings.json: dotted setting IDs in JSON with comments.
- jCal: iCalendar in JSON – iCalendar as JSON: events, to-dos and time zones as nested arrays.
- npm package manifest (package.json) – A JavaScript package’s name, version, scripts and dependencies, in JSON.
Links
Developers
- ical.js – parser for iCalendar and vCard that produces and reads jCal and jCard (JavaScript)
- ez-vcard – vCard library with xCard and jCard support (Java)
- sabre/vobject – reads and writes iCalendar and vCard, including their XML and JSON forms (PHP)