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>">
  <!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>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>webxdc</shortname>
  &singpolyma;
  <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. In order to use these, the host protocol must define a way to transmit the widgets and the associated state updates.</p>
</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.</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/xdc+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>
</message>]]></example>
</section1>
<section1 topic='Sending a State Update' anchor='state'>
  <p>When a widget needs to communicate an update to other participants, this update may contain the following information:</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, except for the info item, are delivered in a message which MUST have the same <tt>&lt;thread&gt;</tt> as the message which originally delivered the widget itself, as children of an element <tt>&lt;x xmlns="urn:xmpp:webxdc:0"&gt;</tt> 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>WebXDC widgets get various data injected into them by the host application. One of these worth mentioning is the <tt>selfAddr</tt> property. 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. When the chat supports &xep0421; this property SHOULD be set to the local party's occupant id.</p>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
  <p>None</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This XEP does not have any specific security considerations, however it is assumed that it will be paired with an implementation of &webxdc; which requires very careful sandboxing.</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>