6.1.1 type

Description: associates a Schema datatype.

Computed Expression: No

Applies to children: No

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

Default Value: xsd:string

The meaning of this constraint is the same as placing an xsi:type attribute on the instance data.

6.1.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 constraint.

Computed Expression: Yes

Applies to children: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: false

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

In addition to restricting value changes, the readOnly constraint provides a hint to the XForms User Interface. Form controls bound to instance data with the readOnly constraint should indicate that entering or changing the value is not allowed. This specification does not define any effect on visibility, focus, or navigation order.

6.1.3 required

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

Computed Expression: Yes

Applies to children: 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 constraint 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 constraint 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.

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

6.1.4 relevant

Description: indicates whether the model item is currently relevant to the rest of the XForms Model. Instance data nodes with relevant=false, are not serialized for submission.

Computed Expression: Yes

Applies to children: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: true

Many forms have data entry 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 constraint indicates that the XForms Processor should render a form control, and conversely, when evaluating to false, indicates that the form control should be rendered specially (grayed out, hidden, etc.).

The relevant constraint 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.

6.1.5 calculate

Description: supplies an expression used to calculate the value of the associated instance data node.

Computed Expression: Yes

Applies to children: No

Legal Values: Any XPath expression

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.

6.1.6 isValid

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

Computed Expression: Yes

Applies to children: No

Legal Values: Any expression that is convertible to boolean

Default Value: true

When evaluating to false, the associated model item is not valid; the converse is not necessarily true. Chapter 11 Processing Model describes details such as immediate validation versus 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.

6.1.7 maxOccurs

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

Computed Expression: No

Applies to children: No

Legal Values: xsd:integer or "unbounded"

Default Value: "unbounded"

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

6.1.8 minOccurs

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

Computed Expression: No

Applies to children: No

Legal Values: xsd:integer

Default Value: 0.

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

6.2.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, and if multiple datatypes apply to the same node, the first definition in document order is used):

1. An XML Schema xsi:type attribute in the instance data.

2. An XML Schema associated with the instance data.

3. An XForms type constraint associated with the instance data node.

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 an additional constraining facet would be accomplished by the following in a Schema:

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

<!-- Datatype through Schema xsi:type -->
<my:first-name xsi:type="nonEmptyString"/>

<!-- Datatype through XForms constraint -->
<instance>
  <my:first-name />
</instance>

<bind type="nonEmptyString" ref="/my:first-name"/>

6.3.1 Closed Enumeration

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

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="Mustercard"/>
    <xsd:enumeration value="Donor's Club"/>
    <xsd:enumeration value="World Express"/>
  </xsd:restriction>
</xsd:simpleType>

6.3.2 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.

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="Mustercard"/>
        <xsd:enumeration value="Donor's Club"/>
        <xsd:enumeration value="World Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

6.3.3 Union

It may be desirable for data collection purposes 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 a Schema:

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

6.3.4 Lists

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

Declaring a list-derived datatype would be accomplished with the following in a Schema:

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

6.4.1 bind

The bind element represents a node-set selected from the instance data. A series of attributes on the element correspond to individual XForms constraints to be applied to each node in the node-set.

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

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

6.4.2 Binding Constraints

Not every possible XPath expression is acceptable 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: elem
   permitted: elem[1]
   permitted: elem[last()]
   permitted: elem[@id="zip"]  if @id is not bound to a form control
   forbidden: elem[@attr="xy"]  if @attr is 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 form processing terminates with a fatal error.

6.4.3 Binding References

References to node-sets are attached to form controls through binding references, described in 8.12.2 Single Node Binding Attributes and 8.12.3 Nodeset Binding Attributes. Different attribute names, ref vs. nodeset, distinguish between a single node and a node-set respectively.

First node rule: When a single-node binding expression selects a node-set of size > 1, the first node in the node-set is used. This has no effect on the individual nodes nor the set of nodes selected by any particular bind element.

Consider a document with the following XForms declarations:

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
 <xforms:bind ref="/orderForm/shipTo/firstName"
          id="fn" type="xsd:string"
          required="true"/>
</xforms:model>

The following examples show three ways of binding user interface control xforms:input to instance element firstName declared in the model shown above.

<xforms:input ref="/orderForm/shipTo/firstName">...

<xforms:input bind="fn">...

<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...

The XForms binding mechanism allows other XML vocabularies to bind user interface controls to an XForms model using any of the techniques shown here. As an example, XForms binding attribute bind might be used within legacy HTML user interface controls as shown below.

<html:input type="text" name="..." xforms:bind="fn"/>