Deferred
The 'jabber:iq:private' namespace has beendocumented inPrivate XML Storage (XEP-0049) [1] according to the historical behaviorof current implementations. However there are two backward compatibleimprovements to the protocol introduced in this standardthat increase the future useability of the protocol: matching on the fullyqualified name of the XML fragment root, and the introduction of a standardmechanism of removing stored data. Because the protocol defined herein is not identical to 'jabber:iq:private', a new namespace name is used: 'http://jabber.org/protocol/private-xml'.
This protocol is designed to provide a simple interface to XML data storageon XMPP servers. The simple interface eases the implementation burden for the mostbasic data storage use-cases (e.g. storing simple client preferences on the server).More sophisticated XML data storage protocols should be built on top of, or compatiblewith this standard.
A Jabber client can store any arbitrary XML on the server side by sending an<iq/> chunk of type "set" to the server with a <query/> child scoped by the'http://jabber.org/protocol/private-xml' namespace. The <query/> element MUST contain a single, arbitraryXML fragment. That fragment MUST be scoped by itsown namespace. Any existing data stored on the server with the same fully qualifiedelement name (tag name + namespace) is replaced by the new data.
The data can then be retrieved by sending an <iq/>of type "get" with a <query/> child scoped by the 'http://jabber.org/protocol/private-xml' namespace,which in turn MUST contain a single child element scoped by the namespace usedfor storage of that fragment. The fully qualified element name is used to locatematching XML data on the server. If no matching data is found, the server willrespond with the empty query child element and not an error.
Finally, existing data on the server can be removed by sending an <iq/>of type "set" with a <query/> child scoped by the 'http://jabber.org/protocol/private-xml' namespace andcontaining an 'action' attribute with value 'delete',which in turn MUST contain a single child element scoped by the namespace usedfor storage of that fragment. The fully qualified element name is used to locatematching XML data on the server. The server responds with a successful resultwhether a matching data fragment was found or not (it's successful because theprovided data no longer exits on the server). Deleting data using this method isindistinguishable from setting an empty XML fragment as far as the behavior thisprotoco is concerned. However, deleting data MUST remove the data from the serverwhich may be implemented differently than the case of setting the data to an emptyelement. This may have significance in the context of future advanced XML storage protocols.Using the basic private XML data storage protocol, Jabber entities can create, read, update, and deleteprivate data on the server. The data stored might beanything, as long as it is valid XML. One typical usage for this namespace is theserver-side storage of client preferences.
| get | Sent with a blank query to retrieve the private data from the server. |
| set | Sent with the private XML data contained inside of a query. |
| set action='delete' | Sent with a blank query to delete private data from the server. |
| result | Returns the private data from the server. |
| error | There was an error processing the request. The exact error can be found in the child error element. |
The root element of this namespace is query. A single childelement with a proper namespace must be included otherwise the server willrespond with error code 406. Only one element can be queried or set in asingle IQ request. However, multiple elements, each containing data,can be stored independently on the server using separate set queries.
CLIENT:<iq type="set"> <query xmlns="http://jabber.org/protocol/private-xml"> <exodus xmlns="exodus:prefs"> <defaultnick>Hamlet</defaultnick> </exodus> </query></iq>SERVER:<iq type="result" from="hamlet@shakespeare.lit/denmark" to="hamlet@shakespeare.lit/denmark" />
CLIENT:<iq type="get"> <query xmlns="http://jabber.org/protocol/private-xml"> <exodus xmlns="exodus:prefs"/> </query></iq>SERVER:<iq type="result" from="hamlet@shakespeare.lit/denmark" to="hamlet@shakespeare.lit/denmark" > <query xmlns="http://jabber.org/protocol/private-xml"> <exodus xmlns="exodus:prefs"> <defaultnick>Hamlet</defaultnick> </exodus> </query></iq>
If a user attempts to get or set http://jabber.org/protocol/private-xml data that belongs to another user, the server must return an error to the sender. The error commonly used is 503 (Service Unavailable).
CLIENT:<iq type="set" to="hamlet@shakespeare.lit"> <query xmlns="http://jabber.org/protocol/private-xml"> <exodus xmlns="exodus:prefs"> <defaultnick>Macbeth</defaultnick> </exodus> </query></iq>SERVER:<iq type="error" from="hamlet@shakespeare.lit" to="macbeth@shakespeare.lit" iq="1003"> <query xmlns="http://jabber.org/protocol/private-xml"> <exodus xmlns="exodus:prefs"> <defaultnick>Macbeth</defaultnick> </exodus> </query> <error code="503">Service Unavailable</error></iq>
If a user attempts to perform a get without providing a child element, the server should return a 406 (Not Acceptable) error:
CLIENT:<iq type="set"> <query xmlns="http://jabber.org/protocol/private-xml"/></iq>SERVER:<iq type="error" iq="1004"> <query xmlns="http://jabber.org/protocol/private-xml"/> <error code="406">Not Acceptable</error></iq>
Certain namespaces are reserved in Jabber (namespaces beginning with 'jabber:' or 'http://jabber.org/', as well as 'vcard-temp'). If a user attempts to get or set http://jabber.org/protocol/private-xml data in a reserved namespace, historically some server implementations have chosen to return an error (commonly 406 [Not Acceptable]) to the sender. Such behavior is not required in order to comply with this document, but may be encountered by clients when interacting with some current server implementations.
CLIENT:<iq type="set"> <query xmlns="http://jabber.org/protocol/private-xml"> <vCard xmlns="vcard-temp"> <FN>Hamlet</FN> </vCard> </query></iq>SERVER (optional error):<iq type="error" iq="1005"> <query xmlns="http://jabber.org/protocol/private-xml"> <vCard xmlns="vcard-temp"> <FN>Hamlet</FN> </vCard> </query> <error code="406">Not Acceptable</error></iq>
The server always replies to a properly formatted get query witha result response rather than some form of 'not found' error.for exmple, the following shows the response from a server that does not have XMLdata under the 'data' name and 'imaginary' namespace.
CLIENT:<iq type="get"> <query xmlns="http://jabber.org/protocol/private-xml"> <data xmlns="imaginary"/> </query></iq>SERVER (does not have data in "imaginary" namespace, returns empty element):<iq type="result" from="hamlet@shakespeare.lit/denmark" to="hamlet@shakespeare.lit/denmark" > <query xmlns="http://jabber.org/protocol/private-xml"> <data xmlns="imaginary"/> </query></iq>
Finally, the client can delete data from the server using the delete query action.
CLIENT:<iq type="get"> <query xmlns="http://jabber.org/protocol/private-xml" action="delete"> <exodus xmlns="exodus:prefs"/> </query></iq>SERVER (server responds with success):<iq type="result" from="hamlet@shakespeare.lit/denmark" to="hamlet@shakespeare.lit/denmark" />
| Code | Text | Description |
|---|---|---|
| 406 | Not Acceptable | The IQ get does not contain a child element or (optionally) the IQ get or set is in a reserved namespace. |
| 503 | Service Unavailable | The IQ get or set is sent to a JID other than that of the sender. |
<?xml version="1.0" encoding="UTF-8" ?><!ELEMENT query (#PCDATA)>
This document in other formats:XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2024 by theXMPP Standards Foundation (XSF).
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.
## 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. ##
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.
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).
The HTML representation (you are looking at) is maintained by the XSF. It is based on theYAML CSS Framework, which is licensed under the terms of theCC-BY-SA 2.0 license.
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.
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>.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
1. XEP-0049: Private XML Storage <https://xmpp.org/extensions/xep-0049.html>.
Note: Older versions of this specification might be available athttps://xmpp.org/extensions/attic/
@report{shigeoka2003private-xml, title = {Enhanced Private XML Storage}, author = {Shigeoka, Iain}, type = {XEP}, number = {0098}, version = {0.1}, institution = {XMPP Standards Foundation}, url = {https://xmpp.org/extensions/xep-0098.html}, date = {2003-06-25/2003-06-25},}END