5.2.1 type

Description: associates a Schema datatype.

Computed Expression: No

Legal Values: Any xsd:QName representing an in-scope Schema simpleType.

Default Value: xsd:anyType

The concept of typed data is important to forms. The assignment of a particular datatype to a model item affects validation of the data it can accept, as well as affecting which form controls to which it can bind.

5.2.2 readOnly

Description: describes whether the value is restricted from changing. The ability of form controls to have focus and appear in the navigation order is unaffected by this property.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: false

When evaluating to true, this property indicates that the XForms Processor should not allow any changes to the bound instance data node.

In addition to restricting value changes, the readOnly property provides a hint to the XForms User Interface. Form controls bound to a model item with the readOnly property should indicate that entering or changing the value is not allowed. The hint provided has no effect on visibility, focus, or navigation order.

5.2.3 required

Description: describes whether a value is required before the instance data is submitted.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: false

Often forms require certain values to be entered. This may be a static requirement, or may only be the case if some condition is satisfied. When evaluating to true, this property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as:

1. If the bound instance data node is an element, the element must not have the xsi:nil attribute set to true.

2. The value of the bound instance data node must be convertible to an XPath string with a length greater than zero.

Except as noted below, the required property does not provide a hint to the XForms User Interface regarding visibility, focus, or navigation order. XForms authors are strongly encouraged to make sure that form controls that accept required data are visible. An XForms Processor may provide a unique indication that a form control is required, and may provide immediate feedback, including limiting navigation, for required form controls.

The chapter 11 Processing Model contains details on how the XForms Processor enforces required values.

5.2.4 relevant

Description: indicates whether the model item is currently relevant to the rest of the XForms Model. XForms Processors would typically not render an associated form control, including children, when the value is false.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: true

Many forms have fields dependent on other conditions. For example, a form might ask whether the respondent owns a car. It is only appropriate to ask for further information about their car if they have indicated that they own one.

When evaluating to true, this property indicates that the XForms Processor should render a form control, and conversely, when evaluating to false, indicates that the form control should not be rendered.

The relevant property provides hints to the XForms User Interface regarding visibility, focus, and navigation order. In general, when true, associated form controls should be made visible. When false, associated form controls should be made unavailable, removed from the navigation order, and not allowed focus.

The following table shows the user interface interaction between required and relevant.

5.2.5 calculate

Description: indicates that the instance data node associated with the model item is to be dynamically calculated.

Computed Expression: Yes

Legal Values: Any expression that is convertible to an XPath datatype compatible with the associated XML Schema datatype

Default Value: none

An XForms Model may include model items that are computed from the other values elsewhere. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. The computed value can be represented as a computed expression using the values of other model items. The XForms Processing Model indicates how and when the calculation is recomputed.

5.2.6 isValid

Description: specifies the predicate that needs to be satisfied for the associated instance data node to be considered valid.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: true

An XForms Model may include model items that need to be revalidated. When evaluating to true, indicates that the model item is considered valid. The chapter 11 Processing Model describes details such as immediate validation vs. validation upon submit.

Computed expressions used here are not restricted to examining the instance data node they are invoked on. XPath, plus the extensions in this specification, provide the means to traverse the instance data, as well as call-outs to external script, enabling potentially complex validations.

The XForms User Interface may indicate whether a form control is currently valid or invalid.

5.2.7 maxOccurs

Description: for repeating structures, indicates the maximum number of allowed child elements.

Computed Expression: No

Legal Values: xsd:integer or "unbounded"

Default Value: "unbounded"

For model item elements that are repeated, this optional property specifies a maximum number of allowed child elements. This only applies to element nodes selected as part of a repeat sequence (9.3 Repeating Structures).

5.2.8 minOccurs

Description: for repeating structures, indicates the minimum number of allowed child elements.

Computed Expression: No

Legal Values: xsd:integer

Default Value: 0.

For model item elements that are repeated, this optional property specifies a minimum number of allowed child elements. This only applies to element nodes selected as part of a repeat sequence (9.3 Repeating Structures).

5.3.1 bind

The bind element represents a node-set selected from the instance data. A series of attributes on the element correspond to individual model item properties, which are applied to each node in the node-set.

<bind
  id = xsd:ID
  ref = binding-expression
  type = xsd:QName
  readOnly = model-item-property
  required = model-item-property
  relevant = model-item-property
  isValid = model-item-property
  calculate = model-item-property
  maxOccurs = xsd:nonNegativeInteger or "unbounded"
  minOccurs = xsd:nonNegativeInteger
