Constraints

6 Constraints

This chapter defines constraints that can be bound to form data. The combination of these constraints with an instance data node is called a model item. Taken together, these constraints are called model item constraints. The term Schema constraint refers only to XML Schema datatype constraints, while the term XForms constraint refers to XForms-specific constraints defined in the following section.

6.1 XForms Constraints

XForms constraints are defined via attributes of element bind. There are two kinds of constraints in XForms 1.0 as defined below.

Fixed constraints are static values that the XForms Processor evaluates only once. Such constraints typically encode type information.
Computed expressions are XPath expressions that provide a value to the XForms Processor. Such values are recomputed at certain times as specified by the XForms Processing Model (see 4 Processing Model). These expressions encode dynamic constraints such as the dependency among various data items. Computed expressions are not restricted to examining the value of the instance data node to which they apply. XPath expressions provide the means to traverse the instance data; more complex computations may be encoded as call-outs to external scripts.

The following constraints are available for all model items. For each constraint, the following information is provided:

Description
Computed Expression (yes or no)
Applies to children (inherited by instance data child elements and attributes)
Legal Values
Default Value

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 effect of this constraint is the same as placing attribute xsi:type 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.

A form may require certain values, and this requirement may be dynamic. 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:

If the bound instance data node is an element, the element must not have the xsi:nil attribute set to true.
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 an indication that a form control is required, and may provide immediate feedback, including limiting navigation. Chapter 4 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. 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 fields that depend 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.

Constraint relevant 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.

	`required="true"`	`required="false"`
`relevant="true"`	The form control (and any children) should be visible or available to the user. The XForms User Interface may indicate that a value is required.	The form control (and any children) should be visible or available to the user. The XForms User Interface may indicate that a value is optional.
`relevant="false"`	The form control (and any children) should be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed. The XForms User Interface may indicate that should the form control become relevant, a value would be required.	The form control (and any children) should be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed.

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 other values. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. Such computed value can be expressed as a computed expression using the values of other model items. The XForms Processing Model indicates when and how the calculation is performed.

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 4 Processing Model describes details such as immediate validation versus validation upon submit.

The XForms User Interface may indicate the validity of a form control.

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.

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.

6.2 Schema Constraints

Chapter 5 Datatypes described how XForms uses the XML Schema datatype system to constrain the value space of data values collected by an XForm. Such datatype constraints can be provided via an XML Schema. Alternatively, this section lists various mechanisms for attaching type constraints to instance data. Attributes xsi:schemaLocation and xsi:noNamespaceSchemaLocation are ignored for purposes for locating a Schema. XForms Basic processors have restricted Schema processing requirements as defined in 11.1.1 XForms Basic.

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 type constraints apply to the same node, the first definition in document order is used).

An XML Schema associated with the instance data.
An XML Schema xsi:type attribute in the instance data.
An XForms type constraint associated with the instance data node using XForms binding.
If no type constraint is provided, the data instance node defaults to type=xsd:string (default to string rule).

The following declares a datatype based on xsd:string with an additional constraining facet.

Type Constraint Using Schema.

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

This new datatype would then be associated with one or more model items through one of the methods outlined here.

Attaching A Type Constraint

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

This defines element first-name to be of type nonEmptyString.

Attaching Type Constraint Using XForms Binding

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

Here, we have attached type information to element first-name via element bind. This enables the XForms author extend external Schemas that she does not have the ability to change.

6.3 Additional Schema Examples

The following non-normative sections illustrate mapping between Schema concepts and data structures commonly used in form authoring.

6.3.1 Closed Enumeration

It is often necessary to restrict the allowable values of the associated instance data node to a closed list of alternatives, e.g., when asking for a credit card type. Here is a schema fragment that declares a datatype that allows enumerated values of an xsd:string.

Closed Enumeration

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="MusterCard"/>
    <xsd:enumeration value="Donor'sClub"/>
    <xsd:enumeration value="WildExpress"/>
    <xsd:enumeration value="EntryPermit"/>
  </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.

Open Enumeration

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="MusterCard"/>
        <xsd:enumeration value="Donor'sClub"/>
        <xsd:enumeration value="WildExpress"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

6.3.3 Union

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

The following defines a datatype that accepts either a creditCardType or bonusProgramType.

Union Of Types

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

6.3.4 Lists

Form controls such as selectMany collect more than one value. This corresponds to Schema list datatypes.

The following declares a list-derived datatype.

List Datatype

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

6.4 Binding

Binding is the glue that connects the separate pieces of XForms—here, we use XForms binding to associate instance data with model item constraints.

Binding is specified via binding expressions, which select nodes from the instance data. Binding expressions are based on XPath and are defined in chapter 7 XPath Expressions in XForms. This section describes how binding expressions are used when defining the XForms model.

6.4.1 bind

Element bind operates on a node-set selected from the instance data. Attributes on element bind encode XForms constraints to be applied to each node in the node-set.

XML Representation: <bind>

<bind ref = binding-expression
  <!-- model item constraints -->
  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: (bind)* -->
</bind>

ref - A binding expression that selects the set of nodes that this bind operates on.
model item constraints Model item constraints as defined in 6.1 XForms Constraints.

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

6.4.2 Rules For Binding Expressions

Not every possible XPath expression is acceptable as a binding expression. The following rules are used to limit the range of XPath expressions that can appear as valid binding expressions.

No dynamic predicates. Predicates are permitted, but such predicates must not depend on other form settings. Here are a few examples to illustrate this.
Permissible Binding Expressions
```
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
```
No invocation of any function that returns a node-set. Function calls are permitted, but not any that return a node-set.
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, form processing terminates with a fatal error.

6.4.3 Binding References

Binding references can be used to bind form controls to the underlying data instance as described in 8.12.2 Single Node Binding Attributes and 8.12.3 Nodeset Binding Attributes. Different attribute names, ref and 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:

First Node Rule

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
  <xforms:bind ref="/orderForm/shipTo/firstName" id="fn" />
</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.

UI Binding Using Attribute ref

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

UI Binding Using Attribute bind

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

Specifies Model Containing The Instance Explicitly

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

XForms Binding In Legacy HTML User Interface Controls

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


Table of Contents	Prev	Next	Bottom