mirror of https://github.com/moparisthebest/xeps
154 lines
6.8 KiB
XML
154 lines
6.8 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
<!ENTITY ns "urn:xmpp:json-msg:0">
|
|
<!ENTITY nsx "urn:example:">
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Simple JSON Messaging</title>
|
|
<abstract>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.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0432</number>
|
|
<status>Experimental</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>udt</shortname>
|
|
&dcridland;
|
|
<revision>
|
|
<version>0.1.0</version>
|
|
<date>2020-02-25</date>
|
|
<initials>XEP Editor (jsc)</initials>
|
|
<remark>Accepted by vote of Council on 2020-02-19.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.2</version>
|
|
<date>2020-02-13</date>
|
|
<initials>dwd</initials>
|
|
<remark>
|
|
<p>Have another crack at getting this through Council.</p>
|
|
<ul>
|
|
<li>Rename to a more obvious name</li>
|
|
<li>Remove IQ</li>
|
|
<li>Remove API, instead describe API requirements</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2019-12-30</date>
|
|
<initials>dwd</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Initial Revision</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>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.</p>
|
|
<p>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 is difficult to then
|
|
migrate to something else, and enforces that custom clients are always used.</p>
|
|
<p>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, and yields an interoperable protocol. Unusually, this
|
|
specification SHOULD NOT be used as a base upon which to build other standards.</p>
|
|
<section2 topic="Terminology">
|
|
<p>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.</p>
|
|
<p>Because this document defines mechanisms for sending essentially arbitrary data, no real-world examples are
|
|
given.</p>
|
|
<p>Instead, example namespaces are used within an XML namespace prefixed by <tt>&nsx;</tt></p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Overview' anchor="overview">
|
|
<section2 topic="Discovering Support" anchor="feature">
|
|
<p>Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature
|
|
of <tt>&ns;</tt>.</p>
|
|
<p>Support for a particular datatype is given by concatenating the <tt>&ns;</tt> feature with a hash character
|
|
('<tt>#</tt>') and the datatype, for example <tt>&ns;#&nsx;foo</tt>.</p>
|
|
</section2>
|
|
<section2 topic="Data Transfers">
|
|
<p>Simple JSON Messaging 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 JSON Messaging payload may be ancillary data
|
|
to another message, or a standalone message in its own right.</p>
|
|
<section3 topic="Protocol Syntax">
|
|
<p>A Simple JSON Messaging payload consists of a single element, <tt><payload/></tt>, qualified by the XML namespace
|
|
<tt>&ns;</tt>. It has a single, mandatory attribute of <tt>datatype</tt>, which MUST contain a string conformant
|
|
to the requirements for XML namespaces (typically a URI under the control of the application developer).</p>
|
|
<p>As with XML namespaces, this URI is never expected to be resolved, and is used solely as an identifier.
|
|
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.</p>
|
|
<p>The <tt><payload</tt> element contains exactly one mandatory child element, the <tt><json/></tt> element
|
|
defined in &xep0335;. This in turns contains the JSON data.</p>
|
|
<example><![CDATA[
|
|
<message from="gamer@game-company.example"
|
|
to="match-maker.game-company.example"
|
|
id="12345">
|
|
<payload xmlns="]]>&ns;<![CDATA[" datatype="]]>&nsx;foo<![CDATA[">
|
|
<json xmlns="urn:xmpp:json:0">
|
|
{
|
|
"annoying-teenager-level": 11
|
|
}
|
|
</json>
|
|
</payload>
|
|
</message>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic="API Requirements">
|
|
<p>In order to satisfy the goals of this protocol, client library developers are encouraged to provide a simple to use API for this protocol. Developers are encouraged to use terms such as "JSON Message" in their API calls and documentation.</p>
|
|
<p>Support for a particular datatype SHOULD be advertised automatically when listening for custom messages of that type if possible.</p>
|
|
</section1>
|
|
|
|
<section1 topic="Schema">
|
|
<code>
|
|
<![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="]]>&ns;<![CDATA[" xmlns:xs="http://www.w3.org/2001/XMLSchema">
|
|
<xs:element name="payload" type="udt:payloadType" xmlns:udt="]]>&ns;<![CDATA["/>
|
|
<xs:complexType name="payloadType">
|
|
<xs:sequence>
|
|
<xs:any minOccurs="1" maxOccurs="1"/>
|
|
<!-- Always a XEP-0335 json element, but I can't figure that out. -->
|
|
</xs:sequence>
|
|
<xs:attribute type="xs:string" name="datatype"/>
|
|
</xs:complexType>
|
|
</xs:schema>
|
|
]]>
|
|
</code>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>All security implications herein are those of the payload.</p>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This XEP requires no interaction with &IANA;. </p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>None.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>The authors wish to share any credit with many members of the community, including Florian Schmaus, Daniel Gultsch, Georg Lukas, and others.</p>
|
|
</section1>
|
|
|
|
</xep>
|