New XEP: WebXDC

inbox/webxdc.xml

@@ -0,0 +1,164 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE xep SYSTEM 'xep.dtd' [
+  <!ENTITY xep-number "xxxx">
+  <!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>xxxx</number>
+  <status>ProtoXEP</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.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='[email protected]' 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:[email protected]' 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='[email protected]' 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='[email protected]' 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='[email protected]' 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='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>
+</xep>

xep.ent

@@ -1175,6 +1175,14 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
     <jid>[email protected]</jid>
   </author>
 " >
+<!ENTITY singpolyma "
+  <author>
+    <firstname>Stephen Paul</firstname>
+    <surname>Weber</surname>
+    <email>[email protected]</email>
+    <jid>[email protected]</jid>
+  </author>
+" >
 
 <!-- XMPP Extension Protocols -->