XEP-0471: Events

Abstract
This specification describe how to handle events with XMPP.
Author
Jérôme Poisson
Copyright
© 2022 – 2022 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status

Experimental

WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.
Type
Standards Track
Version
0.1.0 (2022-12-13)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final

1. Introduction

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) [1] which describe a way to wrap iCal [2] 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.

This XEP proposes an alternative which leverage existing tools such as Publish-Subscribe (XEP-0060) [3].

2. Requirements

The design goals of this XEP are:

3. Glossary

4. Use Cases

4.1 Creating a Simple Event

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:

Example 1. Minimal Event
<iq
  type='set'
  from='juliet@capulet.lit/chamber'
  to='juliet@capulet.lit'
  id='event1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:events:0'>
      <item>
        <event xmlns='urn:xmpp:events:0'>
          <name>Coffee with the nurse</name>
          <start>2022-09-05T12:00:00Z</start>
          <end>2022-09-05T13:00:00Z</end>
        </event>
      </item>
    </publish>
  </pubsub>
</iq>

4.1.1 explanation

An event is published on a Publish-Subscribe (XEP-0060) [3] item. Juliet publishes this event on her personal agenda, thus she uses the node 'urn:xmpp:events:0' (see events nodes). 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 XMPP Date and Time Profiles (XEP-0082) [5].

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/>.

4.2 Organizing an Event

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:

Example 2. Organising an Event
<iq
  type='set'
  from='juliet@capulet.lit/chamber'
  to='pubsub.capulet.lit'
  id='event2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:events:0/balls'>
      <item id='2022_ball'>
        <event xmlns='urn:xmpp:events:0'>
          <name xml:lang='en'>Capulet's Ball</name>
          <start>2022-12-15T20:00:00Z</start>
          <end>2022-12-16T02:00:00Z</end>
          <head-picture>
            <file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
              <file xmlns='urn:xmpp:file:metadata:0'>
                <media-type>image/jpeg</media-type>
                <name>ball_room.jpg</name>
                <size>120354</size>
                <dimensions>1920x1080</dimensions>
                <hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
                <hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
                <desc>Photo of the ball room.</desc>
                <thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.capulet.lit' media-type='image/png' width='640' height='360'/>
              </file>
              <sources>
                <url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.capulet.lit/123abc-def-456-789/ball_room.jpg' />
                <jinglepub xmlns='urn:xmpp:jinglepub:1' from='download.capulet.lit' id='123abc-def-456-789'>
                  <description xmlns='urn:xmpp:jingle:apps:file-transfer:5' />
                </jinglepub>
              </sources>
            </file-sharing>
          </head-picture>
          <description type='text' xml:lang='en'>
            The Capulet familly is organizing its great annual ball! Come and enjoy the event of the year…
          </description>
          <description type='xhtml' xml:lang='en'>
            <div xmlns='http://www.w3.org/1999/xhtml'>
                The Capulet familly is organizing its great <strong>annual ball!</strong> Come and enjoy the event of the year…
            </div>
          </description>
          <category term='ball' wd='Q478515' xml:lang=en />
          <category term='dance' wd='Q11639' xml:lang=en />
          <category term='music' wd='Q638' xml:lang=en />
          <location>
            <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
              <locality>Capulet's House</locality>
              <country>Italy</country>
              <lat>45.4181</lat>, 
              <lon>10.9637</lon>
              <text>Code for entrance gate: 0123C</text>
            </geoloc>
          </location>
          <rsvp xml:lang='en'>
            <x xmlns="jabber:x:data" type="form">
              <field var="FORM_TYPE" type="hidden">
                <value>urn:xmpp:events:rsvp:0</value>
              </field>
              <field type='list-single' label='Attending' var='attending'>
                <value>maybe</value>
                <option label='maybe'><value>maybe</value></option>
                <option label='yes'><value>yes</value></option>
                <option label='no'><value>no</value></option>
                <required/>
              </field>
            </x>
          </rsvp>
          <invitees jid='pubsub.capulet.lit' node='urn:xmpp:events:invitees:0/2022_ball' />
          <comments jid='pubsub.capulet.lit' node='urn:xmpp:microblog:0:comments/2022_ball' />
          <blog jid='pubsub.capulet.lit' node='2022_ball_blog' />
          <schedule jid='pubsub.capulet.lit' node='urn:xmpp:events:0/2022_ball_schedule' />
          <attachments>
            <file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
              <file xmlns='urn:xmpp:file:metadata:0'>
                <media-type>application/pdf</media-type>
                <name>dinner_menu.pdf</name>
                <size>50123</size>
                <hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>d7b7d858663d110761ac4c9b7dbc4d8408445b16be0b9cedb908a2c7b454335a</hash>
                <desc>Menu for the ball dinner.</desc>
              </file>
              <sources>
                <url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.capulet.lit/789abc-def-123-456/dinner_menu.pdf' />
                <jinglepub xmlns='urn:xmpp:jinglepub:1' from='download.capulet.lit' id='789abc-def-123-456'>
                  <description xmlns='urn:xmpp:jingle:apps:file-transfer:5' />
                </jinglepub>
              </sources>
            </file-sharing>
          </attachments>
          <extra>
            <x xmlns="jabber:x:data" type="result">
              <field var="FORM_TYPE" type="hidden">
                <value>urn:xmpp:events:extra:0</value>
              </field>
              <field var='website'>
                <value>https://ball2022.capulet.lit</value>
              </field>
              <field var='accessibility:wheelchair'>
                <value>full</value>
              </field>
            </x>
          </extra>
        </event>
      </item>
    </publish>
  </pubsub>
