jCard: The JSON Format for vCard

jCard uses ISO 8601 extended format for date/time values (e.g., "1985-04-12" instead of "19850412") because the extended format is more commonly used in Internet applications that use JSON, improving readability and compatibility with existing JSON consumers.

json

vCard grouping syntax (dot-prefixed property names) is replaced in jCard with a "group" parameter because prefixing property names would complicate JSON key handling; the parameter approach aligns with jCard's uniform key-value parameters object.

json

jCard parsers SHOULD check even known property values for structured information by considering the JSON data type of the value (array vs. primitive), as this is especially important for languages where array and string access use the same syntax.

json

Round-tripping guarantees that all components, properties, and property parameters are preserved when converting vCard to jCard and back. However, ordering of elements and case of property/parameter names will not necessarily be preserved.

json

Any unrecognized property parameter MUST be converted to a string value with its content set to the property parameter value text, treated as if it were a TEXT value.

json

Array elements within structured property values MUST have the primitive type matching the jCard type identifier. For RFC 6350 structured text values, only JSON strings are used; extensions defining structured number or boolean values MUST use JSON number or boolean types.

json

In jCard, property names MUST NOT be prefixed by a group name. Instead, grouping is achieved through a "group" parameter holding the group name. When converting vCard to jCard, the group name's case SHOULD be converted to lowercase.

json

Multi-valued parameters MUST be represented as a JSON array containing the separated string values. Single-value parameters SHOULD be represented using a single string value.

json

Parameter names MUST be in lowercase in jCard; the original case of the parameter value MUST be preserved. The VALUE parameter MUST NOT be added to the parameters object — the value type is instead signaled through the type identifier string.

json

Property names in jCard MUST be in lowercase. The vCard format specifies property names are case insensitive and recommends uppercase; jCard mandates lowercase.

json

The GROUP parameter MUST NOT be used in plain vCard (RFC 6350) or xCard; it is reserved exclusively for the jCard format to avoid collisions.

json, registry

The jCard array containing structured data MUST contain all required elements even if they are empty, mirroring vCard's requirement that the component separator MUST be specified even if the component value is missing.

json

The jCard "version" property MUST be represented in the corresponding jCard component with the same value as in the vCard ("4.0" for RFC 6350 conformant vCards), and MUST be the first element of the properties array.

json

The UNKNOWN value data type MUST NOT be used in any plain vCard (RFC 6350); it is reserved exclusively for the jCard format. When converting jCard with type "unknown" to vCard, the VALUE parameter MUST NOT be specified and the value MUST be taken over without processing.

json, registry

When converting from vCard to jCard, BEGIN and END properties MUST NOT appear as properties of the jCard object. When converting from jCard to vCard, BEGIN and END properties MUST be added to enclose the properties.

json

When converting jCard to vCard, the VALUE parameter MUST be added to properties whose default value type is unknown but which do not have jCard type identifier "unknown". The VALUE parameter MUST be omitted for properties with jCard type "unknown".

json

When converting vCard to jCard, lines MUST be unfolded first, then vCard escaping MUST be unescaped, then JSON escaping MUST be applied. The reverse order applies when converting jCard to vCard, with long lines SHOULD be folded as per RFC 6350.

json

A jCard object is a JSON array with exactly two elements: the string "vcard" as the first element, and an array of jCard properties as the second element. This structure replaces the BEGIN/END property delimiters used in vCard.

json

A new "unknown" property value type is introduced in jCard to preserve unrecognized property values during round-tripping between jCard and vCard. When a vCard property has no VALUE parameter and its default value type is not known, the value MUST be converted to a primitive JSON string with type set to "unknown".

json, interoperability-note

Each jCard property is represented as an array with four fixed elements: (1) lowercase property name string, (2) parameters object, (3) lowercase type identifier string, and (4) one or more value elements. Multi-valued properties add additional array elements beyond the fourth.

json

This document registers the "application/vcard+json" MIME media type for transfer of vCard data in JSON format. Optional parameter "version" is as defined for text/vcard in RFC 6350 Section 10.1.

json, registry

This document registers the "GROUP" parameter in the vCard Parameters registry (RFC 6350 Section 10.3.2), reserved exclusively for jCard use. It MUST NOT be used in plain vCard or xCard.

json, registry

This document registers the "UNKNOWN" value data type in the vCard Value Data Types registry (RFC 6350 Section 10.3.3), reserved exclusively for jCard use to preserve unknown property values during round-tripping.

json, registry

jCard does not change the semantic meaning of underlying vCard data and does not impose or remove security considerations that apply to the underlying data. All security considerations from RFC 6350 Section 9 and associated extensions remain applicable.

json, security

jCard inherits the security risks of JSON as discussed in RFC 4627 Section 7. A flaw in the JSON parser could impose threats not present with conventional vCard data. Use of JavaScript's eval() is only allowed using the regular expression from RFC 4627 Section 6; a native JSON parser should be preferred.

json, security

jCard boolean values use the type identifier "boolean" with a JSON boolean value (true/false). Integer values use "integer" with JSON number primitives; decimals and exponents MUST be eliminated when converting integer types back to vCard.

json

jCard date values use the type identifier "date" and represent dates in ISO 8601 extended format (e.g., "1985-04-12" instead of vCard's "19850412"). Reduced accuracy, truncated, and expanded representations follow RFC 6350 restrictions; the basic format MUST be used when the extended format is not applicable.

json

jCard time values use the type identifier "time" and use ISO 8601 extended format with colons separating hour, minute, and second (e.g., "23:20:50"). UTC offsets are permitted within time values in jCard, unlike jCal where they are not permitted.

json

jCard timestamp values use the type identifier "timestamp" and require the ISO 8601 extended format complete representation (e.g., "1985-04-12T23:20:50"). UTC offset hours and minutes are separated by ":" for ISO 8601 consistency.

json

Structured property values (e.g., ADR, N) are represented as a JSON array containing one element per text component, with empty/missing components represented by zero-length strings. A component that itself has multiple values is represented as a nested array.

json