>
  <!-- Content: (##empty) -->
</bind>

Each bind element selects a node-set from the instance data, and applies any model item properties. When additional nodes are added through the insert action, the newly added nodes are included in any node-sets matched by binding expressions.

5.3.2 Binding Constraints

Not every possible XPath expression is accepted as a binding expression. The following constraints are placed upon binding expressions:

1. No dynamic predicates. Predicates are permitted, but any predicates used must not alter the returned node-set based on other form settings. For example:

   permitted: foo
   permitted: foo[1]
   premitted: foo[last()]
   permitted: foo[@id="zip"] ONLY if @id is not bound to a form control
   forbidden: foo[@bar=""] with @bar bound to a form control

2. No dynamic variables. The XForms specification does not provide any variables.

3. No invocation of any function that returns a node-set. Function calls are permitted, but not any that return a node-set.

4. No invocation of any function with side-effects. All functions defined in the XForms specification are side-effect-free. Any extension functions should also be side-effect-free.

Upon detecting a binding expression that violates any of the above constraints, an exception will be thrown.

5.3.3 Binding References

References to node-sets are attached to form controls through binding references, described in 7.14.2 Single Node Binding Attributes and 7.14.3 Nodeset Binding Attributes. Different attribute names, ref vs. nodeset, distinguish between a single node, and a node-set, respectively. When a single-node binding expression selects a node-set of size > 1, the "first node" rule is applied, utilizing only the first node in the node-set. This has no effect on the individual nodes nor the set of nodes selected by any particular bind element.

Examples:

<xform:input bind="id-of-bind-element">
   <xform:caption>Your first name</xform:caption>
</xform:input>

Alternatively, an inline binding expression can be used with the ref and xform attributes.

<xform:input xform="id-of-xform-element" ref="binding-expression">
   <xform:caption>Your first name</xform:caption>
</xform:input>

These attributes can also be used on non-XForms form controls, for instance XHTML:

<html:input type="text" name="..." xform:bind="id-of-bind-element"/>

5.3.4 Binding Example

Consider a document with the following XForms declarations:

<xform:instance xmlns="">
  <orderForm>
    <shipTo>
      <firstName>John</firstName>
    </shipTo>
  </orderForm>
</xform:instance>

and

<xform:bind ref="orderForm/shipTo/firstName"
  id="fn"
  type="xsd:string"
  required="true"/>

An input form control could be attached to the instance data directly, or indirectly:

<xform:input ref="orderForm/shipTo/firstName">...</xform:input>
<!-- or -->
<xform:input bind="fn">...</xform:input>

5.4.1 Atomic Datatype

The XForms Processing Model applies XML Schema facets as part of the validation process. At the simplest level, it is necessary to associate a set of facets (through a Schema datatype) with a model item. This has the effect of restricting the allowable values of the associated instance data node to valid representations of the lexical space of the datatype.

The set of facets may be associated with a model item in one of the following ways (only the first that applies is used):

1. An xsi:type attribute (restricted to simpleTypes in XForms Basic) on the initial instance data.

2. (XForms Full only) An XML Schema associated with the instance data.

3. A type model item property.

4. Otherwise, the datatype is treated as xsd:string (default to string rule).

Example Schema Syntax: declaring a datatype based on an xsd:string plus additional constraining facet would be accomplished by the following in an external Schema:

<xsd:simpleType name="restrictedString">
  <xsd:restriction base="xsd:string">
    <xsd:minLength value="1"/>
  </xsd:restriction>
</xsd:simpleType>

5.4.2 Closed Enumeration

Often it is necessary to restrict the allowable values of the associated instance data node to a closed list of alternatives.

Example Schema Syntax: declaring a datatype allowing enumerated values of an xsd:string would be accomplished with the following in an external Schema:

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="Mastercard"/>
    <xsd:enumeration value="Diner's Club"/>
    <xsd:enumeration value="American Express"/>
  </xsd:restriction>
</xsd:simpleType>

5.4.3 Open Enumeration

A special case of enumerated datatypes is the common form design pattern of a list, with an 'other, please specify' choice. This is referred to as an open enumeration.

Example Schema Syntax: declaring an open enumeration is possible through a combination of union and enumeration features, with the following in an external Schema:

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Mastercard"/>
        <xsd:enumeration value="Diner's Club"/>
        <xsd:enumeration value="American Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

5.4.4 Union

It may be desirable for data collection purpose to allow an instance data item to be a valid lexical value of one among several datatypes. Unions are defined in XML Schema.

Example Schema Syntax: declaring a datatype allowing either a creditCardType or bonusProgramType value would be accomplished with the following in an external Schema:

<xsd:simpleType>
  <xsd:union memberTypes="creditCardType bonusProgramType"/>
</xsd:simpleType>

5.4.5 Multiple Selection

Some form controls, such as selectMany, have the notion of supporting more than one simpleType value at any given time. This corresponds with Schema list datatypes.

Example Schema Syntax: declaring a list-derived datatype would be accomplished with the following in an external Schema:

<xsd:simpleType name="listOfMyIntType">
  <xsd:list itemType="xsd:int"/>
</xsd:simpleType>

5.4.6 Repeating Line Items

It is common for certain types of forms, such as order forms, to contain repeating structures, typically line items.

Chapter 9 XForms User Interface contains details on representing this with XForms User Interface form controls, as well as details for how this relates to the instance data in chapter 11 Processing Model.

5.4.7 Alternate Representation

In some forms, alternate representations might be necessary for underlying instance data structures.

Example Schema Syntax: a Schema choice element is roughly analogous to this, although XForms uses a more dynamic version. Examples of this are found in 9 XForms User Interface