</iq>

4.2.1 explanation

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.

5. Events Nodes

Events are published to pubsub nodes. Each user may have a personal agenda on its Personal Eventing Protocol (XEP-0163) [6] 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).

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.

6. Events Data

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.

6.1 Head Picture

<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) [7]. 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.

It is strongly recommended to include thumbnails if the head picture is large, as the event may be displayed on any screen size.

6.2 Description

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.

6.3 Categories

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 [8]. 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.

6.4 Location

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) [9] <geoloc/> element and any number of <online/> elements (described below).

<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.

6.4.1 Online Location

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) [10] can be used.

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) [11]

Example 3. Online Location
<iq
  type='set'
  from='juliet@capulet.lit/chamber'
  to='pubsub.capulet.lit'
  id='event3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:events:0/ball_organisation'>
      <item>
        <event xmlns='urn:xmpp:events:0'>
          <!-- … -->

          <location>
            <online>
              <name xml:lang="en">Ball organisation</name>
              <software name='Jitsi Meet' wd='Q87849488' url='https://meet.jit.si/' need_install='false' />
              <url-data xmlns='http://jabber.org/protocol/url-data' target='https://jitsi.capulet.lit/ball_2022_organisation' />
              <instructions xml:lang='en'>
                  Just click on the link to access the room. We'll be discussion about organisation of the Capulet ball.
              </instructions>
            </online>
            <online>
              <x xmlns='jabber:x:conference' jid='ball_talks@muc.capulet.lit' />
              <instructions xml:lang='en'>
                  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>

6.5 RSVP

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) [12] and Field Standardization for Data Forms (XEP-0068) [13]. The form must be specified as explained in Field Standardization for Data Forms (XEP-0068) [13] 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".

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) [13] MUST be followed, and the 'var' attribute MUST be namespaced using Clark Notation [14].

The answer is provided by attendees using Pubsub Attachments (XEP-0470) [15]: an <rsvp/> element qualified by the 'urn:xmpp:events:0' namespace is attached to the event item, containing the submitted data.

<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.

Example 4. RSVP Form
<iq
  type='set'
  from='juliet@capulet.lit/chamber'
  to='pubsub.capulet.lit'
  id='event4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:events:0/picnics'>
      <item id='picnic_ab123'>
        <event xmlns='urn:xmpp:events:0'>
          <!-- … -->

          <rsvp>
            <x xmlns="jabber:x:data" type="form">
              <field var="FORM_TYPE" type="hidden">
                <value>urn:xmpp:events:rsvp:0</value>
              </field>
              <field type='list-single' label='Attending' var='attending'>
                <value>maybe</value>
                <option label='maybe'><value>maybe</value></option>
                <option label='yes'><value>yes</value></option>
                <option label='no'><value>no</value></option>
                <required/>
              </field>
              <field label='Number of persons comming (including you)' var='participants_number'>
                <value>1</value>
              </field>
              <field
                label='Do you have any allergy or food restriction?'
                var='{https://example.org/some_software}restrictions'
                type='text-multi' />
            </x>
          </rsvp>
            
          <!-- … -->
        </event>
      </item>
    </publish>
  </pubsub>
