xeps/xep-0068.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>Field Standardization for Data Forms</title>
  <abstract>This document specifies how to standardize field variables used in the context of jabber:x:data forms.</abstract>
  &LEGALNOTICE;
  <number>0068</number>
  <status>Active</status>
  <interim/>
  <type>Informational</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0004</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>formtypes</shortname>
  <registry/>
  &hildjj;
  &stpeter;
  <revision>
    <version>1.2pre1</version>
    <date>2011-10-18</date>
    <initials>psa</initials>
    <remark>Removed mandates about x- prefix.</remark>
  </revision>
  <revision>
    <version>1.1</version>
    <date>2004-07-07</date>
    <initials>psa</initials>
    <remark>Specified ability to standardize field option values.</remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2003-08-18</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2003-06-05</date>
    <initials>psa</initials>
    <remark>Specified rules regarding registration and naming of FORM_TYPEs and associated fields.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-05-09</date>
    <initials>psa</initials>
    <remark>Clarified the relation of FORM_TYPE to registered namespaces; defined registry format; added IQ example.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-01-22</date>
    <initials>jjh</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
    <p>Now that &xep0004; has been finalized, several uses of jabber:x:data forms have been put on the standards track, including &xep0045;.  These protocols typically need a way to gather data from both humans (using a GUI format) and computer processes (using a pre-defined but flexible format).</p>
    <p>The 'jabber:x:data' namespace provides an adequate mechanism for both of these uses, as long as computer processes can rely on the var=&quot;&quot; names on a particular type of form.</p>
    <p>This document proposes a specific mechanism for the &REGISTRAR; to standardize these form field variable names. Thus this document enables existing clients to process forms as they have to this point, but enables protocol authors to specify a mechanism for non-GUI processors of those forms to determine the semantic meanings of those forms.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
    <ol>
      <li>Forms must continue to be presentable to humans for data entry.</li>
      <li>Jabber clients that know how to process generic jabber:x:data messages must be supported; the basic format of jabber:x:data must not change.</li>
      <li>If a form type is used in the context of a standards-track protocol, it should be standardized and registered; however, there is no requirement that all form types must be registered (e.g., form types used in custom applications).</li>
      <li>If a form type is standardized and registered, field names used in the context of that form type must either be standardized as well or else be clearly labeled as unregistered.</li>
      <li>Forms that are not directed <em>to</em> an entity must be able to traverse the entity (e.g., a form sent to a MUC room, intended for the participants of the room, and not the room itself).</li>
      <li>Forms must continue to be flexible for implementations; unknown future expansion fields must not be limited.</li>
      <li>The chosen approach must work for forms embedded in messages as well as in IQs.</li>
    </ol>
</section1>

