xep-0481.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>0481</number>
        <status>Experimental</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.1.0</version>
            <date>2023-05-04</date>
            <initials>XEP Editor: ks</initials>
            <remark>
                <p>Promoting to Experimental.</p>
            </remark>
        </revision>
        <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'>
          &lt;Quote xmlns='somenamespace'&gt;
             &lt;Consumption unit='kWh'&gt5000&lt;/Consumption&gt;
             &lt;Cost unit='USD'&gt200&lt;/Cost&gt;
          &lt;/Quote&gt;
       </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>