From RFC 7095 (jCard), read in full from rfc-editor.org, including the ABNF of its appendix A, which the RFC calls non-normative. The vCard side is on the properties and versions and syntax pages. Like jCal, jCard has no table of properties: any property, now or added later, is converted the same way. The default value types below are those of RFC 6350 section 6.
The arrays
| Part | Form | Rules |
|---|---|---|
| card | ["vcard", properties] | an array of two elements (section 3.2): the string vcard and an array of property arrays; BEGIN and END MUST NOT be properties; several cards are a plain JSON array of cards |
| property | [name, parameters, type, value, …] | at least four elements (section 3.3): the lower-case name, the parameters object, the lower-case type identifier, then one value, or one for each value of a multi-valued property; the type identifier is what a parser uses to read the value |
| parameters | { "name": value, … } | an object, {} when there are none; the key is the lower-case parameter name and the value keeps its case; VALUE MUST NOT be in it (section 3.4) |
| a parameter value | a string, or an array of strings | a parameter that takes a list (sort-as, type) is an array of strings; a single-valued one SHOULD be a string; the double quotes of the vCard form are not part of the value (section 3.4.2) |
version | ["version", {}, "text", "4.0"] | MUST be present and MUST be the first property (section 3.3.1.1) |
| group | the group parameter | vCard's CONTACT.FN is ["fn", { "group": "CONTACT" }, "text", …]; a property name MUST NOT carry the group prefix; the value is not empty and holds letters, digits and hyphens; converting back, it is the prefix and the parameter is dropped (section 3.3.1.2, 7.1) |
Structured values
A property whose value is compound (n, adr, org, gender) has one value that is an array, with an element for each
component, empty ones as "" (section 3.3.1.3). A component with several values is an array in turn:
ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A.
["adr", {}, "text", ["", "", ["My Street", "Left Side", "Second Shack"], "Hometown", "PA", "18252", "U.S.A."]]
- The array MUST contain all the required elements, even if empty: seven for
adrand five forn. - The elements have the JSON type of the property's type identifier: strings for text.
- A structured value with one component SHOULD be written as the plain value;
gendermay be a plain string ("M") or an array (["F", "grrrl"]), so a parser checks the JSON type.
Value types
The type identifier says how a value is written (section 3.5). Dates and times use the ISO 8601 extended form; where that does not apply, the basic form is used.
| Type | JSON value | Examples |
|---|---|---|
text | a string | ["kind", {}, "text", "group"] |
uri | a string | ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"] |
date | a string: 1985-04-12, 1985-04, 1985, --04-12, --04, ---12 | ["bday", {}, "date", "--04-12"] |
time | a string: 23:20:50, 23:20, 23, -20:50, -20, --50, with an optional zone; seconds 60 only for a leap second; midnight is 00; no fractions; offsets are allowed here (unlike jCal) | ["x-time-offset", {}, "time", "12:30:00-08:00"] |
date-time | a date, T, a time: 1985-04-12T23:20:50Z, --04-12T23:20, ---12T23:20, 2013-08-15T09:45:00+01:00 | ["anniversary", {}, "date-time", "2013-02-14T12:30:00"] |
date-and-or-time | a date-time, a date, or a time written with a leading T | ["bday", {}, "date-and-or-time", "T12:30"] |
timestamp | a complete date-time in extended form, with an optional zone | ["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"] |
boolean | true or false | ["x-non-smoking", {}, "boolean", true] |
integer | a JSON number; a fraction or exponent MUST be removed when converting to vCard | ["x-karma-points", {}, "integer", 42] |
float | a JSON number; an exponent MUST be removed when converting to vCard | ["x-grade", {}, "float", 1.3] |
utc-offset | a string, +HH:MM or -HH:MM | ["tz", {}, "utc-offset", "-05:00"] |
language-tag | a string, one language tag (RFC 5646) | ["lang", {}, "language-tag", "de"] |
unknown | a string: the unprocessed value text; no VALUE on the way back and no escaping other than JSON's | ["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"] |
Default types of the vCard 4.0 properties (RFC 6350 section 6)
| Default type | Properties |
|---|---|
text | kind, xml, fn, nickname (a list), gender (two components), title, role, categories (a list), note, prodid, email, version; structured: n (5), adr (7), org, clientpidmap (2); tel and tz default to text and are usually reset to uri and utc-offset |
uri | source, photo, impp, geo, logo, member, related (or text), sound, uid (or text), url, key (or text), fburl, caladruri, caluri |
date-and-or-time | bday, anniversary (either may be reset to text) |
timestamp | rev |
language-tag | lang |
Conversion rules
vCard to jCard (RFC 7095 section 3)
- Unfold the lines. Remove the vCard escapes (RFC 6350 section 3.4) and the RFC 6868 escapes of parameter values. Then apply JSON escaping.
- The type is the
VALUEparameter, else the property's default type, elseunknown.VALUEis not written. An unrecognised parameter is written as a string, as text (section 5.1). - The group prefix is removed and written as the
groupparameter, its name lower-cased.
jCard to vCard (section 4)
- Add
BEGIN:VCARDandEND:VCARD. Unescape JSON, apply the vCard and RFC 6868 escapes, fold long lines. Names SHOULD be upper case. VALUEMUST be added where the default type is unknown and the type is notunknown; it MAY be left out for the default type; it MUST be left out forunknown.- The
groupparameter's value, and a dot, are put before the property name (SHOULD be upper case); the parameter itself MUST NOT appear.
What the viewer reports
- a top-level value that is not an array, a card that is not a two-element array named
vcard, a missingversionproperty or one that is not first, abeginorendproperty, a property name carrying a group prefix; - a property array with fewer than four elements, a name that is not a lower-case string, a second element that is not an object, a type that is not a lower-case string or not a type this RFC defines;
- a parameter that is not a string or an array of strings, a
valueparameter, an empty or malformedgroupparameter; - a structured value that is not an array of the right length, a component that is not a string or an array of strings; a value that is not of the JSON form or the date and time form of its type; several values on a property that takes one; a type the property does not take;
- every problem the vCard viewer finds in the converted text, at the array that made the line.