<section1 topic='Approach' anchor='approach'>
    <section2 topic='Overview' anchor='approach-overview'>
        <p>Within Jabber, namespaces are used to scope data that conforms to a schema (often data that extends the core protocol in some fashion). In addition, namespaces can also provide context for the field variable names used in jabber:x:data forms and reports. This proposal makes that link explicit by defining a mechanism for linking a namespace name with a form and the field names and types used in that form. Specifically, the namespace name is specified in the form as the value of a hidden variable called "FORM_TYPE".</p>
    </section2>
    <section2 topic='Whether to Register' anchor='approach-register'>
        <p>The first decision-point is whether a FORM_TYPE needs to be registered with the XMPP Registrar. The following rules apply:</p>
        <ol>
          <li>If the FORM_TYPE is used in the context of a form defined in a XEP published by the &XSF;, it MUST be registered.</li>
          <li>If the FORM_TYPE is used in the context of some other XMPP protocol but the form is not defined in a XEP, it MAY be registered.</li>
          <li>If the FORM_TYPE is used in the context of a custom protocol, it MAY be registered.</li>
        </ol>
    </section2>
    <section2 topic='FORM_TYPE Names' anchor='approach-formtypes'>
        <p>While the value of the FORM_TYPE attribute SHOULD be considered an opaque string from the application perspective, the following rules apply:</p>
        <ol>
          <li>For custom protocols, the name SHOULD be an HTTP URI that is managed by the namespace owner (e.g., "http://example.com/foo").</li>
          <li>For all new protocols approved by the XSF, the name MUST be a "urn:xmpp:*" URN in accordance with Section 4 of &xep0053;.</li>
          <li>For "legacy" protocols managed by the XSF, the name SHOULD use the old-style "jabber:*:*" format.</li>
        </ol>
    </section2>
    <section2 topic='Field Names' anchor='approach-fieldnames'>
        <p>For FORM_TYPEs that are registered with the XMPP Registrar, the following rules apply:</p>
        <ol>
          <li>If the field name is defined by the XSF (i.e., in a XEP), the field name MUST be registered with the XMPP Registrar.</li>
          <li>If the field name is defined outside the XSF, the field name MAY be registered with the XMPP Registrar.</li>
        </ol>
        <p>If the FORM_TYPE is not registered, the field MAY have any name (managed by the namespace owner).</p>
        <p class='box'>Note: Older versions of this specification mandated that unregistered field names had to begin with the prefix "x-". In accordance with &xdash;, that mandate has been removed.</p>
    </section2>
    <section2 topic='Field Values' anchor='approach-fieldvalues'>
      <p>Field values may also be registered; refer to the <link url='registrar'>XMPP Registrar</link> section of this document.</p>
    </section2>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
    <section2 topic='Unspecified Form' anchor='usecases-unspecified'>
      <p>These are forms that do not have a hidden field of name FORM_TYPE.
        Existing processing rules still apply.</p>
      <example caption='Message with no FORM_TYPE'><![CDATA[
<message 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'>
  <thread>vote-thread-reatmon-134</thread>
  <x xmlns='jabber:x:data' type='form'>
    <title>Vote #134</title>
    <instructions>
      This is the vote to pick a new mascot. 
      Thanks for your time!
    </instructions>
    <field var='mascot' type='list-single'>
      <required/>
      <option label='Light Bulb'><value>light_bulb</value></option>
      <option label='Penguin'><value>penguin</value></option>
      <option label='Moose'><value>moose</value></option>
      <option label='Triangle Man'><value>triangle_man</value></option>
      <option label='Other'><value>other</value></option>
    </field>
  </x>
</message>
    ]]></example>
    </section2>
    <section2 topic='Correctly Specified FORM_TYPE' anchor='usecases-correct'>
      <p>In the following example, the FORM_TYPE is 'http://jabber.org/protocol/pubsub', all of the fields whose names start with "pubsub#" are registered with the XMPP Registrar (see &xep0060;), and the custom "time_restrictions" field defined by the organization at example.com uses &clark; in the field name.</p>

      <example caption='Message with FORM_TYPE'><![CDATA[
<message to="node-owner" from="pubsub.jabber.org">
    <x xmlns="jabber:x:data" type="form">
       <title>PubSub subscriber request</title>
       <instructions>To approve this entity's subscription request,
            click the OK button. To deny the request, click the
            cancel button.</instructions>
       <field var="FORM_TYPE" type="hidden">
           <value>http://jabber.org/protocol/pubsub</value>
       </field>
       <field var="pubsub#node" type="hidden">
           <value>generic/pgm-mp3-player</value>
       </field>
       <field var="pubsub#subscriber_jid" type="jid-single" 
              label="Jabber ID of Subscriber">
           <value>sub1@foo.com</value>
       </field>
       <field var="{http://example.com/pubsub}time_restrictions" type="text-multi" 
              label="Limit to these time ranges">
           <value>09:00-12:00</value>
           <value>13:00-17:00</value>
       </field>
    </x>
</message>
      ]]></example>
    </section2>
    <section2 topic='Incorrectly Specified FORM_TYPE' anchor='usecases-incorrect'>

    <p>If the FORM_TYPE field is not hidden, it MUST be ignored as a context indicator.</p>

      <example caption='Message with bad FORM_TYPE'><![CDATA[
<message to="juliet@capulet.com" from="romeo@montague.net/garden">
    <x xmlns="jabber:x:data" type="form">
       <title>Balcony Scene (Act 2, Scene 2)</title>
       <instructions>But soft! What light through yonder window breaks?</instructions>
       <!-- Not hidden.  Treated as any other text-single field. -->
       <field var="FORM_TYPE" type="text-single">
         <value>http://jabber.org/protocol/shakespeare</value>
       </field>
       <field var="light" type="list-multi">
           <option label="Juliet">Sun</option>
           <option lable="Maid">Moon</option>
           <option label="Eyes">Stars</option>
       </field>
    </x>
</message>
      ]]></example>
  </section2>
  <section2 topic='IQ Example' anchor='usecases-IQ'>
    <p>The following example shows a user's interaction with a Multi-User Chat room in order to register with the room.</p>
    <example caption='User Requests Registration Requirements'><![CDATA[
<iq
    from='hag66@shakespeare.lit/pda'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'
    id='reg1'>
  <query xmlns='jabber:iq:register'/>
</iq>
    ]]></example>
    <example caption='Service Returns Registration Form'><![CDATA[
<iq 
    type='result'
    from='darkcave@macbeth.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    id='reg1'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      To register on the web, visit http://shakespeare.lit/
    </instructions>
    <x xmlns='jabber:x:data' type='form'>
      <title>Dark Cave Registration</title>
      <instructions>
        Please provide the following information
        to register with this room.
      </instructions>
      <field
          type='hidden'
          var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#user</value> 
      </field>
      <field 
          type='text-single'
          label='First Name'
          var='muc#user_first'>
        <required/>
      </field>
      <field 
          type='text-single'
          label='Last Name'
          var='muc#user_last'>
        <required/>
      </field>
      <field 
          type='text-single'
          label='Desired Nickname'
          var='muc#user_roomnick'>
        <required/>
      </field>
      <field 
          type='text-single'
          label='Your URL'
          var='muc#user_url'/>
      <field 
          type='text-single'
          label='Email Address'
          var='muc#user_email'/>
      <field 
          type='text-multi'
          label='FAQ Entry'
          var='muc#user_faqentry'/>
    </x>
  </query>
</iq>
    ]]></example>
    <example caption='User Submits Registration Form'><![CDATA[
<iq 
    type='set'
    from='hag66@shakespeare.lit/pda'
    to='darkcave@macbeth.shakespeare.lit'
    id='reg2'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#user</value> 
      </field>
      <field var='muc#user_first'>
        <value>Brunhilde</value>
      </field>
      <field var='muc#user_last'>
        <value>Entwhistle-Throckmorton</value>
      </field>
      <field var='muc#user_roomnick'>
        <value>thirdwitch</value>
      </field>
      <field var='muc#user_url'>
        <value>http://witchesonline/~hag66/</value>
      </field>
      <field var='muc#user_email'>
        <value>hag66@witchesonline</value>
      </field>
      <field var='muc#user_faqentry'>
        <value>Just another witch.</value>
      </field>
    </x>
  </query>
</iq>
    ]]></example>
  </section2>
