<?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> <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.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="" names on a particular type of form.</p> <p>This document proposes a specific mechanism for the ®ISTRAR; 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='Naming Convention' anchor='approach-naming'> <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".</li> <li>For all new protocols approved by the XSF, the name MUST be an HTTP URI or IETF-style URN.</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 field names MUST conform to one of the following two conditions:</p> <ol> <li>If the field name is defined by the relevant XEP or by registration, the field name MUST be registered with the XMPP Registrar and MAY have any name (except a name that begins with "x-"), subject to approval by the XMPP Registrar.</li> <li>If the field name is unregistered, the field name MUST begin with "x-".</li> </ol> <p>If the FORM_TYPE is not registered, the field name MAY have any name (presumably managed by the namespace "owner").</p> </section2> <section2 topic='Field Values' anchor='approach-values'> <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', and all of the fields whose var names start with "pubsub#" would be registered with the XMPP Registrar, associated with that namespace.</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="x-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='Message with Bad Field' anchor='usecases-badfield'> <p>When a FORM_TYPE is specified correctly, and an unknown field is found whose name does not start with "x-", a receiver MAY respond with an "Not Acceptable" error.</p> <example caption='Message with bad field'><![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> <field var="FORM_TYPE" type="hidden"> <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> <message from="juliet@capulet.com" to="romeo@montague.net/garden" type="error"> <error code="406" type='modify'> <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> The field "light" is not acceptable. </text> </error> </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="hidden", it does not have the special meaning defined herein.</p> <p>If the form is used in an IQ, the namespace of the <query/> element SHOULD match the base namespace of the FORM_TYPE. (One possible way of solving this problem would have been to reuse the <query/> 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='Error Codes' anchor='errors'> <p>If the receiving entity believes that a specified field is invalid for the given FORM_TYPE, the receiver MAY respond to the sender with a "Not Acceptable" error; alternatively, the receiver MAY choose to ignore unknown fields.</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, or "x-" fields that are understood by a particular implementation and a user of that implementation.</p> </section1> <section1 topic='IANA Considerations' anchor='iana'> <p>This document requires no interaction with &IANA; for now. However, if this document is submitted to the IETF later, IANA should be used to standardize the field names rather than the XMPP Registrar.</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'> ®PROCESS; <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 <form_type/> element. The registrant MAY also register more than one field at a time, each contained in a separate <field/> 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 <field/> 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>