mirror of
https://github.com/moparisthebest/xeps
synced 2024-10-31 15:35:07 -04:00
210 lines
9.5 KiB
XML
210 lines
9.5 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<!--
|
|
© XMPP Standards Foundation, 2016
|
|
Author: Peter Waher
|
|
-->
|
|
<xep>
|
|
<header>
|
|
<title>Content Types in Messages</title>
|
|
<abstract>This specification describes a generic method whereby content in messages can be tagged as having a specific Internet Content Type. It also provides a method for sending the same content using different content types, as a fall-back mechanism when communicating between clients having different content type support.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>xxxx</number>
|
|
<status>ProtoXEP</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0030</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>content</shortname>
|
|
&peterwaher;
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2016-01-15</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<p>First draft.</p>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>
|
|
Sometimes it is desirable for clients to communicate, or to send messages between each other, using a well defined Internet Content Type.
|
|
Reasons can vary between the purely esthetic to funcional data-exchange. While there are XEPs, such as &xep0071; that provides means for
|
|
sending richer content using a specific type, this extensions provides a similar mechanism, but for the general case of any content having
|
|
a defined Internet Content Type.
|
|
</p>
|
|
<p>
|
|
<strong>Note:</strong> While the examples in this extensions uses Markdown as an example, any other text-based content type can be used.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Use Cases' anchor='usecases'>
|
|
<section2 topic='Content type hint' anchor='hint'>
|
|
<p>
|
|
The simplest use case is hinting at the content type of the textual content presented in the message body. This is done by aggregating
|
|
a <strong>content</strong> element of namespace <strong>urn:xmpp:content</strong> to the message, with the attribute <strong>type</strong>
|
|
specifying the content type. If the element does not provide a value, it is understood that the body contains the textual body of the
|
|
content. This method should only be used if there's no risk of misunderstanding the message if the content type is not understood by
|
|
the receiver, and the textual representation is readable. Example:
|
|
</p>
|
|
<example caption='Hinting at a content type'>
|
|
<![CDATA[
|
|
<message
|
|
from='person1@example.org/34892374'
|
|
to='person2@example.org/938089023'
|
|
type='chat'>
|
|
<body>**Note:** This message is very important.</body>
|
|
<content type='text/markdown' xmlns='urn:xmpp:content'/>
|
|
</message>]]>
|
|
</example>
|
|
</section2>
|
|
<section2 topic='Alternate encoding' anchor='encoding'>
|
|
<p>
|
|
If there is a risk of misunderstanding the message if it's content type is not recognized, or the presentation of the message
|
|
is done in an undesireable fashion, you can provide an alternate encoding of the message in the <strong>content</strong> element
|
|
itself. If the <strong>content</strong> element contains a message, and the content type is recognized, the message should be
|
|
taken from the <strong>content</strong> element instead of the <strong>body</strong> element. The <strong>body</strong> element
|
|
in turn, should contain the <strong>plain text</strong> version of the same message. Example:
|
|
</p>
|
|
<example caption='Alternate encoding'>
|
|
<![CDATA[
|
|
<message
|
|
from='person1@example.org/34892374'
|
|
to='person2@example.org/938089023'
|
|
type='chat'>
|
|
<body>Note: Go to Google and search for it.</body>
|
|
<content type='text/markdown' xmlns='urn:xmpp:content'>
|
|
**Note:** Go to [Google](http://www.google.com/) and search for it.
|
|
</content>
|
|
</message>]]>
|
|
</example>
|
|
</section2>
|
|
<section2 topic='Alternate encodings' anchor='encodings'>
|
|
<p>
|
|
By providing multiple <strong>content</strong> elements in the same message, you can allow the receiver to choose the encoding
|
|
best suited for its purpose. It also makes it possible to interchange messages that are understood by both humans and machines
|
|
in the same message. If an empty <strong>content</strong> element is found, it is interpreted as above, i.e. providing a hint
|
|
as to the content type of the message in the <strong>body</strong> element. Example:
|
|
</p>
|
|
<example caption='Alternate encodings'>
|
|
<![CDATA[
|
|
<message
|
|
from='person1@example.org/34892374'
|
|
to='person2@example.org/938089023'
|
|
type='chat'>
|
|
<body>
|
|
Your energy consumption this month is 5000 kWh.
|
|
That is very much. It will cost you 200 USD.
|
|
You can find current tariffs at our web page.
|
|
</body>
|
|
<content type='text/markdown' xmlns='urn:xmpp:content'>
|
|
Your energy consumption this month is **5000 kWh**.
|
|
That is *very much*. It will cost you **200 USD**.
|
|
You can find current tariffs at our [web page](http://www.example.com/Energy).
|
|
</content>
|
|
<content type='text/xml' xmlns='urn:xmpp:content'>
|
|
<Quote xmlns='somenamespace'>
|
|
<Consumption unit='kWh'>5000</Consumption>
|
|
<Cost unit='USD'>200</Cost>
|
|
</Quote>
|
|
</content>
|
|
</message>]]>
|
|
</example>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Determining Support' anchor='support'>
|
|
<p>
|
|
If an entity supports content types as specified herein, it MUST advertise that fact by returning a feature of
|
|
"urn:xmpp:content" in response to &xep0030; information requests.
|
|
</p>
|
|
<example caption="Service discovery information request">
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='example.org'
|
|
to='device@example.org'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>]]>
|
|
</example>
|
|
<example caption="Service discovery information response">
|
|
<![CDATA[
|
|
<iq type='result'
|
|
from='device@example.org'
|
|
to='example.org'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='urn:xmpp:content'/>
|
|
...
|
|
</query>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic,
|
|
presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities
|
|
information from an entity, it SHOULD use explicit service discovery instead.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
|
<section2 topic='Content Types' anchor='contentTypes'>
|
|
<p>
|
|
This document does not specify how content types are to be interpreted, or if content types are valid or well defined.
|
|
It does not specify which content types are to be understood, or when. It only provides a means to hint or include different
|
|
encodings in the same message.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Custom Content Types' anchor='customTypes'>
|
|
<p>
|
|
It is possible to use custom or vendor-specific content types. These types are marked by prefixing the subtype with
|
|
<strong>x.</strong> for custom unregistered types, and with <strong>vnd.</strong> for registered vendor specific types.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Stanza size' anchor='stanzaSize'>
|
|
<p>
|
|
Care has to be taken when sending multiple encodings of the same message, as to not reach the smallest allowed
|
|
maximum stanza size used by client and server software.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>
|
|
The <link url="#schema">protocol schema</link> needs to be added to the list of <link url="http://xmpp.org/resources/schemas/">XMPP protocol schemas</link>.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<code>
|
|
<![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!--
|
|
© XMPP Standards Foundation, 2016
|
|
Author: Peter Waher
|
|
-->
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:content'
|
|
xmlns='urn:xmpp:content'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:element name='content'>
|
|
<xs:complexType mixed='true'>
|
|
<xs:attribute name='type' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
</xs:schema>
|
|
]]>
|
|
</code>
|
|
</section1>
|
|
</xep>
|