Community articleJSON representation of an event
Added by IBM contributorIBM on September 27, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars1 comment

The Domino Calendar Service uses a JSON schema to represent events.
The Domino Calendar Service uses a JSON schema to represent an event that is designed to preserve all the properties of iCalendar. The JSON representation is derived in part from the iCalendar specification (RFC 5545). It includes many of the same property names as iCalendar but the JSON syntax may be easier to use in a web application implemented in JavaScript.

The Domino Calendar Service supports both JSON and iCalendar so you can decide which is best for your application. JSON is the default representation.

This topic provides several examples of events represented in JSON format. The following JSON representation examples are provided
  • Single Event - Simple appointment example with start and end dates and with time zone array
  • Multiple Events -
  • Event with Attendees
  • Recurring Event
  • Recurring Event with an Exception
  • Single instance of a Recurring Event

Single Event represented in JSON format

A simple example of a single JSON event is a single appointment. The following is a JSON representation example of a single event - an appointment (an event without attendees) in which the start and end dates are formatted in UTC (Coordinated Universal Time):

Example 1. Simple appointment
{
	  "events": [
	    {
	      "href": "/mail/dlawson.nsf/api/calendar/events/9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
	      "id": "9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
	      "summary": "Dentist appointment",
	      "location": "Dr. Wilson's office",
	      "description": "Don't forget to floss",
	      "start": {
	        "date": "2013-09-09",
	        "time": "17:00:00",
	        "utc": true
	      },
	      "end": {
	        "date": "2013-09-09",
	        "time": "18:00:00",
	        "utc": true
	      },
	      "class": "public",
	      "transparency": "opaque",
	      "sequence": 0,
	      "last-modified": "20130822T201533Z",
	      "x-lotus-notesversion": {
	        "data": "2"
	      },
	      "x-lotus-appttype": {
	        "data": "0"
	      }
	    }
	  ]
	}


The example includes an events array with a single entry. The event properties are defined in the following table.

Table 1. Basic event properties
Property Name TypeDescription iCalendar Property
hrefString The URL of this event resource.N/A
idStringThe universal ID of this event.UID
summaryStringThe summary (or subject) of this event.SUMMARY
locationStringThe location of this event.LOCATION
descriptionStringA detailed description of this event.DESCRIPTION
startObjectThe start date and time. DTSTART
endObjectThe end date and time. DTEND
classStringDefines the scope of the access that the calendar owner intends for information within an individual calendar entryCLASS
transparency String Defines whether an event is transparent or not to busy time searches.TRANSP
sequenceIntegerDefines the revision sequence number of the calendar component within a sequence of revisions. For example, "sequence": 0, indicates a new entry with no revisions.SEQUENCE
x-lotus-notesversionObject ... X-LOTUS-NOTESVERSION
x-lotus-apptypeObject ... X-LOTUS-APPTYPE



The example can also be represented in a more complex form by showing an appointment with a time zones array.

Example 2. Simple appointment with a time zone
{
	  "timezones": [
	    {
	      "tzid": "Eastern",
	      "standard": {
	        "start": {
	          "date": "1950-11-05",
	          "time": "02:00:00"
	        },
	        "offsetFrom": "-0400",
	        "offsetTo": "-0500",
	        "recurrenceRule": "FREQ=YEARLY;BYMONTH=11;BYDAY=1SU;BYHOUR=2;BYMINUTE=0"
	      },
	      "daylight": {
	        "start": {
	          "date": "1950-03-12",
	          "time": "02:00:00"
	        },
	        "offsetFrom": "-0500",
	        "offsetTo": "-0400",
	        "recurrenceRule": "FREQ=YEARLY;BYMONTH=3;BYDAY=2SU;BYHOUR=2;BYMINUTE=0"
	      }
	    }
	  ],
	  "events": [
	    {
	      "href": "/mail/dlawson.nsf/api/calendar/events/9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
	      "id": "9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
	      "summary": "Dentist appointment",
	      "location": "Dr. Wilson's office",
	      "description": "Don't forget to floss",
	      "start": {
	        "date": "2013-09-09",
	        "time": "13:00:00",
	        "tzid": "Eastern"
	      },
	      "end": {
	        "date": "2013-09-09",
	        "time": "14:00:00",
	        "tzid": "Eastern"
	      },
	      "class": "public",
	      "transparency": "opaque",
	      "sequence": 0,
	      "last-modified": "20130822T201533Z",
	      "x-lotus-notesversion": {
	        "data": "2"
	      },
	      "x-lotus-appttype": {
	        "data": "0"
	      }
	    }
	  ]
	}


