2020-03-31 16:25:11 -04:00
<?xml version='1.0' encoding='UTF-8'?>
< !DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep >
<header >
<title > Reminders</title>
<abstract > This specification provides a way to set up reminders.</abstract>
&LEGALNOTICE;
<number > 0435</number>
2021-07-13 04:20:20 -04:00
<status > Deferred</status>
2020-03-31 16:25:11 -04:00
<type > Standards Track</type>
<sig > Standards</sig>
<approver > Council</approver>
<dependencies >
<spec > XMPP Core</spec>
<spec > XEP-0082</spec>
</dependencies>
<supersedes />
<supersededby />
<shortname > NOT_YET_ASSIGNED</shortname>
<author >
<firstname > Marcos</firstname>
<surname > De Vera Piquero</surname>
<email > marcos@tenak.net</email>
<jid > marcos@tenak.net</jid>
</author>
<revision >
<version > 0.1.0</version>
<date > 2020-03-31</date>
<initials > XEP Editor (jsc)</initials>
<remark > Accepted by vote of Council on 2020-03-04.</remark>
</revision>
<revision >
<version > 0.0.1</version>
<date > 2020-02-17</date>
<initials > mdvp</initials>
<remark > <p > Initial version</p> </remark>
</revision>
</header>
<section1 topic= 'Introduction' anchor= 'intro' >
<p > It is sometimes useful, while reading some conversations, to be
reminded about it at some point in the future. This specification
proposes a mechanism to allow clients to set up such reminders.</p>
</section1>
<!-- <section1 topic='Requirements' anchor='reqs'> -->
<!-- <p>STRONGLY RECOMMENDED.</p> -->
<!-- </section1> -->
<section1 topic= 'Glossary' anchor= 'glossary' >
<dl >
<di >
<dt > Reminder</dt>
<dd >
An automatically generated message addressed to an entity sent
at a given time. Its goal is to remind the creating entity
about something.
</dd>
</di>
</dl>
</section1>
<section1 topic= 'Requirements' anchor= 'requirements' >
<p > This protocol requires handling of dates and times, as such it conforms to &xep0082; .</p>
</section1>
<section1 topic= 'Discovering support' anchor= 'disco' >
<p > An entity may wish to discover if a service supports the Reminders feature; in order to do so, it sends a service discovery information query to the server..</p>
<example caption= 'Client requests information about a server' > < ![CDATA[
<iq from= 'juliet@capulet.net/balcony'
id='disco1'
to='capulet.net'
type='get'>
<query xmlns= 'http://jabber.org/protocol/disco#info' />
</iq> ]]></example>
<p > If the server supports the Reminders feature, it MUST specify the
'urn:xmpp:reminders:0' feature in its service discovery information
features as specified in &xep0030; </p>
<example caption= 'Server advertises support for reminders' > < ![CDATA[
<iq to= 'juliet@capulet.net/balcony' id= 'disco1' from= 'capulet.net'
type='result'>
<query xmlns= 'http://jabber.org/protocol/disco#info' >
…
<feature var= 'urn:xmpp:reminders:0' />
…
</query>
</iq> ]]></example>
</section1>
<section1 topic= 'Use Cases' anchor= 'usecases' >
<p > For end users, this provides a way to be reminded about stuff
while being in a conversation, without the need to leave it and go
to some calendar application or similar and create a full event
there. By setting a reminder, a user will be notified by the server
at whatever given time the reminder is created with and with
whatever the description was set for such a reminder.</p>
<section2 topic= 'Creating a reminder' anchor= 'creating' >
<p > A user wants to create a new reminder. For creating a
reminder, an entity MUST send an IQ stanza with the 'type'
attribute with a value of "set" and a direct < reminder/>
child qualified by the "urn:xmpp:reminders:0" namespace.</p>
<example caption= 'User creates a new reminder' > < ![CDATA[
<iq from= 'juliet@capulet.net/balcony'
to='capulet.net'
id='abc123'
type='set'>
<reminder xmlns= 'urn:xmpp:reminders:0' >
<date > 2020-02-19T23:41:00Z</date>
<text xml:lang= 'en' > Please go sleep before it's too late</text>
</reminder>
</iq> ]]> </example>
<example caption= 'Server acknowledges the reminder creation' > < ![CDATA[
<iq id= 'abc123'
to='juliet@capulet.net/balcony'
from='capulet.net'
type='result'>
<reminder xmlns= 'urn:xmpp:reminders:0' id= 'd414cec2-5369-11ea-9455-8b8d265047d9' >
<date > 2020-02-19T23:41:00Z</date>
<text xml:lang= 'en' > Please go sleep before it's too late</text>
</reminder>
</iq> ]]></example>
<p > Whenever the reminder's data sent by a client is not complete or
in an invalid format, the server MUST send an error stanza of type
'modify' and a 'bad-request' condition.</p>
<example caption= 'Server sends a bad-request error response' > < ![CDATA[
<iq id= 'bad1'
to='capulet.net'
from='juliet@capulet.net/balcony'
type='set'>
<reminder xmlns= 'urn:xmpp:reminders:0' >
<date > Tomorrow at noon</date>
<text xml:lang= 'en' > Lunch at Romeo's</text>
</reminder>
</iq>
<iq id= 'bad1'
to='juliet@capulet.net/balcony'
from='capulet.net'
type='error'>
<error type= 'modify' >
<bad-request xmlns= 'urn:ietf:params:xml:ns:xmpp-stanzas' />
</error>
</iq> ]]></example>
<p > In the event of a client trying to set a reminder in the
past, the server MUST send an error stanza of type 'modify' and
a 'gone' condition.</p>
<example caption= 'Server sends a gone error response' > < ![CDATA[
<iq id= 'bad2'
to='capulet.net'
from='juliet@capulet.net/balcony'
type='set'>
<reminder xmlns= 'urn:xmpp:reminders:0' >
<date > 2000-01-01T00:00:00Z</date>
<text xml:lang= 'en' > New Year's party</text>
</reminder>
</iq>
<iq id= 'bad2'
to='juliet@capulet.net/balcony'
from='capulet.net'
type='error'>
<error type= 'modify' >
<gone xmlns= 'urn:ietf:params:xml:ns:xmpp-stanzas' />
</error>
</iq> ]]></example>
</section2>
<section2 topic= 'Server sends a reminder' anchor= 'send' >
<p > Whenever the time for a reminder arrives, the server MUST send
a message with the reminder to the creating entity.</p>
<example caption= 'Server sends a reminder' > < ![CDATA[
<message from= 'capulet.net' to= 'juliet@capulet.net/balcony' id= 'reminder1' >
<reminder xmlns= 'urn:xmpp:reminders:0' id= 'd414cec2-5369-11ea-9455-8b8d265047d9' >
<date timezone= 'UTC' > 2020-02-19T23:41:00Z</date>
<text xml:lang= 'en' > Please go sleep before it's too late</text>
</reminder>
</message> ]]></example>
<p > After sending a reminder, the server MAY choose to delete it
from its storage.</p>
</section2>
<section2 topic= 'Client cancels a reminder' anchor= 'cancel' >
<p > There may be the case where a user wants to cancel an already
set reminder. To do so, the client MUST send an IQ stanza of
type 'set' with a 'reminder' child containing the 'id' attribute
of the reminder to be deleted, without any additional child.</p>
<example caption= 'Client deletes a reminder' > < ![CDATA[
<iq id= 'abc2'
from='juliet@capulet.net/balcony'
to='capulet.net'
type='set'>
<reminder xmlns= 'urn:xmpp:reminders:0' id= 'd414cec2-5369-11ea-9455-8b8d265047d9' />
</iq> ]]></example>
<example caption= 'Server acknowledges a reminder deletion' > < ![CDATA[
<iq id= 'abc2'
to='juliet@capulet.net/balcony'
from='capulet.net'
type='result'>
<reminder xmlns= 'urn:xmpp:reminders:0' id= 'd414cec2-5369-11ea-9455-8b8d265047d9' />
</iq> ]]></example>
</section2>
</section1>
<section1 topic= 'Internationalization Considerations' anchor= 'i18n' >
<p > As stated in the requirements, the 'date' element MUST contain
a valid &xep0082; DateTime value.</p>
</section1>
<section1 topic= 'Security Considerations' anchor= 'security' >
<p > This document introduces no additional security considerations
above and beyond those defined in the documents on which it
depends.</p>
</section1>
<section1 topic= 'IANA Considerations' anchor= 'iana' >
<p > No interaction with &IANA; is required as a result of this document.</p>
</section1>
<section1 topic= 'XMPP Registrar Considerations' anchor= 'registrar' >
<p > This specification defines the following XML namespace:</p>
<ul >
<li > urn:xmpp:reminders:0</li>
</ul>
<p > Upon advancement of this specification from a status of
Experimental to a status of Draft, the ®ISTRAR; shall add the
foregoing namespace to the registry located at &NAMESPACES; , as
described in Section 4 of &xep0053; .</p>
</section1>
<section1 topic= 'XML Schema' anchor= 'schema' >
<p > TODO</p>
</section1>
</xep>