From RFC 7265 (jCal), read in full from rfc-editor.org, including the ABNF of its appendix A, which the RFC calls non-normative. The iCalendar side is on the components and properties and values and parameters pages. jCal has no table of properties: any component, property or parameter, now or added later, is converted the same way, so the lists are those of RFC 5545.
The arrays
| Part | Form | Rules |
|---|---|---|
| object, component | [name, properties, components] | a fixed-length array of three elements (section 3.3); the name is lower case, the second is an array of property arrays, the third an array of component arrays; a top-level object is named vcalendar |
| stream | an array of objects | there is no stream type: several objects are a plain JSON array (section 3.2) |
| property | [name, parameters, type, value, …] | at least four elements (section 3.4): the lower-case name, the parameters object, the lower-case type identifier, then one value for a single-valued property or one for each value of a multi-valued one |
| 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.5) |
| a parameter value | a string, or an array of strings | a parameter that takes a list (delegated-to, delegated-from, member) is an array of strings; a parser MUST accept either form for a single value (section 3.5.2); the double quotes of the iCalendar form are not part of the value |
Value types
The type identifier says how the values are written (section 3.6). The dates and times are the ISO 8601 extended forms, in complete representation only: reduced accuracy MUST NOT be used.
| Type | JSON value | Example |
|---|---|---|
binary | a string, base64 (RFC 4648 section 4) | ["attach", {}, "binary", "SGVsbG8gV29ybGQh"] |
boolean | true or false | ["x-non-smoking", {}, "boolean", true] |
cal-address | a string, a URI | ["attendee", {}, "cal-address", "mailto:kewisch@example.com"] |
date | a string, YYYY-MM-DD | ["dtstart", {}, "date", "2011-05-17"] |
date-time | a string, YYYY-MM-DDTHH:MM:SS with an optional zone Z; the same leap-second and offset rules as RFC 5545 | ["dtstamp", {}, "date-time", "2012-10-17T12:00:00Z"] |
duration | a string, as in RFC 5545 | ["duration", {}, "duration", "P1D"] |
float | a JSON number | ["x-grade", {}, "float", 1.3] |
integer | a JSON number that resolves to an integer in the range RFC 5545 gives | ["percent-complete", {}, "integer", 42] |
period | an array of two strings: the start (a date-time), then the end (a date-time) or a duration | ["freebusy", { "fbtype": "FREE" }, "period", ["1997-03-08T16:00:00Z", "P1D"]] |
recur | an object of rule parts (below) | ["rrule", {}, "recur", { "freq": "DAILY", "count": 5 }] |
text | a string | ["comment", {}, "text", "hello, world"] |
time | a string, HH:MM:SS with an optional Z | ["x-time-utc", {}, "time", "12:30:00Z"] |
uri | a string, a URI | ["tzurl", {}, "uri", "http://example.org/tz/Europe-Berlin.ics"] |
utc-offset | a string, +HH:MM or -HH:MM | ["tzoffsetfrom", {}, "utc-offset", "-05:00"] |
unknown | a string: the unprocessed value text; no VALUE on the way back and no escaping other than JSON's | ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"] |
Recurrence rule object
Each rule part is a member whose key is the lower-case name (section 3.6.10). freq and wkst are strings with their
case kept; until is a date or date-time string; count and interval are single numbers; the
numeric by parts (bysecond, byminute, byhour, bymonthday,
byyearday, byweekno, bymonth, bysetpos) and byday (strings such as
"-1SU") are a number or string, or an array of them when there are several; a parser MUST understand a single value
both ways.
Special properties
geo(section 3.4.1.1): typefloat, the value one array[latitude, longitude]; written with a semicolon in iCalendar.request-status(3.4.1.2): typetext, the value an array of two or three strings (code, description, and data when there is any).- Multi-valued properties (
categories,resources,freebusy,exdate,rdate): one array element for each value, joined with commas in iCalendar.
Conversion rules
iCalendar to jCal (RFC 7265 section 3)
- Unfold the lines. Remove the iCalendar escapes (RFC 5545 and RFC 6868). Then apply JSON string escaping.
ENCODING=BASE64: keep the base64 for a BINARY value; for any other type remove the parameter and base64-decode the value.- The type is the
VALUEparameter, else the default type of the property, elseunknown.VALUEis not written into the parameters object. A parameter nobody recognises is written as a string, as text (section 5.1). - Numbers have no leading zeros or plus sign in JSON.
jCal to iCalendar (section 4)
- Unescape JSON, apply the iCalendar escapes, fold long lines. Names SHOULD be upper case. Non-binary values MUST NOT be base64 encoded.
VALUEMUST be added where the property's default type is unknown and the type is notunknown; it MAY be left out when the type is the property's default; it MUST be left out forunknown.
What the viewer reports
- a top-level value that is not an array, an object that is not named
vcalendar, a component array that does not have three elements or whose second and third are not arrays; - 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 string or not lower case or not a type this RFC defines;
- a parameter that is not a string or an array of strings, a
valueparameter, a parameter name that is not lower case; - a value that is not of the JSON form of its type (a non-integer
integer, aperiodthat is not an array of two strings, ageothat is not two numbers, a date written without hyphens, a recurrence rule that is not an object or has nofreq), several values on a property that takes one, a type the property does not take; - every problem the iCalendar viewer finds in the converted text, at the array that made the line.