<di><dt><value/></dt><dd>The XML character data of this element defines the default value for the field (according to the form-processing entity) in a data form of type "form", the data provided by a form-submitting entity in a data form of type "submit", or a data result in a data form of type "result". In data forms of type "form", if the form-processing entity provides a default value via the <value/> element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one <value/> element; all other field types MUST NOT contain more than one <value/> element.</dd></di>
<di><dt><option/></dt><dd>One of the options in a field of type "list-single" or "list-multi". The XML character of the <value/> child defines the option value, and the 'label' attribute defines a human-readable name for the option. The <option/> element MUST contain one and only one <value/> child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an <option/> element.</dd></di>
</dl>
<p>If the <field/> element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The <field/> element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each <field/> element SHOULD possess a 'type' attribute that defines the data "type" of the field data (if no 'type' is specified, the default is "text-single"); fields provided in the context of other forms types MAY possess a 'type' attribute as well. For data forms of type "submit", inclusion of the 'type' attribute is OPTIONAL, since the form-processing entity is assumed to understand the data types associated with forms that it processes.</p>
<p>If the <field/> element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The <field/> element MAY possess a 'label' attribute that defines a human-readable name for the field.</p>
<p>The 'type' attribute defines the data "type" of the field data. The following rules apply for that attribute:</p>
<ul>
<li>For data forms of type "form", each <field/> element SHOULD possess a 'type' attribute. If the 'type' attribute is absent, the default of "text-single" is to be applied.</li>
<li>For data forms of type "submit", "result" or "error", the recieving entity can infer the 'type' attribute value from context. Nevertheless, the 'type' attribute MAY be present for clarity. Note that forms of type "error" SHOULD NOT have any <field/> elements.</li>
</ul>
<p>If fields are presented in a user interface (e.g., as items in a questionnaire or form result), the order of the field elements in the XML SHOULD determine the order of items presented to the user.</p>
<abstract>This specification defines an XML data format for use by XMPP clients in storing bookmarks to mult-user chatrooms and web pages. The chatroom bookmarking function includes the ability to auto-join rooms on login.</abstract>
<abstract>This document defines a protocol to query and control an archive of messages stored on a server.</abstract>
&LEGALNOTICE;
<number>0313</number>
<status>Deferred</status>
<status>Experimental</status>
<lastcall>2017-11-15</lastcall>
<type>Standards Track</type>
<sig>Standards</sig>
@ -28,6 +28,24 @@
</schemaloc>
&mwild;
&ksmith;
<revision>
<version>0.7.1</version>
<date>2020-08-04</date>
<initials>rufferson</initials>
<remark>
<p>Fix missing part of sentence to make more sense</p>
</remark>
</revision>
<revision>
<version>0.7.0</version>
<date>2020-03-20</date>
<initials>mw</initials>
<remark>
<p>Add 'before-id' and 'after-id' fields, flipped pages, single-item retrieval and a new mandatory disco feature</p>
<p>Split preferences protocol into a separate document</p>
<p>Split the details of pubsub archives into a separate document</p>
</remark>
</revision>
<revision>
<version>0.6.3</version>
<date>2018-07-16</date>
@ -176,9 +194,9 @@
<li>The remote JID that the stanza is to (for an outgoing message) or from (for an
incoming message).</li>
<li>A server-assigned UID that MUST be unpredictable and unique within the archive.</li>
<li>The message stanza itself. The entire original stanza SHOULD be stored, but at a
minimumonlythe&BODY; tag MUST be preserved (ie. the server might, at its
discretion, strip certain extensions from messages before storage).</li>
<li>The message stanza itself. The entire original stanza SHOULD be stored, but at a minimum only the &BODY; tag MUST
be preserved (ie. the server might, at its discretion, strip certain extensions from messages before storage), in
addition to all standard attributes of the stanza (e.g. to, from, type, id).</li>
</ul>
<p>Note that 'incoming' and 'outgoing' messages are viewed within the context of the archived JID, rather than the system as a whole. For example, if romeo@montegue.lit sent a message to juliet@capulet.lit, it would be an outgoing message in the context of archiving for Romeo, and an incoming message in the context of archiving for Juliet.</p>
<section2topic='Order of messages'anchor='archive_order'>
<p>While this document talks about 'clients' and 'servers', as these are the common cases, the querying entity (referred to as a 'client') need not be an XMPP client as defined by RFC6120, but could potentially be any type of entity, and the queried entity (referred to as a 'server') need not be an XMPP server as defined by RFC6120, although access controls might prohibit any given entity from being able to access an archive.</p>
@ -272,30 +287,36 @@
</iq>]]></example>
<p>To ensure that the client knows when the results are complete, the server MUST send the &IQ; result after last query result has been sent
to the client. The client can optionally include a 'queryid' attribute in their query, which allows the client to match results to their initiating query.</p>
<p>When querying a pubsub node's archive, the 'node' attribute is added to the <query> element.</p>
<examplecaption="A user queries a pubsub node's archive for messages"><![CDATA[
<examplecaption="A user queries an archive for messages"><![CDATA[
<p>By default all messages match a query, and filters are used to request a subset of the archived
messages. Filters are specified in a &xep0004; data form included with the query. The hidden FORM_TYPE field
MUST be set to this protocol's namespace, 'urn:xmpp:mam:2'. Three further fields are defined by this
MUST be set to this protocol's namespace, 'urn:xmpp:mam:2'. Six further fields are defined by this
XEP and MUST be supported by servers, though all of them are optional for the client. These fields are:</p>
<ul>
<li>start</li>
<li>end</li>
<li>with</li>
<li>before-id (*)</li>
<li>after-id (*)</li>
<li>ids (*)</li>
</ul>
<p>Servers supporting fields marked with an asterisk (*) MUST advertise the disco feature 'urn:xmpp:mam:2#extended' and clients
that depend on these fields MUST verify that the server advertises this feature before attempting to use them.</p>
<p>Other fields may be used, but are not defined in this document - the naming of new fields MUST be
consistent with the format defined in &xep0068;. Servers MUST NOT mark any fields in the form as
being required (i.e. with the data forms <required/> element), regardless of whether they are
defined in this document or elsewhere.</p>
<section3topic='Filtering by JID'anchor='filter-jid'>
<p>If a 'with' field is present in the form, it contains a JID against which to match messages. The
server MUST only return messages if they match the supplied JID. A message in a user's archive matches if the JID matches either the to or from of the message. An item in a pubsub or MUC archive matches if the publisher of the item matches the JID; note that this should only be available to entities that would already have been allowed to know the publisher of the events (e.g. this could not be used by a visitor to a semi-anonymous MUC).</p>
<p>If the 'with' field's value is the bare JID of the archive, the server must only return results where both the 'to' and 'from' match the bare JID (either as bare or by ignoring the resource), as otherwise every message in the archive would match</p>
server MUST only return messages if they match the supplied JID. A message in a user's archive matches if the JID matches either the to or from of the message. An item in a MUC archive matches if the publisher of the item matches the JID; note that this should only be available to entities that would already have been allowed to know the publisher of the events (e.g. this could not be used by a visitor to a semi-anonymous MUC).</p>
<p>To allow querying for messages the user sent to themselves, the client needs to set the 'with' attribute to the account JID. In that case, the server MUST only return results where both the 'to' and 'from' match the bare JID (either as bare or by ignoring the resource), as otherwise every message in the archive would match.</p>
<p>If 'with' is omitted, the server MUST match all messages in the selected timespan with the query,
regardless of the to/from addresses on each message.</p>
<examplecaption='Querying for all messages to/from a particular JID'><![CDATA[
<p>Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.</p>
<p>If the UID contained within an <after> or <before> element is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
<p>When the results returned by the server are complete (that is: when they have not been limited by the maximum size of the result page (either as specified or enforced by the server)), the server MUST include a 'complete' attribute on the <fin> element, with a value of 'true'; this informs the client that it doesn't need to perform further paging to retreive the requested data. If it is not the last page of the result set, the server MUST either omit the 'complete' attribute, or give it a value of 'false'.</p>
<examplecaption='Server completes a result with the last page of messages'><![CDATA[
<!-- result messages -->
<iqtype='result'id='u29303'>
<finxmlns='urn:xmpp:mam:2'complete='true'>
<setxmlns='http://jabber.org/protocol/rsm'>
<firstindex='0'>23452-4534-1</first>
<last>390-2342-22</last>
<count>16</count>
</set>
</fin>
<p>If the client already knows the UID of one or more messages it wants to fetch, it can use
the 'ids' field:</p>
<examplecaption='Fetching a specific message from the archive'><![CDATA[
<iqtype='set'id='juliet1'>
<queryxmlns='urn:xmpp:mam:2'>
<xxmlns='jabber:x:data'type='submit'>
<fieldvar='FORM_TYPE'type='hidden'>
<value>urn:xmpp:mam:2</value>
</field>
<fieldvar='ids'>
<value>28482-98726-73623</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>Sometimes (e.g. due to network or storage partitioning, or other transient errors) the server might return results to a client that are unstable (e.g. they might later change in sequence or content). In such a situation the server MUST stamp the <fin> element with a 'stable' attribute with a value of 'false'. If the server knows that the data it's serving are stable it MUST either stamp a 'stable' attribute with a value of 'true', or no such attribute. An example of when unstable might legitimately be returned is if the MAM service uses a clustered data store and a query covers a time period for which the data store has not yet converged; it the server could return best-guess results and tell the client that they may be unstable. A client SHOULD NOT cache unstable results long-term without later confirming (by reissuing appropriate queries) that they have become stable.</p>
<p>If any UID requested by the client in any of the 'before-id', 'after-id' or 'ids' form fields is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
</section3>
<section3topic='Retrieving form fields'anchor='query-form'>
<p>In order for the client find out about additional fields the server might support, it can send an iq stanza of type 'get' addressed to the archive like this:</p>
<section3topic='Retrieving form fields'anchor='query-form'>
<p>In order for the client find out about additional fields the server might support, it can send an iq stanza of type 'get' addressed to the archive like this:</p>
<p>If the client understands any of the additional fields it MAY proceed to include any of them in subsequent queries. It is not required to include any or all of the supported fields in queries.</p>
<examplecaption="Client uses two discovered query fields in a query"><![CDATA[
<p>If the client understands any of the additional fields it MAY proceed to include any of them in subsequent queries. It is not required to include any or all of the supported fields in queries.</p>
<p>A special note about the 'ids' field: this field is of type 'list-multi' which typically is used to allow the client to select from a provided list of options. In this case the list of all possible ids MUST NOT be provided by the server, as it is likely to be extremely large. Instead the server MUST include a &xep0122;<validate/> element that signals the list is open to arbitrary values provided by the client.</p>
<p>As specified in &xep0068;, names of custom fields SHOULD use Clark notation to avoid conflicts with other extensions.</p>
<examplecaption="Client uses two discovered query fields in a query"><![CDATA[
<iqtype='set'id='query4'>
<queryxmlns='urn:xmpp:mam:2'>
<xxmlns='jabber:x:data'type='submit'>
@ -485,9 +492,11 @@
</query>
</iq>
]]></example>
<p>Note that as the 'with', 'start' and 'end' fields MUST be implemented by servers, clients are able to submit forms using combinations of only these fields without needing to first fetch the form from the server and the types of these fields MUST be 'jid-single', 'text-single' and 'text-single' respectively. A server MUST NOT rely on a client having first requested the form before submitting queries</p>
</section3>
<p>Note that as the 'with', 'start' and 'end' fields MUST be implemented by servers, clients are able to submit forms using combinations of only these fields without needing to first fetch the form from the server and the types of these fields MUST be 'jid-single', 'text-single' and 'text-single' respectively. A server MUST NOT rely on a client having first requested the form before submitting queries</p>
<p>If a client includes a form field that the server does not recognise, the server MUST respond with a 'feature-not-implemented' error.</p>
</section3>
</section2>
<section2topic='Query results'anchor='results'>
<p>The server responds to the archive query by transmitting to the client all the messages
that match the criteria the client requested, subject to implementation limits. The results are sent as individual stanzas,
@ -534,6 +543,167 @@
</message>
]]></example>
</section2>
<section2topic='Paging through results'anchor='query-paging'>
<p>Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.</p>
<p>RSM does not define the behaviour of including both <before> and <after> in the same request. To retrieve a range of items between two known ids, use before-id and after-id in the query form instead.</p>
<p>If the UID contained within an <after> or <before> element is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
<examplecaption='Message id not found in archive'><![CDATA[
<p>When the results returned by the server are complete (that is: when they have not been limited by the maximum size of the result page (either as specified or enforced by the server)), the server MUST include a 'complete' attribute on the <fin> element, with a value of 'true'; this informs the client that it doesn't need to perform further paging to retreive the requested data. If it is not the last page of the result set, the server MUST either omit the 'complete' attribute, or give it a value of 'false'.</p>
<examplecaption='Server completes a result with the last page of messages'><![CDATA[
<!-- result messages -->
<iqtype='result'id='u29303'>
<finxmlns='urn:xmpp:mam:2'complete='true'>
<setxmlns='http://jabber.org/protocol/rsm'>
<firstindex='0'>23452-4534-1</first>
<last>390-2342-22</last>
<count>16</count>
</set>
</fin>
</iq>
]]></example>
<p>Sometimes (e.g. due to network or storage partitioning, or other transient errors) the server might return results to a client that are unstable (e.g. they might later change in sequence or content). In such a situation the server MUST stamp the <fin> element with a 'stable' attribute with a value of 'false'. If the server knows that the data it's serving are stable it MUST either stamp a 'stable' attribute with a value of 'true', or no such attribute. An example of when unstable might legitimately be returned is if the MAM service uses a clustered data store and a query covers a time period for which the data store has not yet converged; it the server could return best-guess results and tell the client that they may be unstable. A client SHOULD NOT cache unstable results long-term without later confirming (by reissuing appropriate queries) that they have become stable.</p>
</section3>
<section3topic='Requesting the last page'>
<p>To request the page at the end of the archive (i.e. the most recent messages), include just an empty <before/> element in the RSM part of the query. As defined by RSM, this will return the last page of the archive.</p>
<examplecaption='A request for the last page in an archive'><![CDATA[
<p>Within the returned page, all results are still in chronological order, that is, the first result you receive will be the oldest item in the page, and the last result you receive will be the last item in the archive.</p>
<p>When planning a query, a client may wish to learn the current state of the archive. This includes information about the first/last entries in the archive.</p>
<p>When the archive advertises support for 'urn:xmpp:mam:2#extended' then the archive supports queries for this metadata via an iq of type 'get' to the
archive's address, with a <metadata/> payload in the 'urn:xmpp:mam:2' namespace.</p>
<p>The server response includes a <metadata/> element containing information about the archive. This element MUST include <start/> and <end/>
elements, which each have an 'id' and XEP-0082 formatted 'timestamp of the first and last messages in the archive respectively.</p>
<p>A PubSub service offering MAM SHOULD store each of the items published to each node. When responding to MAM requests it MUST construct the message stanza within the <forwarded> element in the same manner as the notifications sent to subscribers for the item, except that specifying the 'from' 'to' and 'id' attributes are OPTIONAL. Pubsub items must be returned one per message stanza (i.e. there MUST NOT be multiple <item> elements within the <items> element).</p>
<examplecaption='Server returns a pubsub messages'><![CDATA[
<p>This specification reserves the 'node' attribute of the <query> element for use with pubsub archives. Full details of using
this protocol to query pubsub node archives are documented in [FIXME: number to be assigned to xep-pubsub-mam].</p>
</section3>
</section2>
<section2topic='IDs'anchor='business-ids'>
<p>The IDs used within an archive MUST be unique per item stored and MUST NOT be reused, even if the original item with a given ID has since been removed from the archive. If a server provides multiple archives (e.g. many user archives, or many MUC archives), the IDs do not need to be unique across all of these archives unless the server also allows a single query to be run across multiple archives (e.g. searching of all MUC rooms), discussion of which is beyond the scope of this document. These IDs are strings that servers may construct in any manner, and clients must treat as opaque strings (e.g. there is no requirement for them to be numeric, sequenced or GUIDs).</p>
<abstract>This specification describes a method to migrate to PEP based bookmarks without loosing compatibility with client that still use Private XML.</abstract>
Jonas Schäfer
3 years ago