</iq>
Example 5. Romeo Submit his RSVP Answer
<iq from='romeo@montague.lit/123'
  id='events_5'
  to='pubsub.capulet.lit'
  type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='xmpp:pubsub.capulet.lit?;node=urn%3Axmpp%3Aevents%3A0%2Fpicnics;item=picnic_ab123'>
      <item id='romeo@montague.lit'>
        <attachments>
          <rsvp xmlns='urn:xmpp:events:0'>
            <x xmlns="jabber:x:data" type="submit">
              <field var='FORM_TYPE'>
                <value>>urn:xmpp:events:rsvp:0</value>
              </field>
              <field var='attending'>
                <value>yes</value>
              </field>
              <field var='{https://example.org/some_software}restrictions'>
                <value>no</value>
              </field>
            </x>
          </rsvp>
        </attachments>
      </item>
    </publish>
  </pubsub>
</iq>

6.5.1 RSVP Summarizing

To summarize RSVP answers, as explained in Pubsub Attachments (XEP-0470) [15], 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.

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.

Example 6. Juliet Check Current Summary of RSVP
  <iq from='pubsub.capulet.lit'
    id='events_6'
    to='juliet@capulet.lit/chamber'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <items node='urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:events:0/picnics'>
        <item id='picnic_ab123'>
          <summary xmlns='urn:xmpp:pubsub-attachments:summary:1'>
            <!-- … -->

            <attendees xmlns='urn:xmpp:events:0' confirmed='5' max='7' />

            <!-- … -->
          </summary>
        </item>
      </items>
    </pubsub>
  </iq>
  

6.5.2 Private RSVP

Due to the way Pubsub Attachments (XEP-0470) [15] is working, the normal way to answer RSVP is visible to everybody which can see the event. This is normally not a problem as people which attend the event can see by themselves who is there or not, however some persons may not want to have their RSVP or JID exposed to other participants. In this case the RSVP MAY be sent through a <message/> stanza directed to the JID of the event publisher. The RSVP is then simply put as a child of the stanza, with an optional <body/>. If not <body/> is provided or if the body in empty, The <message/> SHOULD include a <store> hint as specified in Message Processing Hints (XEP-0334) [16].

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.

Example 7. Romeo Submit a Private RSVP Answer
  <message from='romeo@montague.lit/123' to='juliet@.capulet.lit' >
    <rsvp xmlns='urn:xmpp:events:0'>
      <x xmlns="jabber:x:data" type="submit">
        <field var='FORM_TYPE'>
          <value>>urn:xmpp:events:rsvp:0</value>
        </field>
        <field var='attending'>
          <value>yes</value>
        </field>
        <field var='{https://example.org/some_software}restrictions'>
          <value>no</value>
        </field>
      </x>
    </rsvp>
    <store xmlns="urn:xmpp:hints"/>
  </message>

6.6 Linked Pubsub Nodes

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) [6] service, and a 'node' attribute specifying the pubsub node used. The supported elements are described below.

6.6.1 invitees

<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.

Example 8. Pubsub Service Returns the List of Invitees to Juliet
<iq type='result'
  from='pubsub.capulet.lit'
  to='juliet@capulet.lit/chamber'
  id='invitees_123'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='urn:xmpp:events:invitees:0/2022_ball'>
      <item id='abcdef'>
        <invitee jid='nurse@capulet.lit' name='Nurse' />
      </item>
      <item id='123456'>
        <invitee jid='tybalt@capulet.lit' name='Tybalt' />
      </item>
      <!-- … -->
    </items
    </pubsub>
  </iq>

6.6.2 comments

The <comments/> element link to a Microblogging Over XMPP (XEP-0277) [4] comments node holding comments to the event iself.

6.6.3 blog

The <blog/> element link to a Microblogging Over XMPP (XEP-0277) [4] node with a blog about the event. It is useful to keep people updated about any news or preparation information.

6.6.4 schedule

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).

6.7 Attachments

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) [7].

6.8 Extra Data

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) [13] and be namespaced using Clark Notation [14]. All field and the form itself are optional.

The following fields may be used, if not specified otherwise their type is "text-single":

6.9 External Event

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.

