From c2364c0f26efaa38a706cded55ad55adce6748f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= Date: Tue, 13 Dec 2022 18:39:04 +0100 Subject: [PATCH] Accept inbox/events.xml as XEP-0471 --- xep-0471.xml | 576 +++++++++++++++++++++++++++++++++++++++++++++++++++ xep.ent | 1 + 2 files changed, 577 insertions(+) create mode 100644 xep-0471.xml diff --git a/xep-0471.xml b/xep-0471.xml new file mode 100644 index 00000000..5864c8b0 --- /dev/null +++ b/xep-0471.xml @@ -0,0 +1,576 @@ + + +%ents; +]> + + +
+ Events + This specification describe how to handle events with XMPP. + &LEGALNOTICE; + 0471 + Experimental + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0004 + XEP-0060 + XEP-0447 + XEP-0470 + + + + events + + Jérôme + Poisson + goffi@goffi.org + goffi@jabber.fr + + + 0.1.0 + 2022-12-13 + XEP Editor (jsc) + Accepted by vote of Council on 2022-09-28. + + + 0.0.1 + 2022-09-08 + jp +

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 &xep0097; which describe a way to wrap iCaliCalendar https://datatracker.ietf.org/doc/html/rfc5545 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 &xep0060;.

+ + +

The design goals of this XEP are:

+
    +
  • use pubsub and its access model to be able to have events either private or public, and to take advantage of the subscription mechanism
    • +
  • being able to specify simple events with minimum metadata (e.g. doctor appointment, coffee with a friend)
    • +
  • provide optional tools such as RSVP or invitees list for events organization
    • +
  • 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.)
    • +
  • group several events of same kind in a pubsub node (e.g. personal agenda, work agenda, events linked to an organization)
    • +
  • flexible enough to specify all kind of extra metadata (e.g. description, classification tags, accessibility information) and media (e.g. main picture)
    • +
  • being able to optionally link to other pubsub features such as &xep0277; blog, or a way to share picture after the event is finished
    • +
  • be extensible
    • +
+ + +
    +
  • RSVP: "Répondez s'il vous plaît", a way for event invitees to indicate whether they plan to attend the 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:

+ + + + + + + Coffee with the nurse + 2022-09-05T12:00:00Z + 2022-09-05T13:00:00Z + + + + +]]> + +

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 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 &xep0082;.

+

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:

+ + + + + + + Capulet's Ball + 2022-12-15T20:00:00Z + 2022-12-16T02:00:00Z + + + + image/jpeg + ball_room.jpg + 120354 + 1920x1080 + 2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU= + 2AfMGH8O7UNPTvUVAM9aK13mpCY= + Photo of the ball room. + + + + + + + + + + + + The Capulet familly is organizing its great annual ball! Come and enjoy the event of the year… + + +
+ The Capulet familly is organizing its great annual ball! Come and enjoy the event of the year… +
+ + + + + + + Capulet's House + Italy + 45.4181, + 10.9637 + Code for entrance gate: 0123C + + + + + + urn:xmpp:events:rsvp:0 + + + maybe + + + + + + + + + + + + + + + application/pdf + dinner_menu.pdf + 50123 + d7b7d858663d110761ac4c9b7dbc4d8408445b16be0b9cedb908a2c7b454335a + Menu for the ball dinner. + + + + + + + + + + + + + urn:xmpp:events:extra:0 + + + https://ball2022.capulet.lit + + + full + + + + + + + +]]> + +

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

+

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

+

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

+ + +

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

+

<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 &xep0249; 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 &xep0103;

+ + + + + + + + + + + Ball organisation + + + + Just click on the link to access the room. We'll be discussion about organisation of the Capulet ball. + + + + + + Join this room for any king of discussions which need to be written, and to share files. + + + + + + + + + +]]> + + + +

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

+

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, &xep0068; MUST be followed, and the 'var' attribute MUST be namespaced using &clark;.

+

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.

+

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

+ + + + + + + + + + + urn:xmpp:events:rsvp:0 + + + maybe + + + + + + + 1 + + + + + + + + + + +]]> + + + + + + + + + >urn:xmpp:events:rsvp:0 + + + yes + + + no + + + + + + + + +]]> + +

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.

+

For each <rsvp/> element attached, the count is done like this:

+
    +
  • the increment is equal to the value of the 'participants_number' field, or 1 if +
      +
    1. the 'participants_number' field is not used or not present in submitted values
      2. +
    2. the value doesn't cast to an int
      3. +
    3. the int value is lower than 1
      4. +
    +
    • +
  • if the value of 'attending' field is not set or "no", then nothing is done
    • +
  • if the value of 'attending' field is "yes", both "confirmed" and "max" are increased by the increment value
    • +
  • if the value of 'attending' field is "maybe", only "max" is increased by the increment value
    • +
+

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 &xep0470; 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 &xep0334;.

+

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.

+ + + + + >urn:xmpp:events:rsvp:0 + + + yes + + + no + + + + + +]]> + + + + +

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 &xep0163; service, and a 'node' attribute specifying the pubsub node used. The supported elements are described below.

+ +

<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 &xep0277; comments node holding comments to the event iself.

+ + +

The <blog/> element link to a &xep0277; node with a blog about the event. It is useful to keep people updated about any news or preparation information.

+ + +

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 &xep0447;.

+ + + +

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 &xep0068; and be namespaced using &clark;. All field and the form itself are optional.

+

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

+
    +
  • website: the value links to a website dedicated to the event
    • +
  • status: indicate if the event will happen for sure or if it's a tentative. The possible values are "confirmed" if the event will happen for sure, "tentative" if the event may happen dependant on some condition (e.g. number of participants, convenient date found), and "cancelled" if the event won't happen. Note that "tentative" events may be moved to another timetechnically any event can be moved to a different time, the "tentative" status just make it a stronger possibility.
    • +
  • languages: indicate the main languages that will be used during the event. The field is of type "list-multi", and each language value is an ISO 639 language code.
    • +
  • accessibility:wheelchair: indicates if the event is accessible to wheelchairs. The possible values are "full" for an event totally accessible to wheelchair, "partial" when some zones may be difficult to access, and "no" when the zone is not adapted for wheelchairs.
    • +
+ + + +

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.

+ + + + + + Capulet's Ball + 2022-12-15T20:00:00Z + 2022-12-16T02:00:00Z + + + + + +]]> + + + + + +

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 &xep0030; information request:

+ + + +]]> + + + ... + + ... + +]]> +

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 &xep0030; information request:

+ + +]]> + + + ... + + ... + +]]> + + + +

TODO

+ + + +

TODO

+ + +

TODO

+ + +

TODO

+ + +

Thanks to JC Brand for spelling corrections.

+ + diff --git a/xep.ent b/xep.ent index 3d7700f3..e07abcc2 100644 --- a/xep.ent +++ b/xep.ent @@ -1666,3 +1666,4 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates WebSocket S2S (XEP-0468) XEP-0468: WebSocket S2S <https://xmpp.org/extensions/xep-0468.html>." > Bookmark Pinning (XEP-0469) XEP-0469: Bookmark Pinning <https://xmpp.org/extensions/xep-0469.html>." > Pubsub Attachments (XEP-0470) XEP-0470: Pubsub Attachments <https://xmpp.org/extensions/xep-0470.html>." > +Events (XEP-0471) XEP-0471: Events <https://xmpp.org/extensions/xep-0471.html>." >