Introduction
jCal is iCalendar written as JSON. It is defined by RFC 7265 (May 2014) as a one-to-one
mapping from the iCalendar data model to JSON arrays and objects, so a calendar converts to jCal and back without losing a
component, property or parameter. The media type is application/calendar+json. RFC 7265 gives no file
extension, so a jCal file is usually called .json; it is told from other JSON by its first array,
["vcalendar", …].
jCal is a separate format from iCalendar, not a variant of it: the data model is the same, but the syntax, the media type and the way
each value is written are different. The explorer opens a .json file, or one with no extension, that starts with
["vcalendar", (or a stream of such arrays), in the jCal viewer.
Structure
A calendar object is a three-element array: the name "vcalendar", an array of properties, an array of
components. Every component has the same three elements. A property is an array of at least four elements: its lower-case name, an
object of parameters ({} when there are none), the lower-case value type, and one or more values. The value type
replaces the VALUE parameter. A multi-valued property (categories, resources, freebusy,
exdate, rdate) has one element for each value; geo, request-status, a period
and a recurrence rule have structured values. There is no stream: several objects are a JSON array of them.
0["vcalendar", [properties], [components]]1 array…["prodid", {}, "text", "…"] and the other propertiesrepeated…["vevent", [properties], [components]] and the other componentsrepeated
DTSTART;TZID=US/Eastern:20060102T120000
RDATE;TZID=US/Eastern;VALUE=PERIOD:20060102T150000/PT2H
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
["dtstart", { "tzid": "US/Eastern" }, "date-time", "2006-01-02T12:00:00"]
["rdate", { "tzid": "US/Eastern" }, "period", ["2006-01-02T15:00:00", "PT2H"]]
["rrule", {}, "recur", { "freq": "YEARLY", "byday": "-1SU", "bymonth": 10 }]
The array of the second example in RFC 7265 appendix B writes the period as one string and the second byday as
1SU; the RFC text (section 3.6.9) says a period is an array of two strings, and its own iCalendar example has
-1SU. The viewer reports the string period and reads the value as written.
Converting
- iCalendar to jCal (RFC 7265 section 3): unfold the lines, remove the iCalendar escapes of text and the RFC 6868 escapes of
parameter values, then apply JSON escaping. Names are lower case, the value type comes from
VALUEor the property's default (and isunknownwhen neither is known), dates and times are in ISO 8601 extended form, numbers and booleans are JSON numbers and booleans. - jCal to iCalendar (section 4): unescape JSON, then apply the iCalendar escapes, fold long lines, write names in upper
case, add
VALUEwhen the type is not the property's default (never forunknown), and never base64-encode a value that is not binary.
The viewer does this conversion and reads the resulting text with the iCalendar viewer, so the Events, Repeats and Time zones tabs work; its Mapping tab sets each array against the content line it becomes.
Not described
The pages follow RFC 7265, read in full from rfc-editor.org (the text, the ABNF of appendix A and both examples). 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 7265 (the length of a component and of a property, the types of the elements, the lower-case names, the value types and the shape of each value), and the whole is converted to iCalendar text and read by the iCalendar viewer, whose problems are shown at the array that made each line. Not done: a stream whose top-level array mixes objects is read object by object; the multi-valued parameters are checked as arrays of strings but not against the list of parameters that take a list; a file over 24 MiB is shown as JSON only.
- Reference: the ABNF of appendix A is described by the mapping page's prose, not reproduced.
Unknown
- Reference: RFC errata for RFC 7265 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.
- jCard: vCard in JSON – vCard 4.0 contacts as JSON: names, numbers and addresses as 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)
- biweekly – iCalendar library with xCal and jCal support (Java)
- sabre/vobject – reads and writes iCalendar and vCard, including their XML and JSON forms (PHP)