<p>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.</p>
<p>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.</p>
<p>The only existing attempt at this point is &xep0097; which describe a way to wrap iCal<note>iCalendar <linkurl='https://datatracker.ietf.org/doc/html/rfc5545'>https://datatracker.ietf.org/doc/html/rfc5545</link></note> data. However, this XEP never got traction, is not taking advantage of XMPP features, doesn't handle thing such as invitees and RSVP, and it not easily extensible.</p>
<li>provide optional tools such as RSVP or invitees list for events organization</li>
<li>it should be possible to optionally ask any kind of extra data in RSVP (e.g.: number of people attending, allergy information for dinner, etc.)</li>
<li>group several events of same kind in a pubsub node (e.g. personal agenda, work agenda, events linked to an organization)</li>
<li>flexible enough to specify all kind of extra metadata (e.g. description, classification tags, accessibility information) and media (e.g. main picture)</li>
<li>being able to optionally link to other pubsub features such as &xep0277; blog, or a way to share picture after the event is finished</li>
<li><strong>RSVP</strong>: "<linkurl='https://en.wikipedia.org/wiki/RSVP'>Répondez s'il vous plaît</link>", a way for event invitees to indicate whether they plan to attend the event</li>
<p>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:</p>
<p>An event is published on a &xep0060; item. Juliet publishes this event on her personal agenda, thus she uses the node 'urn:xmpp:events:0' (see <linkurl='#events_nodes'>events nodes</link>). The payload of an event is an <event/> element qualified by the namespace 'urn:xmpp:events:0'. Each event MUST have one or several <name/> elements containing a human readable short text describing the element. If several <name/> elements are used, they MUST have distinct 'xml:lang' attributes, to specify the same name in different languages. Each <event/> element MUST have a <start/> and an <end/> child elements specifying the expected start time and end time of the event by using the format explained in &xep0082;.</p>
<p>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/>.</p>
</section3>
</section2>
<section2topic='Organizing an Event'anchor='originazing-event'>
<p>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.</p>
<p>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 <linkurl='#simple-event-explanation'>simple event explanation</link>, all other elements are optionals. The elements used are briefly explained below, and are more detailed in <linkurl='#events-data'>Events Data</link> section.</p>
<p>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.</p>
<p><description/> elements contain human readable text to explain what the event is about.</p>
<p><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.</p>
<p><location/> specify where the event takes place. It may also be used for online events.</p>
<p><rsvp/> contains the form that invitees will answer to indicate if they plan to attend the event.</p>
<p>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 <linkurl='#linked_nodes'>Linked Pubsub Nodes</link> section.</p>
<p><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.</p>
<p>Finally, the <extra/> element contains a data form for any useful extra information.</p>
<p>Events are published to pubsub nodes. Each user may have a personal agenda on its &xep0163; service, by using the 'urn:xmpp:events:0' node. This node should have an access model of "whitelist" by default, however it is up to the entity holding the PEP node to use an other access model (a JID linked to an organisation may want to make public all its events from the personal agenda by using an "open" access model).</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1topic='Events Data'anchor='events-data'>
<p>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 <linkurl='#simple-event-explanation'>Simple Event Explanation</link>.</p>
<p><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.</p>
<p>The element MUST contain a child <file-sharing/> element as described &xep0447;. The image SHOULD be published in JPEG format due to its widespread support and the fact that mostly photos are expected to be used as head pictures.</p>
<p>It is strongly recommended to include thumbnails if the head picture is large, as the event may be displayed on any screen size.</p>
</section2>
<section2topic='Description'anchor='description'>
<p>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.</p>
<p>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.</p>
<p>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 <linkurl='#security'>Security Considerations</link> for some advices.</p>
<p>The "xml:lang" attribute SHOULD be present on each description element.</p>
<p>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.</p>
</section2>
<section2topic='Categories'anchor='categories'>
<p>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.</p>
<p>Whenever possible, the <category/> SHOULD have a "wd" attribute whose value is the <linkurl='https://www.wikidata.org/wiki/Wikidata:Identifiers'>Wikidata Entity ID</link>
<note>to find the ID corresponding to the term, you can either <linkurl='https://www.wikidata.org/wiki/Special:Search'>search on Wikidata itself</link>, or <linkurl='https://www.wikidata.org/wiki/Wikidata:Identifiers'>check it via Wikipedia</link>. An item entity identifier is needed, thus it should start with a "Q". IDs can also be found via <linkurl='https://www.mediawiki.org/wiki/API:Main_page'>Wikipedia API</link> or <linkurl='https://www.wikidata.org/wiki/Wikidata:Data_access'>Wikidata API</link>.</note>.
Wikidata is an open and collaborative database with over 100 million items. By specifying the Wikidata entity ID corresponding to the term, the category becomes machine readable and can be easily translated, associated to similar terms, linked to corresponding Wikipedia page in end-user language, and so on.</p>
</section2>
<section2topic='Location'anchor='location'>
<p>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 &xep0080;<geoloc/> element and any number of <online/> elements (described below).</p>
<p><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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p><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.</p>
<p>If the online location is on an XMPP MUC, an <x/> element qualified by the 'jabber:x:conference' namespace as described in &xep0249; can be used.</p>
<p>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 <linkurl='#categories'>Categories section</link> 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).</p>
Join this room for any king of discussions which need to be written, and to share files.
</instructions>
</online>
</location>
<!-- … -->
</event>
</item>
</publish>
</pubsub>
</iq>]]></example>
</section3>
</section2>
<section2topic='RSVP'anchor='RSVP'>
<p>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 &xep0004; and &xep0068;. The form must be specified as explained in &xep0068; with <field/> having a 'type' attribute with a value of "hidden", a 'var' with a value of "FORM_TYPE", and the field value MUST be "urn:xmpp:events:rsvp:0".</p>
<p>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.</p>
<p>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.</p>
<p>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, &xep0068; MUST be followed, and the 'var' attribute MUST be namespaced using &clark;.</p>
<p>The answer is provided by attendees using &xep0470;: an <rsvp/> element qualified by the 'urn:xmpp:events:0' namespace is attached to the event item, containing the submitted data.</p>
<p><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.</p>
<p>To summarize RSVP answers, as explained in &xep0470;, the number of attendees is counted with 2 values: "confirmed" which are attendees coming for sure, and "max" which is the maximum number of persons expected.</p>
<p>For each <rsvp/> element attached, the count is done like this:</p>
<ul>
<li>the increment is equal to the value of the 'participants_number' field, or 1 if
<ol>
<li>the 'participants_number' field is not used or not present in submitted values</li>
<li>the value doesn't cast to an int</li>
<li>the int value is lower than 1</li>
</ol>
</li>
<li>if the value of 'attending' field is not set or "no", then nothing is done</li>
<li>if the value of 'attending' field is "yes", both "confirmed" and "max" are increased by the increment value</li>
<li>if the value of 'attending' field is "maybe", only "max" is increased by the increment value</li>
</ul>
<p>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.</p>
<examplecaption="Juliet Check Current Summary of RSVP"><