This example includes a single time zone with an ID of "Eastern" and a single event. Notice that the event start and end properties are represented in Eastern time. Each object has a tzid property that refers back to the "Eastern" time zone.

Table 2. Time zone properties
Property Name TypeDescription iCalendar Property
tzidString The ID of this time zoneTZID
standard ObjectThe rules for observing standard time in this time zone.STANDARD
daylight ObjectThe rules for observing daylight saving time (if applicable to this time zone).DAYLIGHT



Multiple Events represented in JSON format

The following is an example of multiple events, in the form of multiple appointments and meetings, represented in JSON format. This example includes only summary properties for each event. Non-summary properties like description are omitted.

EXAMPLE 3.  Multiple events - multiple appointments/meetings
{
  "x-lotus-charset": {
    "data": "UTF-8"
  },
  "events": [
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
      "id": "9008092AE62C4C9485257BCF006F2FEC-Lotus_Notes_Generated",
      "summary": "Dentist appointment",
      "location": "Dr. Wilson's office",
      "start": {
        "date": "2013-09-09",
        "time": "17:00:00",
        "utc": true
      },
      "end": {
        "date": "2013-09-09",
        "time": "18:00:00",
        "utc": true
      },
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "x-lotus-summarydataonly": {
        "data": "TRUE"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    },
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated/20130911T220000Z",
      "id": "3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "summary": "Track workout",
      "location": "High school track",
      "start": {
        "date": "2013-09-11",
        "time": "22:00:00",
        "utc": true
      },
      "end": {
        "date": "2013-09-11",
        "time": "23:00:00",
        "utc": true
      },
      "recurrenceId": "20130911T220000Z",
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "x-lotus-summarydataonly": {
        "data": "TRUE"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    },
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/DB7E0BAC21EC322A85257BD200756E26-Lotus_Notes_Generated",
      "id": "DB7E0BAC21EC322A85257BD200756E26-Lotus_Notes_Generated",
      "summary": "Staff meeting",
      "location": "Ray's office",
      "start": {
        "date": "2013-09-12",
        "time": "13:00:00",
        "utc": true
      },
      "end": {
        "date": "2013-09-12",
        "time": "14:00:00",
        "utc": true
      },
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "x-lotus-organizer": {
        "data": "CN=Duke Lawson/O=Peaks"
      },
      "x-lotus-summarydataonly": {
        "data": "TRUE"
      },
      "x-lotus-appttype": {
        "data": "3"
      }
    }
  ]
}


Event with attendees represented in JSON format

The following is an example of an event with attendees represented in JSON format. The example shows a single event with an organizer property and an array of attendee properties. The example also contains a time zones array.

