xeps/xep-0315.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'?>
<xep>
<header>
  <title>Data Forms XML Element</title>
  <abstract>This specification defines an XMPP protocol extension for including XML-data in XEP-0004 data forms.</abstract>
  &LEGALNOTICE;
  <number>0315</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0004</spec>
  </dependencies>
  <supersedes>None</supersedes>
  <supersededby>None</supersededby>
  <shortname>media-element</shortname>
  <schemaloc/>
  <author>
    <firstname>Sergey</firstname>
    <surname>Dobrov</surname>
    <email>binary@jrudevels.org</email>
    <jid>binary@jrudevels.org</jid>
    <uri>http://jrudevels.org/</uri>
  </author>
  <revision>
    <version>0.1</version>
    <date>2012-10-15</date>
    <initials>psa</initials>
    <remark><p>Initial published version approved for publication by the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2012-06-21</date>
    <initials>snd</initials>
    <remark><p>Root element name changed to "wrapper"; xmlns fixed in the XML-schema.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2012-06-13</date>
    <initials>snd</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>In certain protocols that make use of &xep0004;, it can be helpful to include XML-data (for example, when we want to insert a big amount of structured data which is hard to insert as a separate fields). This document defines a method for including XML-data in a data form.</p>
</section1>

<section1 topic='Media Element' anchor='media'>
  <p>The root element for XML-data is &lt;wrapper/&gt;. This element MUST be qualified by the "urn:xmpp:xml-element" namespace. The &lt;wrapper/&gt; element MUST be contained within a &lt;field/&gt; element qualified by the 'jabber:x:data' namespace.</p>
  <p>The &lt;wrapper/&gt; element SHOULD contain an XML-data which needs to be represented in a form.</p>
  <example caption='PubSub Blog Node Metadata'><![CDATA[
<wrapper xmlns='urn:xmpp:xml-element'>
  <feed xmlns='http://www.w3.org/2005/Atom'>
    <title>Romeo&amp;apos;s Microblog</title>
    <id>tag:montague.lit,2008:home</id>
    <updated>2008-05-08T18:30:02Z</updated>
    <author>
      <name>Romeo Montague</name>
      <uri>xmpp:romeo@montague.lit</uri>
    </author>
  </feed>
</wrapper>
  ]]></example>
  <example caption='Inclusion in Data Form'><![CDATA[
<x xmlns='jabber:x:data' type='form'>
  [ ... ]
  <field var='xml-metadata' type='hidden'>
    <wrapper xmlns='urn:xmpp:xml-element'>
      <feed xmlns='http://www.w3.org/2005/Atom'>
        <title>Romeo&amp;apos;s Microblog</title>
        <id>tag:montague.lit,2008:home</id>
        <updated>2008-05-08T18:30:02Z</updated>
        <author>
          <name>Romeo Montague</name>
          <uri>xmpp:romeo@montague.lit</uri>
        </author>
      </feed>
    </wrapper>
  </field>
  [ ... ]
</x>
  ]]></example>
</section1>

<section1 topic="Usage Practices">
  <p>XML-data is usually hard for manual editing and SHOULD be used only for machine level iteractions. So it's RECOMMENDED to include it in the form as a "hidden" field.</p>
  <p>However, there are situations when human editing of XML-data may be useful (for example, to see XML-logs of some XMPP-service). In that case it's RECOMMENDED for a client to represent this XML in a pretty formatted form and give an instruments to make it easier to edit XML-data.</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='ns'>
    <p>The &REGISTRAR; includes "urn:xmpp:xml-element" in its registry of protocol namespaces (see &NAMESPACES;).</p>
  </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:xml-element'
    xmlns='urn:xmpp:xml-element'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='wrapper'>
    <xs:complexType>
      <xs:sequence>
        <xs:any minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
  ]]></code>
</section1>

</xep>