xep-0491.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY xep-number "0491">
  <!ENTITY webxdc "<span class='ref'><link url='https://webxdc.org'>WebXDC</link></span> <note>WebXDC docs: <link url='https://webxdc.org/docs/'>https://webxdc.org/docs/</link></note>">
  <!ENTITY webxdcSendUpdate "<span class='ref'><link url='https://webxdc.org/docs/spec/sendUpdate.html'>WebXDC</link></span> <note>WebXDC sendUpdate: <link url='https://webxdc.org/docs/spec/sendUpdate.html'>https://webxdc.org/docs/spec/sendUpdate.html</link></note>">
  <!ENTITY webxdcaddrname "<span class='ref'><link url='https://webxdc.org/docs/spec/selfAddr_and_selfName.html'>WebXDC</link></span> <note>WebXDC selfAddr and selfName: <link url='https://webxdc.org/docs/spec/selfAddr_and_selfName.html'>https://webxdc.org/docs/spec/selfAddr_and_selfName.html</link></note>">
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>WebXDC</title>
  <abstract>This document defines an XMPP protocol extension to communicate WebXDC widgets and their state updates.</abstract>
  &LEGALNOTICE;
  <number>&xep-number;</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0335</spec>
    <spec>XEP-0421</spec>
    <spec>WebXDC</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>webxdc</shortname>
  &singpolyma;
  <revision>
    <version>0.1.3</version>
    <date>2024-10-17</date>
    <initials>spw</initials>
    <remark>
      <ul>
        <li>Clarifications and wording</li>
        <li>Better references for WebXDC spec</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.1.2</version>
    <date>2024-07-03</date>
    <initials>spw</initials>
    <remark>
      <ul>
        <li>Suggest what to use for selfAddr</li>
        <li>Add acknowledgements</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.1.0</version>
    <date>2024-06-20</date>
    <initials>XEP Editor: dg</initials>
    <remark>
      <ul>
        <li>Promoted to Experimental</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2024-06-05</date>
    <initials>spw</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>&webxdc; is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections for the sandboxed web content. In order to provide support for &webxdc; widgets, the host protocol (XMPP in our case) must define a way to transmit these widgets and the associated state updates.</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
  <p>This specification uses some terminology defined below:</p>
  <ul>
    <li>widget: the WebXDC widget delivered in a zip container as defined by &webxdc;</li>
    <li>host application: the XMPP client embedding the widget</li>
    <li>peer: the chat partner in a 1:1 chat or one of the participants of a &xep0045; or other group chat</li>
    <li>host protocol: the protocol used by the peers to communicate (XMPP in our case)</li>
  </ul>
</section1>
<section1 topic='Sending a Widget in a Message' anchor='send'>
  <p>A widget may be attached to a message using any file-transfer mechanism supported by the client, such as &xep0066; or &xep0385;. The message MUST contain a <tt>&lt;thread/&gt;</tt> element with a new, unique id.  Note: including multiple file-transfer mechanisms in the same message may be beneficial for broader compatibility.</p>