</section1>

<section1 topic='Implementation Notes' anchor='impl'>
    <p>If the FORM_TYPE field is not type=&quot;hidden&quot;, it does not have the special meaning defined herein.</p>
    <p>If the form is used in an IQ, the namespace of the &lt;query/&gt; element SHOULD match the base namespace of the FORM_TYPE. (One possible way of solving this problem would have been to reuse the &lt;query/&gt; tag from the IQ form of jabber:x:data within messages, but that would have meant that existing clients would not have been able to participate in these exchanges.)</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>Security-conscious programs that are using this approach should be careful to process only agreed-upon fields with agreed-upon types.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA; for now.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Registries' anchor='registrar-reg'>
    <section3 topic='FORM_TYPEs Registry' anchor='registrar-reg-formtypes'>
      <p>The XMPP Registrar shall maintain a registry of information about submitted FORM_TYPEs.</p>
      <section4 topic='Process' anchor='registrar-reg-formtypes-process'>
        &REGPROCESS;
        <code><![CDATA[
<form_type>
  <name>FORM_TYPE namespace or namespace derivative</name>
  <doc>associated specification</doc>
  <desc>natural-language description of form type</desc>
  <field
      var='the_field_name'
      type='the_field_type'
      label='natural-language description of field'/>
</form_type>
        ]]></code>
        <p>The registrant MAY register more than one FORM_TYPE at a time, each contained in a separate &lt;form_type/&gt; element. The registrant MAY also register more than one field at a time, each contained in a separate &lt;field/&gt; child element. Registrations of new fields within an existing FORM_TYPE MUST include the full XML snippet but SHOULD NOT include the FORM_TYPE description (only the name and the XEP number or other document identifier). Note that for ease of use the format for the &lt;field/&gt; element in the registry submission is the same as that defined in XEP-0004; in addition, the value of the 'type' attribute MUST be one of those defined in that XEP-0004.</p>
        <p>In addition, a registrant MAY also register particular field option values for fields of type 'list-single' and 'list-multi'. The format for such submissions is as follows:</p>
        <code><![CDATA[
<form_type>
  <name>FORM_TYPE namespace or namespace derivative</name>
  <doc>associated XEP or other document</doc>
  <desc>natural-language description of form type</desc>
  <field
      var='the_field_name'
      type='the_field_type'
      label='natural-language description of field'>
    <option label='natural-language description of option'>
      <value>the_value</value>
    </option>
  </field>
</form_type>
        ]]></code>
      </section4>
    </section3>
  </section2>
</section1>

</xep>