JEP-0141: Data Forms Layout

This JEP defines an extension to the Data Forms protocol enabling an application to specify form layouts.


WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.


JEP Information

Status: Experimental
Type: Standards Track
Number: 0141
Version: 0.1
Last Updated: 2004-08-10
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, JEP-0004
Supersedes: None
Superseded By: None
Short Name: xdata-layout

Author Information

Matthew Miller

Email: linuxwolf@outer-planes.net
JID: linuxwolf@outer-planes.net

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Table of Contents

1. Introduction
2. Requirements
3. Use Cases
3.1. Paging Fields
3.2. Sectioning Fields
3.3. Including Tables
4. Implementation Notes
4.1. Discovery
4.2. Field Distribution
4.3. Page Labels and Descriptions
4.4. Section Labels and Descriptions
4.5. Internationalization/Localization
5. Security Considerations
6. IANA Considerations
7. Jabber Registrar Considerations
8. Formal Definition
8.1. <page/> Root Element
8.2. <section/> Element
8.3. <fieldref/> Element
8.4. <reportedref/> Element
8.5. <desc/> Element
8.6. XML Schema
Notes
Revision History


1. Introduction

Data Forms [1] ("x:data") provides a simple and interoperable way to request and present information for both applications and humans. However, the simple nature of "x:data" requires the form renderer to use a generic "key/value" format. This JEP builds upon "x:data" to provide this additional layout information.

2. Requirements

The requirements for this JEP are:

3. Use Cases

This JEP defines a new namespace, "http://jabber.org/protocol/xdata-layout". All layout is defined by "pages" and "sections".

All of the use cases refer to the following form:

Example 1. Sample form

<x xmlns='jabber:x:data' type='form'>
  <title>JSF Application</title>
  <instructions>Please fill out this form</instructions>
  
  <field var='name.first' type='text-single' label='First Name'>
    <required/>
  </field>
  <field var='name.last' type='text-single' label='Last Name'>
    <required/>
  </field>
  <field var='email' type='text-single' label='E-mail Address'>
    <required/>
  </field>
  <field var='jid' type='jid-single' label='Jabber JID'>
    <required/>
  </field>
  
  <field var='background' type='text-multi' label='Background Information'>
  </field>
  <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'>
  </field>
  <field var='reasoning' type='text-multi' label='Reasons for Joining'>
  </field>
  
  <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'>
  </field>
  <field var='activity.jeps' type='text-multi' label='JEPs Authored or Co-Authored'>
  </field>
</x>
  

3.1 Paging Fields

One of the simplest layout usages is to separate fields into pages. This is done by including one or more <page/> elements within the x:data form. Each <page/> SHOULD have a "label" attribute to label the page, MAY include a <desc/> for additional information, and SHOULD include a <fieldref/> for each field to be included in the page. To reference an x:data field, the <fieldref/> element's "var" attribute MUST equal the intended <field/>s "var" attribute.

Example 2. Pages of fields

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout' label='Personal Information'>
    <fieldref var='name.first'/>
    <fieldref var='name.last'/>
    <fieldref var='email'/>
    <fieldref var='jid'/>
    <fieldref var='background'/>
  </page>
  <page label='Community Activity'>
    <fieldref var='activity.mailing-lists'/>
    <fieldref var='activity.jeps'/>
  </page>
  <page label='Plans and Reasonings'>
    <fieldref var='future'/>
    <fieldref var='reasoning'/>
  </page>
  
  ...
</x>
    

The preceding example partitions the fields into three pages; labeled "Personal Information", "Community Activity", and "Plans and Reasonings".

If a <fieldref/> within a <page/> references a non-existent <field/>, that reference MUST be ignored.

3.2 Sectioning Fields

The next usage of layout is by sections within pages. This is done by including one or more <section/> elements within each <page/>. Each <section/> SHOULD have a "label" attribute to identify the section, MAY include a <desc/> for additional information, and SHOULD include a <fieldref/> for each field to be included in the section. A <section/> MUST contain at least one <fieldref/> or <reportedref/>. To reference an x:data field, the <fieldref/> element's "var" attribute MUST equal the intended <field/> element's "var" attribute.

Example 3. Sections of fields

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout'>
    <section label='Personal Information'>
      <fieldref var='name.first'/>
      <fieldref var='name.last'/>
      <fieldref var='email'/>
      <fieldref var='jid'/>
      <fieldref var='background'/>
    </section>
    <section label='Community Activity'>
      <fieldref var='activity.mailing-lists'/>
      <fieldref var='activity.jeps'/>
    </section>
    <section label='Plans and Reasoning'>
      <fieldref var='future'/>
      <fieldref var='reasoning'/>
    </section>
  </page>
  
  ...
</x>
    

The preceeding example demonstrates a similar layout to the one previous, but using sections instead of pages.

Sections MAY be nested, to produce a more granular partitioning of fields.