<example caption='An example of sending a widget'><![CDATA[
<message to='romeo@montague.lit' type='chat'>
  <thread>018fe972-ea89-7f4b-90f8-729b85b7f32d</thread>
  <media-sharing xmlns='urn:xmpp:sims:1'>
    <file xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
      <media-type>application/webxdc+zip</media-type>
      <name>Calendar</name>
      <size>3032449</size>
      <hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
      <thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='96' height='96'/>
    </file>
    <sources>
      <reference xmlns='urn:xmpp:reference:0' type='data' uri='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/calendar.xdc />
    </sources>
  </media-sharing>
  <x xmlns='jabber:x:oob'>
    <url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/calendar.xdc</url>
  </x>
</message>]]></example>
</section1>
<section1 topic='Sending a State Update' anchor='state'>
  <p>When a widget needs to communicate an update to peers in a chat, this update may contain one or more of the following items as defined in &webxdcSendUpdate;.</p>
  <table caption='Data transmitted with a WebXDC update'>
    <tr>
      <th>Item</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>info</td>
      <td>Human readable message to send to the chat</td>
    </tr>
    <tr>
      <td>summary</td>
      <td>Text which may be shown next to the widget launcher</td>
    </tr>
    <tr>
      <td>document</td>
      <td>Title which may be shown next to the widget launcher</td>
    </tr>
    <tr>
      <td>payload</td>
      <td>Arbitrary JSON serializable value</td>
    </tr>
  </table>
  <p>These items are delivered in a message which MUST have the same <tt>&lt;thread&gt;</tt> as the message which originally <link url="#send">delivered the widget itself</link>. The stanza SHOULD contain a <tt>x</tt> child having the <tt>urn:xmpp:webxdc:0</tt> namespace, with these items (except for <tt>info</tt>) as children, as defined below.</p>
  <section2 topic='The Info Item' anchor='info'>
    <p>The info item is human-readable and is not needed by the widget itself, thus it is appropriate to transmit it anywhere that it might be visible to all participants, such as in a message body. If this is the only item present, an empty <tt>&lt;x&gt;</tt> element SHOULD still be included in the message to signal this update came from the widget.</p>
    <example caption='An example of sending just info'><![CDATA[
<message to='romeo@montague.lit' type='chat'>
  <thread>018fe972-ea89-7f4b-90f8-729b85b7f32d</thread>
  <x xmlns='urn:xmpp:webxdc:0' />
  <body>Juliet has added an event.</body>
</message>]]></example>
  </section2>
  <section2 topic='The Document and Summary Items' anchor='summary'>
    <p>These items are delivered as children of the <tt>&lt;x&gt;</tt> item, and in the same namespace. The document item using a <tt>&lt;document&gt;</tt> child and the summary item using a <tt>&lt;summary&gt;</tt> child.</p>
    <example caption='An example of sending document and summary'><![CDATA[
<message to='romeo@montague.lit' type='chat'>
  <thread>018fe972-ea89-7f4b-90f8-729b85b7f32d</thread>
  <x xmlns='urn:xmpp:webxdc:0'>
    <document>Our Calendar</document>
    <summary>12 events</summary>
  </x>
</message>]]></example>
  </section2>
  <section2 topic='The Payload Item' anchor='payload'>
    <p>The payload item is delivered using &xep0335; as a child of the <tt>&lt;x&gt;</tt> element</p>
    <example caption='An example of sending payload'><![CDATA[
<message to='romeo@montague.lit' type='chat'>
  <thread>018fe972-ea89-7f4b-90f8-729b85b7f32d</thread>
  <x xmlns='urn:xmpp:webxdc:0'>
    <json xmlns='urn:xmpp:json:0'>{}</json>
  </x>
</message>]]></example>
  </section2>
</section1>
<section1 topic='selfAddr' anchor='selfAddr'>
  <p>&webxdcaddrname; widgets get various data injected into them by the host application. One of these worth mentioning is the <tt>selfAddr</tt> property.</p>
	<ul>
		<li>When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID e.g. <tt>xmpp:juliet@capulet.lit</tt></li>
		<li>When the chat supports &xep0421; this property SHOULD be set to the local party's <tt>occupant-id</tt>.</li>
		<li>Note that no other type of chat is specified here, and especially that a &xep0045; chat without support for &xep0421; SHOULD NOT use full Jabber ID or room nickname for the property, as it may case inconsistent behaviour in some widgets when the user changes their nickname.</li>
	</ul>
</section1>
<section1 topic='selfName' anchor='selfName'>
  <p>The <tt>selfName</tt> property defined by &webxdcaddrname; is human readable and may be set to anything useful per that specification. It MAY be set to the local &xep0045; nickname or &xep0172; where relevant.</p>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
  <p>None</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>It is assumed that an implementation of this XEP will be paired with an implementation of &webxdc;. Please see &webxdc; for sandboxing and security considerations for your WebXDC implementation.</p>
  <p>This XEP does not introduce any specific security considerations besides those present in any &webxdc; implementation.</p>
</section1>
<section1 topic='Privacy Considerations' anchor='privacy'>
  <p>It should be clear to users that their actions inside an embedded widget may be transmitted to other participants.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace: urn:xmpp:webxdc:0</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:webxdc:0'
    xmlns='urn:xmpp:webxdc:0'
    xmlns:json='urn:xmpp:json:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-]]>&xep-number;<![CDATA[: http://www.xmpp.org/extensions/xep-]]>&xep-number;<![CDATA[.html
    </xs:documentation>
  </xs:annotation>

  <xs:import namespace='urn:xmpp:json:0' schemaLocation='https://xmpp.org/schemas/json.xsd' />

  <xs:element name='x'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='summary' type='xsd:string' minOccurs='0' maxOccurs='1'/>
        <xs:element name='document' type='xsd:string' minOccurs='0' maxOccurs='1'/>
        <xs:element name='json' type='json:json' minOccurs='0' maxOccurs='1'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='acks'>
  <p>Thanks to NLNet foundation for funding the work on this specification.</p>
</section1>
</xep>