Example 9. Romeo Link Capulet's Ball in His Personal Agenda
<iq
  type='set'
  from='romeo@montague.lit/123'
  to='romeo@montague.lit'
  id='event_link_123'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:events:0'>
      <item>
        <event xmlns='urn:xmpp:events:0'>
          <name xml:lang='en'>Capulet's Ball</name>
          <start>2022-12-15T20:00:00Z</start>
          <end>2022-12-16T02:00:00Z</end>
          <external jid='pubsub.capulet.lit' node='urn:xmpp:events:0/balls' item='2022_ball' />
        </event>
      </item>
    </publish>
  </pubsub>
</iq>

7. Business Rules

TODO

8. Discovering Support

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) [18] information request:

Example 10. Service Discovery information request
<iq type='get'
    from='juliet@example.org/balcony'
    to='romeo@example.org/orchard'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
Example 11. Service Discovery information response
<iq type='result'
    from='romeo@example.org/orchard'
    to='juliet@example.org/balcony'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:events:0'/>
    ...
  </query>
</iq>

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) [18] information request:

Example 12. Service Discovery information request
<iq type='get'
    from='juliet@example.org/balcony'
    to='pubsub.capulet.lit'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
Example 13. Service Discovery information response
<iq type='result'
    from='pubsub.capulet.lit'
    to='juliet@example.org/balcony'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:events:0'/>
    ...
  </query>
</iq>

9. Security Considerations

TODO

10. IANA Considerations

TODO

11. XMPP Registrar Considerations

TODO

12. XML Schema

TODO

13. Acknowledgements

Thanks to JC Brand for spelling corrections.


Appendices

Appendix A: Document Information

Series
XEP
Number
0471
Publisher
XMPP Standards Foundation
Status
Experimental
Type
Standards Track
Version
0.1.0
Last Updated
2022-12-13
Approving Body
XMPP Council
Dependencies
XMPP Core, XEP-0001, XEP-0004, XEP-0060, XEP-0447, XEP-0470
Supersedes
None
Superseded By
None
Short Name
events
Source Control
HTML

This document in other formats: XML  PDF

Appendix B: Author Information

Jérôme Poisson
Email
goffi@goffi.org
JabberID
goffi@jabber.fr

Copyright

This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

1. XEP-0097: iCal Envelope <https://xmpp.org/extensions/xep-0097.html>.

2. iCalendar https://datatracker.ietf.org/doc/html/rfc5545

3. XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.

4. XEP-0277: Microblogging over XMPP <https://xmpp.org/extensions/xep-0277.html>.

5. XEP-0082: XMPP Date and Time Profiles <https://xmpp.org/extensions/xep-0082.html>.

6. XEP-0163: Personal Eventing Protocol <https://xmpp.org/extensions/xep-0163.html>.

7. XEP-0447: Stateless file sharing <https://xmpp.org/extensions/xep-0447.html>.

8. to find the ID corresponding to the term, you can either search on Wikidata itself, or check it via Wikipedia. An item entity identifier is needed, thus it should start with a "Q". IDs can also be found via Wikipedia API or Wikidata API.

9. XEP-0080: User Geolocation <https://xmpp.org/extensions/xep-0080.html>.

10. XEP-0249: Direct MUC Invitations <https://xmpp.org/extensions/xep-0249.html>.

11. XEP-0103: URL Address Information <https://xmpp.org/extensions/xep-0103.html>.

12. XEP-0004: Data Forms <https://xmpp.org/extensions/xep-0004.html>.

13. XEP-0068: Field Data Standardization for Data Forms <https://xmpp.org/extensions/xep-0068.html>.

14. Clark Notation, a syntax to allow universal names written as a URI in curly brackets followed by the local name; developed by James Clark. <http://www.jclark.com/xml/xmlns.htm>.

15. XEP-0470: Pubsub Attachments <https://xmpp.org/extensions/xep-0470.html>.

16. XEP-0334: Message Processing Hints <https://xmpp.org/extensions/xep-0334.html>.

17. technically any event can be moved to a different time, the "tentative" status just make it a stronger possibility

18. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.

Appendix H: Revision History

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

  1. Version 0.1.0 (2022-12-13)
    Accepted by vote of Council on 2022-09-28.
    XEP Editor (jsc)
  2. Version 0.0.1 (2022-09-08)

    First draft.

    jp

Appendix I: Bib(La)TeX Entry

@report{poisson2022events,
  title = {Events},
  author = {Poisson, Jérôme},
  type = {XEP},
  number = {0471},
  version = {0.1.0},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0471.html},
  date = {2022-09-08/2022-12-13},
}

END