XEP-0004: Clarify field type omission for 'submit' and 'result' form field types

The specification was a bit involved about that topic. Hopefully this
reformatting text improves the readability.

This commit is based on a different patch by Florian Schmaus and
hopefully further improves clarity by spelling out all cases clearly
in a list, as well as more thoroughly defining corner cases.
This commit is contained in:
Florian Schmaus 2020-07-17 15:43:20 +02:00 committed by Jonas Schäfer
parent 5f0bc97f4d
commit f35b0ace41
1 changed files with 6 additions and 1 deletions

View File

@ -223,7 +223,12 @@
<di><dt>&lt;value/&gt;</dt><dd>The XML character data of this element defines the default value for the field (according to the form-processing entity) in a data form of type "form", the data provided by a form-submitting entity in a data form of type "submit", or a data result in a data form of type "result". In data forms of type "form", if the form-processing entity provides a default value via the &lt;value/&gt; element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one &lt;value/&gt; element; all other field types MUST NOT contain more than one &lt;value/&gt; element.</dd></di>
<di><dt>&lt;option/&gt;</dt><dd>One of the options in a field of type "list-single" or "list-multi". The XML character of the &lt;value/&gt; child defines the option value, and the 'label' attribute defines a human-readable name for the option. The &lt;option/&gt; element MUST contain one and only one &lt;value/&gt; child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an &lt;option/&gt; element.</dd></di>
</dl>
<p>If the &lt;field/&gt; element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The &lt;field/&gt; element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each &lt;field/&gt; element SHOULD possess a 'type' attribute that defines the data "type" of the field data (if no 'type' is specified, the default is "text-single"); fields provided in the context of other forms types MAY possess a 'type' attribute as well. For data forms of type "submit", inclusion of the 'type' attribute is OPTIONAL, since the form-processing entity is assumed to understand the data types associated with forms that it processes.</p>
<p>If the &lt;field/&gt; element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The &lt;field/&gt; element MAY possess a 'label' attribute that defines a human-readable name for the field.</p>
<p>The 'type' attribute defines the data "type" of the field data. The following rules apply for that attribute:</p>
<ul>
<li>For data forms of type "form", each &lt;field/&gt; element SHOULD possess a 'type' attribute. If the 'type' attribute is absent, the default of "text-single" is to be applied.</li>
<li>For data forms of type "submit", "result" or "error", the recieving entity can infer the 'type' attribute value from context. Nevertheless, the 'type' attribute MAY be present for clarity. Note that forms of type "error" SHOULD NOT have any &lt;field/&gt; elements.</li>
</ul>
<p>If fields are presented in a user interface (e.g., as items in a questionnaire or form result), the order of the field elements in the XML SHOULD determine the order of items presented to the user.</p>
</section2>
<section2 topic='Field Types' anchor='protocol-fieldtypes'>