-
Notifications
You must be signed in to change notification settings - Fork 119
/
xep-0481.xml
217 lines (215 loc) · 9.78 KB
/
xep-0481.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
<?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'>
< 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'>
<.
</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>