diff --git a/inbox/udt.xml b/inbox/udt.xml new file mode 100644 index 00000000..27fbb9c8 --- /dev/null +++ b/inbox/udt.xml @@ -0,0 +1,197 @@ + + +%ents; + + +]> + + +
+ User-defined Data Transfer + This specification proposes a simple mechanism by which applications can transfer data safely, without + needing additional protocol design work. It is intended to provide a protocol that is trivial to implement and can + be driven with a simple API. + &LEGALNOTICE; + XXXX + ProtoXEP + Standards Track + Standards + + XMPP Core + + + + udt + &dcridland; + + 0.0.1 + 2019-12-30 + dwd + +
    +
  • Initial Revision
    • +
+ + +
+ + +

Applications written on top of XMPP often need to exchange data that has no existing standard. Such applications are + often written by developers unfamiliar with best practise in designing new extensions for XMPP, making it hard to achieve + this simple design goal without causing longer term problems.

+

This leads to "solutions" such as stuffing JSON directly in the <body/> element, for example, and recognising + this at the receiver either by heuristics or by a special <subject/>. While this works, it's difficult to then + migrate to something else, and enforces that custom clients are always used.

+

Therefore this document proposes a very simple (and simplistic) framework for sending such data which - while + very light on features - nevertheless conforms to best practice. Unusually, this specification SHOULD NOT be used + as a base upon which to build other standards, and suggests an API for library developers to implement.

+ +

Data transferred using this specification is encoded using JSON. The type of the data is given by a URI under + the same rules as an XML namespace, and this specification refers to this as the datatype.

+

Because this document defines mechanisms for sending essentially arbitrary data, no real-world examples are + given.

+

Instead, example namespaces are used within an XML namespace prefixed by &nsx;

+ + + + + +

Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature + of &ns;.

+

Support for a particular datatype is given by concatenating the &ns; feature with a hash character + ('#') and the datatype, for example &ns;#&nsx;foo.

+ + +

This specification provides for two types of user-defined data transfers. Each uses a similar payload syntax, + the UDT data payload.

+

Requests are carried within <iq/> stanzas, either of type "get" or "set", and result in a "result" optionally + containing a second UDT data payload.

+

UDT payloads may also be placed within a <message/> stanza. <message/> stanzas MAY contain multiple UDT + payloads, but typical usage is expected to be that there will be only one. The UDT payload may be ancillary data + to another message, or a standalone message in its own right.

+ +

A UDT payload consists of a single element, <payload/>, qualified by the XML namespace + &ns;. It has a single, mandatory attribute of datatype, which MUST contain a string conformant + to the requirements for XML namespaces (typically a URI under the control of the application developer).

+

As with XML namespaces, this URI is never expected to be resolved, and is used solely as an indentifier. + Different strings are considered entirely different datatypes, and common prefixes etc MUST be considered + irrelevant for the purposes of interpreting the data. There are no common or standard datatypes.

+

The <payload element contains exactly one mandatory child element, the <json/> element + defined in &xep0335;. This in turns contains the JSON data.

+ + + + { + "annoying-teenager-level": 11 + } + + + +]]> +

Note that the suggested custom &IQ; query payload of &xep0335; is not used as this would generally require + custom handlers within client libraries:

+ + + + { + "annoying-teenager-percentage": 101 + } + + + +]]> + + + + + +

In order to satisfy the goals of this protocol, it is necessary to define an API that can be consistently + implemented across APIs. This allows application developers to use the protocol easily, and encourages this + over using the ad-hoc techniques described in the introduction.

+

Therefore, while not imposing hard and fast API definitions, this specification proposes naming conventions + for APIs that will hopefully guide application developers toward consistent usage.

+

While names are specified in "snake_case", API developers are free to use their own naming. This specification + also defines APIs as taking session arguments which will often be implied by method calls, and omits types.

+

Library developers SHOULD make these calls as simple to use as possible. If these are significantly harder to use + for inexperienced developers than ad-hoc techniques, then ad-hoc techniques will be used instead.

+ +
    +
  • session - The session, connection or stream object or handle for the library. In cases where the + library uses a single global connection this is omitted. An OO library is likely to elide this and have the call + be a method call on the object instead.
    • +
  • message - The message object or handle for the library. An OO library is likely to elide this and have the call + be a method call on the object instead.
    • +
  • datatype - Typically a string containing an XML-style namespace.
    • +
  • jid - A string or JID object. Any form of legal jid might be used here.
    • +
  • data - Either a JSON-encoded string, or an object or data structure which can be converted by the + library.
    • +
  • get_or_set - A flag for indicating whether this is a "get" or "set" request.
    • +
  • callback - Some callable object or similar as meets the idiom of the language.
    • +
+ + +

Support is advertised on a session by calling udt_advertise(session, datatype). Calling this MUST + explicitly advertise both the &ns; feature and that of the datatype support.

+

APIs are free to (and encouraged to) implicitly advertise support when other calls are made.

+ + +

Requests are sent to a particular jid by calling udt_request(session, jid, get_or_set, datatype, data). + This might return a UDT payload, or have an additional callback argument to call with the response.

+

Applications may register to handle such requests by calling udt_request_callback(session, get_or_set, + datatype, callback). The callback should be called as callback(session, jid, get_or_set, datatype, + data), and returning a payload should send a result containing it. Applications registering this + way SHOULD implicitly advertise support for the datatype.

+ + +

Messages are sent to a particular jid by calling udt_message(session, jid, get_or_set, datatype, data).

+

Applications may register to handle such requests by calling udt_message_callback(session, get_or_set, + datatype, callback). The callback should be called as callback(session, jid, get_or_set, datatype, + data). Applications registering this way SHOULD implicitly advertise support for the datatype.

+

Applications may check to see if any message stanza contains a UDT payload by calling udt_payload(message, + datatype), which returns the payload if it exists.

+ + + + + + + + + + + + + + + + + ]]> + + + + +

All security implications herein are those of the payload.

+ + + +

This XEP requires no interaction with &IANA;.

+ + + +

None.

+ + + +

The authors wish to share any credit with many members of the community, including Florian Schmaus.

+ + +