EXAMPLE 4.  Event with attendees and time zone array
{
  "x-lotus-charset": {
    "data": "UTF-8"
  },
  "timezones": [
    {
      "tzid": "Eastern",
      "standard": {
        "start": {
          "date": "1950-11-05",
          "time": "02:00:00"
        },
        "offsetFrom": "-0400",
        "offsetTo": "-0500",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=11;BYDAY=1SU;BYHOUR=2;BYMINUTE=0"
      },
      "daylight": {
        "start": {
          "date": "1950-03-12",
          "time": "02:00:00"
        },
        "offsetFrom": "-0500",
        "offsetTo": "-0400",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=3;BYDAY=2SU;BYHOUR=2;BYMINUTE=0"
      }
    }
  ],
  "events": [
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/DB7E0BAC21EC322A85257BD200756E26-Lotus_Notes_Generated",
      "id": "DB7E0BAC21EC322A85257BD200756E26-Lotus_Notes_Generated",
      "summary": "Staff meeting",
      "location": "Ray's office",
      "description": "Please email your status update 24 hours before the meeting.",
      "start": {
        "date": "2013-09-12",
        "time": "09:00:00",
        "tzid": "Eastern"
      },
      "end": {
        "date": "2013-09-12",
        "time": "10:00:00",
        "tzid": "Eastern"
      },
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "last-modified": "20130825T212457Z",
      "attendees": [
        {
          "role": "chair",
          "status": "accepted",
          "rsvp": false,
          "displayName": "Duke Lawson/Peaks",
          "email": "DukeLawson@swg.usma.ibm.com"
        },
        {
          "role": "req-participant",
          "status": "needs-action",
          "rsvp": true,
          "displayName": "Dean Melnyk/Peaks",
          "email": "DeanMelnyk@swg.usma.ibm.com"
        },
        {
          "role": "req-participant",
          "status": "needs-action",
          "rsvp": true,
          "displayName": "Raymond Chan/Peaks",
          "email": "RaymondChan@swg.usma.ibm.com"
        }
      ],
      "organizer": {
        "displayName": "Duke Lawson/Peaks",
        "email": "DukeLawson@swg.usma.ibm.com"
      },
      "x-lotus-broadcast": {
        "data": "FALSE"
      },
      "x-lotus-notesversion": {
        "data": "2"
      },
      "x-lotus-appttype": {
        "data": "3"
      }
    }
  ]
}


Recurring event represented in JSON format

The following is an example of a single recurring event in JSON format. The start and end event properties are for the first instance of the recurring event. The recurrenceRule property specifies the recurrence rule. In this case the event recurs weekly on Saturday for four weeks.

EXAMPLE 5.  Recurring event with time zone array
{
  "x-lotus-charset": {
    "data": "UTF-8"
  },
  "timezones": [
    {
      "tzid": "Eastern",
      "standard": {
        "start": {
          "date": "1950-11-05",
          "time": "02:00:00"
        },
        "offsetFrom": "-0400",
        "offsetTo": "-0500",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=11;BYDAY=1SU;BYHOUR=2;BYMINUTE=0"
      },
      "daylight": {
        "start": {
          "date": "1950-03-12",
          "time": "02:00:00"
        },
        "offsetFrom": "-0500",
        "offsetTo": "-0400",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=3;BYDAY=2SU;BYHOUR=2;BYMINUTE=0"
      }
    }
  ],
  "events": [
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "id": "3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "summary": "Track workout",
      "location": "High school track",
      "start": {
        "date": "2013-09-11",
        "time": "18:00:00",
        "tzid": "Eastern"
      },
      "end": {
        "date": "2013-09-11",
        "time": "19:00:00",
        "tzid": "Eastern"
      },
      "recurrenceRule": "FREQ=WEEKLY;COUNT=15;BYDAY=WE",
      "links": [
        {
          "rel": "instances",
          "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated/instances"
        }
      ],
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "last-modified": "20130826T145802Z",
      "x-lotus-notesversion": {
        "data": "2"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    }
  ]
}


Recurring Event with an Exception represented in JSON format

Sometimes a recurring event has exception event instances that have been modified or removed. In this case the events array will contain more than one element.

The following is an example of a recurring event with an exception in JSON format. The first element in the events array describes the overall event including its recurrence rule. The second element describes an exception that occurs on September 25. The location and description properties are different for the exception.

