Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

New XEP: WebXDC #1349

Merged
merged 1 commit into from
Jun 17, 2024
Merged

New XEP: WebXDC #1349

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions inbox/webxdc.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
8 changes: 8 additions & 0 deletions xep.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->

Expand Down