Example 4. Sections of fields (nested)

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout'>
    <section label='Personal Information'>
      <section label='Name'>
        <fieldref var='name.first'/>
        <fieldref var='name.last'/>
      </section>
      <section label='Contact Information'>
        <fieldref var='email'/>
        <fieldref var='jid'/>
      </section>
      <fieldref var='background'/>
    </section>
    <section label='Community Activity'>
      <fieldref var='activity.mailing-lists'/>
      <fieldref var='activity.jeps'/>
    </section>
    <section label='Plans and Reasoning'>
      <fieldref var='future'/>
      <fieldref var='reasoning'/>
    </section>
  </page>
  
  ...
</x>
    

If a <fieldref/> within a <section/> references a non-existent <field/>, that reference MUST be ignored.

3.3 Including Tables

Data forms tables (the <reported/> and <item/> elements) can also be included in the layout, using the <reportedref/> element. This element MAY be included anywhere the <fieldref/> is allowed, and MUST appear once at most.

If a <reportedref/> is specified when no <reported/> is available, the reference MUST be ignored.

4. Implementation Notes

4.1 Discovery

Form providers MAY attempt to discover if the recipient of a form supports styling, although implementations are NOT REQUIRED to do so. Discovery is implemened as defined in Service Discovery [2], using the namespace "http://jabber.org/protocol/xdata-layout" as a feature.

4.2 Field Distribution

In order to prevent the processing from becoming too complex, there are some restrictions in how fields are distributed within the layout.

First, all displayable, modifiable fields (e.g. all except fields of type "FIXED" or "HIDDEN") SHOULD be referenced by a page or section. Any that are not referenced MAY NOT be rendered, although implementations MAY provide some support for this. To have a "FIXED" field included in the layout, it MUST have a "var" attribute.

Second, the same field SHOULD NOT be referenced by more than one page or section. Additionally, a field SHOULD NOT be referenced by the same page or section more than once.

Finally, the order of layout elements SHOULD be maintained. Pages SHOULD be rendered in the order they are defined within the x:data form, and sections and fields SHOULD be rendered in the order they are defined or referenced within a page or section.

4.3 Page Labels and Descriptions

The "label" attribute for <page/> is OPTIONAL, although RECOMMENDED. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing). Usually the containing form's <title/> is used.

The <desc/> element for <page/> is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing). Usually the containing form's <instructions/> is used.

4.4 Section Labels and Descriptions

The "label" attribute for <section/> is OPTIONAL, although RECOMMENDED. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).

The <desc/> element for <section/> is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).

4.5 Internationalization/Localization

This JEP relies on the internationalization/localization mechanisms provided by XMPP Core [3]. Specifically, labels and descriptions MUST be appropriate for the locale indicated by the containing <form/> or stanza.

5. Security Considerations

There are no security considerations introduced by this JEP.

6. IANA Considerations

This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [4].

7. Jabber Registrar Considerations

The Jabber Registrar [5] shall register the namespace "http://jabber.org/protocol/xdata-layout" as a feature namespace.

8. Formal Definition

8.1 <page/> Root Element

The <page/> element is the root layout element for "http://jabber.org/protocol/xdata-layout" namespace. One <page/> elements are contained within the <x xmlns='jabber:x:data'/> element for each rendering page. The <page/> element possesses an attribute for its label, and contains child elements for its description, sections, and field and table references.

The 'label' attribute specifies the label for this <page/>. This attribute is OPTIONAL. Its value is any string.

8.2 <section/> Element

The <section/> element is used to further partition the layout within a <page/>. The <section/> element possesses an attribute for its label, and contains child elements for its description, sections, and field and table references.

The 'label' attribute specifies the label for this <section/>. This attribute is OPTIONAL. Its value is any string.

8.3 <fieldref/> Element

The <fieldref/> element is used to place a form field within the layout. The <fieldref/> possesses a single attribute to identify the field it references, and is otherwise empty.

The 'var' attribute specifies the form field being referenced. This attribute is REQUIRED, and its value SHOULD be equal to one of the <field/> "var" attributes in the containing form.

8.4 <reportedref/> Element

The <reportedref/> element is used to place a form "table" (as described by the <reported/< and <item/> elements) within the layout. The <reportedref/> element has no attributes or children.

8.5 <desc/> Element

The <desc/> element is used to provide additional textual information for a <page/> or <section/>. Its XML character data is the description text.

8.6 XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/xdata-layout'
    xmlns='http://jabber.org/protocol/xdata-validate'
    elementFormDefault='qualified'>

  <xs:element name='page'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='desc' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='section' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='fieldref' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='reportedref' minOccurs='0' maxOccurs='unbounded'/>
      </xs:choice>
      <xs:attribute name='label' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>
  
  <xs:element name='section'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='desc' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='section'/>
        <xs:element ref='fieldref'/>
        <xs:element ref='reportedref'/>
      </xs:choice>
      <xs:attribute name='label' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='fieldref'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='var' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
  
  <xs:element name='reportedref' type='empty'/>

  <xs:element name='desc' type='xs:string'/>
  
  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    


Notes

1. JEP-0004: Data Forms <http://www.jabber.org/jeps/jep-0004.html>.

2. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

3. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.

4. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

5. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.


Revision History

Version 0.1 (2004-08-10)

Initial version. (lw)


END