EXAMPLE 6.  Recurring event with an exception and time zone array
{
  "x-lotus-charset": {
    "data": "UTF-8"
  },
  "timezones": [
    {
      "tzid": "Eastern",
      "standard": {
        "start": {
          "date": "1950-11-05",
          "time": "02:00:00"
        },
        "offsetFrom": "-0400",
        "offsetTo": "-0500",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=11;BYDAY=1SU;BYHOUR=2;BYMINUTE=0"
      },
      "daylight": {
        "start": {
          "date": "1950-03-12",
          "time": "02:00:00"
        },
        "offsetFrom": "-0500",
        "offsetTo": "-0400",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=3;BYDAY=2SU;BYHOUR=2;BYMINUTE=0"
      }
    }
  ],
  "events": [
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "id": "3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "summary": "Track workout",
      "location": "High school track",
      "start": {
        "date": "2013-09-11",
        "time": "18:00:00",
        "tzid": "Eastern"
      },
      "end": {
        "date": "2013-09-11",
        "time": "19:00:00",
        "tzid": "Eastern"
      },
      "recurrenceRule": "FREQ=WEEKLY;COUNT=15;BYDAY=WE",
      "links": [
        {
          "rel": "instances",
          "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated/instances"
        }
      ],
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "last-modified": "20130826T145802Z",
      "x-lotus-notesversion": {
        "data": "2"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    },
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated/20130925T220000Z",
      "id": "3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "summary": "Track workout",
      "location": "Backup track facility",
      "description": "The high school track is being resurfaced this week",
      "start": {
        "date": "2013-09-25",
        "time": "18:00:00",
        "tzid": "Eastern"
      },
      "end": {
        "date": "2013-09-25",
        "time": "19:00:00",
        "tzid": "Eastern"
      },
      "recurrenceId": "20130925T220000Z",
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "last-modified": "20130826T145802Z",
      "x-lotus-notesversion": {
        "data": "2"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    }
  ]
}


Single instance of a Recurring Event represented in JSON format

As described in earlier sections of this topic, the service often represents a recurring event as a whole (that is, all event instances). It can also represent a single instance of a recurring event.

The next example shows an instance of the same event from the earlier example of the event with an exception. The instance occurs on September 18. It has the same id property, but it also has a recurrenceId property. The recurrenceId property lets you uniquely identify the event instance.

Example 7. Single instance of a Recurring Event
{
  "x-lotus-charset": {
    "data": "UTF-8"
  },
  "timezones": [
    {
      "tzid": "Eastern",
      "standard": {
        "start": {
          "date": "1950-11-05",
          "time": "02:00:00"
        },
        "offsetFrom": "-0400",
        "offsetTo": "-0500",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=11;BYDAY=1SU;BYHOUR=2;BYMINUTE=0"
      },
      "daylight": {
        "start": {
          "date": "1950-03-12",
          "time": "02:00:00"
        },
        "offsetFrom": "-0500",
        "offsetTo": "-0400",
        "recurrenceRule": "FREQ=YEARLY;BYMONTH=3;BYDAY=2SU;BYHOUR=2;BYMINUTE=0"
      }
    }
  ],
  "events": [
    {
      "href": "/mail/dlawson.nsf/api/calendar/events/3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated/20130918T220000Z",
      "id": "3C3F810BABFB13DA85257BD200753EF8-Lotus_Notes_Generated",
      "summary": "Track workout",
      "location": "High school track",
      "start": {
        "date": "2013-09-18",
        "time": "18:00:00",
        "tzid": "Eastern"
      },
      "end": {
        "date": "2013-09-18",
        "time": "19:00:00",
        "tzid": "Eastern"
      },
      "recurrenceId": "20130918T220000Z",
      "class": "public",
      "transparency": "opaque",
      "sequence": 0,
      "last-modified": "20130826T145802Z",
      "x-lotus-notesversion": {
        "data": "2"
      },
      "x-lotus-appttype": {
        "data": "0"
      }
    }
  ]
}

Sandro Schifferle commented on Jun 15, 2015

Incomplete Event Properties Specification

Please provide the full event properties specification which includes the properties used inside the examples:

- Attendees

- recurrenceRule

- x-lotus-notesversion (This property is listed but without a specification)

- x-lotus-apptype (This property is listed but without a specification)

- x-lotus-charset

Thanks a lot

x-lotus-charset