First draft.
Nowadays, it is common to handle all kind of events through desktop computer or phone: it is useful to have them at hand, to easily share them and to have all kind of reminders.
XMPP is a good fit to handle events: it's a communication protocol, and as such it would be useful for it to have tools to handle and share events.
The only existing attempt at this point is iCal Envelope (XEP-0097)
This XEP proposes an alternative which leverage existing tools such as Publish-Subscribe (XEP-0060)
The design goals of this XEP are:
Juliet and her nurse decide to have a coffee together. Juliet knows the usual place where they're going, and thus doesn't need to add much information, she creates an event for her agenda on her XMPP client. The client creates an item on Juliet's PEP node `urn:xmpp:events:0` as follow:
An event is published on a Publish-Subscribe (XEP-0060)
This is all for the minimum required elements of an event, everything else is optional. Thus, the only required elements of an event payload are <name/>, <start/> and <end/>.
Juliet is organizing a ball, and to make things easier she uses her XMPP client to manage it. To make the event more appealing, she'll publish a nice image of the ball room as main picture of the event, and she'll publish the list of invitees. She'll also need RSVP to evaluate the number of people attending.
The event she's publishing looks as follows:
Juliet wants to be sure that this event will be a success, thus she provides a lot of information. The first 3 elements <name/>, <start/> and <end/> are the mandatory one as specified in simple event explanation, all other elements are optionals. The elements used are briefly explained below, and are more detailed in Events Data section.
The <head-picture/> element indicate where to find the head picture, or in other terms the main image used to represent the event. This image is used by clients to nicely represent the event to end-user.
<description/> elements contain human readable text to explain what the event is about.
<category/> elements are used to classify the event. This is useful to quickly give an idea of what the event is about, and for events discovery.
<location/> specify where the event takes place. It may also be used for online events.
<rsvp/> contains the form that invitees will answer to indicate if they plan to attend the event.
The 4 following elements <invitees/>, <comments/>, <blog/> and <schedule/> link to pubsub nodes respectively handling list of invitees, comments on the events, blog talking about the event, and event schedule. They are described in Linked Pubsub Nodes section.
<attachments/> elements provide any kind of files that can be useful to the event. It's used here to provide the menu for the dinner.
Finally, the <extra/> element contains a data form for any useful extra information.
Events are published to pubsub nodes. Each user may have a personal agenda on its Personal Eventing Protocol (XEP-0163)
Otherwise, a node may be published on any pubsub service. An events node SHOULD be prefixed with 'urn:xmpp:events:0/', which SHOULD be followed by an unique identifier.
A pubsub node can contain any kind of events, and it is up to the publisher to decide what to put inside. While a personal agenda will hold events related to the owning entity, an events node can be used to keep events related to a school or other organisation, to a room (e.g. to show when and by whom a room is booked), to a team, to professional appointments, etc.
This section describe the various optional elements usable as children of an <event/> element. The 3 mandatory elements <name/>, <start/> and <end/> are specified in Simple Event Explanation.
<head-picture/> element describe the image to use to represent the event to end-user. It is recommended to include it for public events as it may help to give a rough idea of the event, and to represent nicely a summary of the event. Keep in mind that the picture may be resized or cropped to fit end-user display and client's UI choices.
The element MUST contain a child <file-sharing/> element as described Stateless file sharing (XEP-0447)
It is strongly recommended to include thumbnails if the head picture is large, as the event may be displayed on any screen size.
The <description/> element is used to give an human readable text explaining the event. It is the main presentation of the event, usually highlighted below the head picture.
The description may be in plain text, in this case the <description/> MUST have a 'type' attribute with a value of "text". The element then contains the plain text description.
XHTML may also be used to provide rich description. To do so, the "xhtml" value must be used for the 'type' attribute, and the first child element of the <description/> element MUST be a <div/> element qualified by the 'http://www.w3.org/1999/xhtml' namespace. Note that the content MUST be sanitized before being shown to end-user, please check Security Considerations for some advices.
The "xml:lang" attribute SHOULD be present on each description element.
Several <description/> elements MAY be present, as long as they have distinct "type"/"xml:lang" combination. It is not mandatory to provide a text or XHTML description, and providing only one of them is valid.
It is possible to give categories to the event with the <category/> element. This is specially useful for event discovery, and to give a rought idea of what the event is about. A <category/> MUST have a 'term' attribute with a human readable word or short words combination describing the category, and SHOULD have a "xml:lang" attribute set.
Whenever possible, the <category/> SHOULD have a "wd" attribute whose value is the Wikidata Entity ID
It is often important to indicate the place where the event happens. This is done by using a <location/> element which is wrapping zero or one User Geolocation (XEP-0080)
<online/> element is used for virtual meeting using a computer. If is it the under the same <location/> element than a <geoloc/> element, the online meeting is done in parallel to the physical meeting.
There may be several <location> elements if the meeting happens in several places (either at the same time, or one after the other). If several locations are used, each <location/> element MUST have an 'id' attribute with an unique identifier. At least one of the <location/> SHOULD have an 'id' with a value of "main", indicating that it is the main meeting place (which can then be used to discover events by geographical coordinates). When the event is presented to end-user using HTML, the rendering software SHOULD set an 'id' attribute to the element showing the location with the value "location_<LOCATION_ID>" (e.g. for the "main" location, the 'id' attribute would have a value of "location_main"), this way location may then be linked in the XHTML description.
If the meeting is virtual or if a virtual meeting happens in parallel for those who can't go physically to the event, one or more <online/> elements can be used to give the instructions.
The only mandatory <online/> child element is <instructions/> which contains a human readable text explaining how to join the online meeting. The <instructions/> element SHOULD have a 'xml:lang' attribute, and several <instructions/> elements MAY be present if they have distinct 'xml:lang' attributes.
<online/> MAY have an optional <name/> child with a human readable text, this is notably useful if several online locations are used at the same time for different purpose (e.g.: global announces, lost and found, etc.). The <name/> element SHOULD have a 'xml:lang' attribute.
If the online location is on an XMPP MUC, an <x/> element qualified by the 'jabber:x:conference' namespace as described in Direct MUC Invitations (XEP-0249)
It may be useful to indicate which software is used for the meeting. This is done with the <software/> element which MUST have a 'name' attribute with the software name, SHOULD have a 'wd' attribute with Wikidata entity ID when available (see Categories section for explanation on Wikidata) as it provides a lot of machine readable useful information such as where it can be found, on which platforms it is running, etc. The <software/> SHOULD also have an 'url' attribute with the URL to the official software website as value. The 'need_install' attribute MAY be used with a value of either 'true' if the software needs to be installed or 'false' if it's not necessary (i.e. if it's accessible directly via a web resource).
The <url-data/> provide the main URL to be used to join the online meeting. It is specified in URL Address Information (XEP-0103)
RSVP is a major tools when an event is organized: it helps to check if invitees have seen the event, and to evaluate the total number of people attending. The <rsvp> element MUST contain form as specified in Data Forms (XEP-0004)
The form is the one which has to be answered by invitees, it SHOULD contain a field with a 'type' attribute of value "list-single" and a 'var' attribute of value "attending" with 3 options of respective value "maybe", "yes" and "no". This is the main field and it's the one which will be used to estimate the number of attendees. However, an event organizer MAY decide to modify the available options, for instance if the "maybe" option is not desired. This element SHOULD have a <required/> child element.
An optional field named "participants_number" MAY be used to indicate the number of attendees, including the person answering. This field has the default type of "text-single". If present, it will be used to summarize the expected number of persons participating to the event, otherwise one person per attending invitee will be assumed.
Any other field can be added to request extra information to invitees. For instance, it may be used to ask if attendees have allergies, or who is bringing what to a picnic. If a new field is added, Field Standardization for Data Forms (XEP-0068)
The answer is provided by attendees using Pubsub Attachments (XEP-0470)
<rsvp/> element SHOULD have a 'xml:lang' attribute set to the language of the labels. Several <rsvp/> elements MAY be present, in which case they MUST have distinct 'xml:lang' attributes.
To summarize RSVP answers, as explained in Pubsub Attachments (XEP-0470)
For each <rsvp/> element attached, the count is done like this:
The summary is done in an <attendees/> element qualified by the 'urn:xmpp:events:0' namespace, with a 'confirmed' attribute whose value is the number of confirmed invitees, and a 'max' attribute with the maximum number of invitees expected. If 'max' is the same number as 'confirmed' (meaning that nobody has answered "maybe"), then it may be omitted.
Due to the way Pubsub Attachments (XEP-0470)
Note that sending an RSVP with a <message/> may complicate the organisation: it's then not counted automatically in the attachments summary, and if several persons are organizing the event, they may not all check easily the participation.
Some useful external pubsub nodes can be linked to the event. Those nodes are linked through elements which always have a 'jid' attribute specifying the JID of the pubsub or Personal Eventing Protocol (XEP-0163)
<invitees/> element links to a node containing one item per invitee. This node access model MAY be different to the one of the event itself: it can for instance have a "whitelist" access model to restrict the list of invitees only to organisers. In other words, it's not because an user has access to the event item that they have necessarily access to the list of invitees. Each item of the invitees node has a simple payload with an <invitee/> element qualified by the 'urn:xmpp:events:0' namespace and whose attributes are the mandatory 'jid' with the JID of the invitee, and an optional 'name' attribute with a human readable name.
The <comments/> element link to a Microblogging Over XMPP (XEP-0277)
The <blog/> element link to a Microblogging Over XMPP (XEP-0277)
The <schedule/> element link to an events node (i.e. a node using this specification) describing the programation which will happens during the main event. Put another way, it's were information such as dinner time, talks, workshop, etc. can be added.
Several events in the schedule MAY happen at the same time or overlapping time (for instance: various talks happening in parallel in a conference), in which case the locations SHOULD be specified (e.g. in which room each talk is taking place). Schedule MAY include events with RSVP (e.g. for a workshop needing inscription).
The <attachments/> elements is used to attach all kinds of files which may be useful to the event (menu, map, badge template, and so forth). It contains one or more <file-sharing/> elements as specified by Stateless file sharing (XEP-0447)
The <extra/> element hold a data form containing any relevant extra data. The form must be specified by using a FORM_TYPE field with the value "urn:xmpp:events:extra:0" and a 'type' with the value "hidden". Below some fields are specified, a software MAY add additional field. Any new field MUST follow Field Standardization for Data Forms (XEP-0068)
The following fields may be used, if not specified otherwise their type is "text-single":
An event may link to an other one. This is often useful when ones want to participate to an event and add it to their own personal agenda
To link an external event, an <external/> element is used which MUST have the 3 following attributes: 'jid' with the JID of the pubsub service of the linked event, 'node' with the name of the pubsub node and 'item' with the ID of the linked event item.
Generally, only the 3 mandatory <name/>, <start/> and <end/> elements are specified in addition to the <external/> one, the reason being that all data of the events SHOULD be retrieved from the original event itself. The start and end time are still specified through to be sure that the event won't be automatically moved to an unapproved time spot if the original event is modified.
TODO
If a client supports the Events protocol specified in this XEP, it must advertize it by including the "urn:xmpp:events:0" discovery feature in response to a Service Discovery (XEP-0030)
Similarly, if a PEP/Pubsub service implements the summarizing of RSVP as described in RSVP Summarizing, it MUST advertise that fact by including the "urn:xmpp:events:0" discovery feature in response to a Service Discovery (XEP-0030)
TODO
TODO
TODO
TODO
Thanks to JC Brand for spelling corrections.