This chapter is normative.
The XForms Model supports XML Schema built-in datatypes such as string
and custom datatypes defined using XML Schema syntax.
This chapter goes into further detail on the XForms simple syntax. XForms simple syntax is designed for easy hand-authoring and is targeted at HTML authors. Simple syntax provides an easy to learn interface for HTML authors; it achieves its simplicity by providing a smaller range of functionality than that afforded by XML Schemas. Specifically, XForms simple syntax allows the author to:
string;USPostalAddress;date of birth precedes date of graduation;
In order to stay simple, simple syntax does not permit the definition of reusable datatypes. However, Reusable datatypes can be defined in XML Schema and instantiated using XForms simple syntax as described here.
Later on, this chapter discusses ways to combine XForms simple syntax with XML Schema.
The following XForms Specific Properties are very similar in syntax to constraining
datatype facets. However, instead of constraining the value space of a datatype,
they add properties specific to XForms, such as readOnly or required.
The following properties are available for all datatypes, and their syntax is
explained later in this document.
Many XForms Specific Properties can be represented by the Dynamic Constraints Language, and may evaluate to values that can change at any time. XForms Processors that implement form controls need to dynamically update as the evaluated properties change.
Description: provides a document scoped unique identifier
Legal Values: only xsd:ID.
Default Value: none.
For the benefit of authors of XForms Dynamic Constraints or scripts, XForms
defines an id attribute widely across XForms elements. By defining
this as an XForms Specific Property, XML Schema-based or simple syntax XForms Models can be annotated with a unique identifier allowing convenient reference
from other parts of the document.
Description: provides a specific name for the declaring datatype.
Legal Values: only values of type xsd:NCNAME
Default Value: none.
Authors can associate a human-readable name with a declaring datatype through
the use of the name property. Each name should be
unique within the scope of the XForms
Model where it is declared.
When using simple syntax to define elements that appear in the instance
data, the name property provides the corresponding element
name, as shown in the atomic datatype example below.
Description: describes whether the value is restricted from changing. The ability of form controls to have focus and appear in the tab order is unaffected by this property.
Legal Values: any expression that evaluates to xfm:boolean.
Default Value: false.
In addition to restricting value changes, the readOnly property
provides a hint to the 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 tab order.
[Question: Should it be possible to make the readOnly
facet immutable? i.e. if an element in marked
as read-only and immutable, then the XForms
Processor could rely on the facet not
changing and employ a different rendering. Do we need a "constant"? ]
Description: describes whether a value is required before the instance data is submitted.
Legal Values: any expression that evaluates to xfm:boolean.
Default Value: false.
Often forms require certain values to be entered. Within XForms, this may be
a static requirement and defined in an XML Schema (e.g. xsd:minOccurs="1").
Alternatively a value may only be required if some condition is satisfied. Future
versions of this specification will describe details such as immediate validation
vs. onsubmit validation.
Except as noted below, the required property does not provide
a hint to the user interface regarding visibility, focus, or tab 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.
Note: Suspend and resume operations are not restricted by the required
property.
Note: As with the constraining facets, conflicting properties are resolved
by choosing the most restrictive. For instance, if required="false"
was specified but xsd:minOccurs="1" was also defined by the Schema
for the element, the element would still be required.
[Question: it might be useful to set the default for the required attribute for an entire XForms Model. What should the default default be? How could we assign a default for a single XForms Model? This could apply to other attributes as well, e.g. readOnly, etc..]
[Question: Null values, XML Schema nullable="true".
We have not yet addressed the subject of null. It is of particular
relevance for required items.]
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.
Legal Values: any expression that evaluates to xfm: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 information
about their car if they have indicated that they own one. In XForms, this occurs
through the relevant property.
The relevant property provides hints to the user interface regarding
visibility, focus, and tab order. In general, when true, associated
form controls should be made visible. When false, associated form controls should be hidden, though an XForms Processor may only disable the form controls. In either case, the form controls should be removed from the tab order
and not allowed focus.
The following table shows the 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 user interface may indicate that a value is required. | The form control (and any children) should be visible or available to the user. The 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 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. |
Description: indicates that the value of the declaring datatype is to be dynamically calculated.
Legal Values: any expression that evaluates to a datatype compatible with the declaring 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 an Dynamic Constraint using the values of other model items.
Description: indicates that the value of the declaring datatype is to be dynamically validated.
Legal Values: any expression that evaluates to xfm:boolean
Default Value: true.
An XForms Model may include model items that need to be validated. The specified
Dynamic Constraint is invoked every time the value of the declaring datatype
changes. The expression must evaluate to true for the model item
to be considered valid. Future versions of this specification will describe
details such as immediate validation vs. onsubmit validation.
Dynamic Constraints used here are not restricted to examining the instance data item they are invoked on. The Dynamic Constraints Language provides the means to traverse the instance data, as well as call-outs to external script.
The user interface may indicate whether a form control is currently valid or invalid.
[Question: Will the validate property be evaluated
on all the parent or child model items
whenever a value changes? We need to make sure that inter-model
item constraints will get evaluated.]
The basic datatypes defined by XForms can be used individually or aggregated to build appropriate structures for use in XForms applications. XForms provides a number of structures that are mapped to corresponding constructs in XML Schema.
XForms Processors that are Schema compliant can use arbitrarily complex Schema constructs in the XForms Model. The full Schema syntax can be found in [XSchema-1] and [XSchema-2].
Description: inserts an atomic datatype into the XForms Model.
Simple Syntax: for each atomic datatype in the Datatypes chapter, the simple syntax specifies an element with a matching name in the XForms Namespace. Optional allowed attributes in the XForms Namespace are the XForms constraining facets and XForms Specific Properties, except as noted below. The element content is empty, except as noted below:
<string> has 0 or more <mask> children
representing the list members of the mask facet. mask
is not allowed as an attribute.<money> has 0 or more <allowedCurrency>
children representing the list members of the allowedCurrency
facet. allowedCurrency is not allowed as an attribute.<uri> has 0 or more <scheme> children
representing the list members of the scheme facet. scheme
is not allowed as an attribute.<binary> has 0 or more <mediaType>
children representing the members of the mediaType facet. mediaType
is not allowed as an attribute.enumeration facet is described below.name XForms Specific Property is required.<money> may not be considered an atomic
datatype (see note in the Datatypes chapter),
and thus may be considered a structure rather than a datatype.A method is needed to include datatypes defined elsewhere (in either XForms or Schema format) into the XForms Model. One syntax proposal is:
<xfm:element type="...Schema or XForms datatype" ... />Example Simple Syntax:
Example Equivalent Schema Syntax:
<xsd:element name="foo"> <xsd:complexType> <xsd:restriction base="xfm:string"> <xfm:minLength value="1"/> </xsd:restriction> </xsd:complexType> </xsd:element>
Second Example Simple Syntax:
Second Example Equivalent Schema Syntax:
<xsd:element name="foo"> <xsd:complexType> <xsd:restriction base="xfm:binary"> <xsd:mediaType value="image/jpg"/> <xsd:mediaType value="image/png"/> </xsd:restriction> </xsd:complexType> </xsd:element>
Description: inserts an atomic datatype, with a restricting enumeration, into the XForms Model. Enumerations are mentioned separately here only because of their special syntax.
Simple Syntax: an enumerated datatype is declared as an atomic datatype above, with the additional syntax as follows:
<value> children with string content representing
the individual enumerated value.choices which contains an XForms Dynamic Constraint
that returns a list of values at runtime. This list is used in addition to
any <value> children.enum can be either open
(the default) or closed. When closed, the enumeration
is strictly limited to the defined values. When open, other values
are allowed, as long as they satisfy all other constraining facets.Note that an open enumeration is useful for scenarios like the following, where a multiple choice question has an "other" option:
Note: functionality similar to open enumerations is available in XML Schema through the combination of union and enumeration features.
Simple Syntax:
Equivalent Schema Syntax:
<xsd:element name="foo" enum="closed"> <xsd:complexType> <xsd:restriction base="xfm:string"> <xsd:enumeration value="Mastercard"/> <xsd:enumeration value="Diner's Club"/> <xsd:enumeration value="American Express"/> </xsd:restriction> </xsd:complexType> </xsd:element>
Simple Syntax with Dynamic Choices:
Description: allows aggregate hierarchical arrangement of datatypes.
Simple Syntax: the simple syntax specifies the element <group>,
with the possible attributes representing the XForms Specific Properties.
Example Simple Syntax:
Example Equivalent Schema Syntax:
<xsd:group name="person"> <xsd:sequence> <xsd:element name="personName" type="xfm:string"/> <xsd:element name="personTitle" type="xfm:string"/> </xsd:sequence> </xsd:group>
Note that here element person does not define a new datatype;
when mapped to XML Schema syntax; i.e. person is an anonymous type
that cannot be reused.
Note: The Working Group is looking for feedback on whether the option for an unordered group is necessary in addition to the ordered group as described above.
Description: allows differing datatypes to be bound to a single model item.
Simple Syntax: the simple syntax specifies the element <union>,
with the possible attributes representing the XForms Specific Properties. Child
datatypes do not require the name attribute.
Example Simple Syntax:
<xfm:union name="weekday"> <xfm:string enum="closed"> <xfm:value>Monday</xfm:value> <xfm:value>Tuesday</xfm:value> <xfm:value>Wednesday</xfm:value> <xfm:value>Thursday</xfm:value> <xfm:value>Friday</xfm:value> <xfm:value>Saturday</xfm:value> <xfm:value>Sunday</xfm:value> </xfm:string> <xfm:number min="1" max="7" scale="0"/> </xfm:union>
Example Equivalent Schema Syntax:
<xsd:element name="weekday"> <xsd:simpleType> <xsd:union> <xsd:simpleType> <xsd:restriction base="xfm:string"> <xsd:enumeration value="Monday"/> <xsd:enumeration value="Tuesday"/> <xsd:enumeration value="Wednesday"/> <xsd:enumeration value="Thursday"/> <xsd:enumeration value="Friday"/> <xsd:enumeration value="Saturday"/> <xsd:enumeration value="Sunday"/> </xsd:restriction> </xsd:simpleType> <xsd:simpleType> <xsd:restriction base="xfm:decimal"> <xsd:maxInclusive value="7"/> <xsd:minInclusive value="1"/> <xsd:scale value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:union> </xsd:simpleType> </xsd:element>
[Issue: Is the name attribute required for each of the elements within a union?]
Description: allows homogeneous collections (i.e., all members of an array are the same structure).
Simple Syntax: the simple syntax specifies the element <array>,
with the possible attributes representing the XForms Specific Properties.
Two additional attributes are defined: minOccurs and maxOccurs.
The value of these must be either a non-negative xfm:number or
for maxOccurs, "unbounded". These limit
the minimum and maximum number of datatypes in the collection, respectively.
The default for both is 1.
Note: The author has the ability to specify whether a containing element for
the repeating elements is produced. If a name is specified for
the array then a containing element will be created where the containing element
name will be derived from the name of the array. If no name is
provided for the array then no containing element will be created.
Example Simple Syntax:
Example Equivalent Schema Syntax:
<xsd:element name="children"> <xsd:complexType> <xsd:sequence> <xsd:element name="child" type="xfm:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element>
Second Example Simple Syntax:
Second Example Equivalent Schema Syntax:
Description: allows alternative structures to be defined within simple syntax and for a Dynamic Constraint to determine which should be created in the instance data.
Simple Syntax: the simple syntax specifies the element <switch>,
with the possible attributes representing the XForms Specific Properties. The
content model consists of <case> elements, which in turn
contain datatype declarations. The <case> elements have two
attribute: name from the XForms Specific Properties, and condition,
which consists of a script to validate.
Example Simple Syntax:
<xfm:switch name="address"> <xfm:case name="us" condition="property::locale is 'US'" > <xfm:string name="street"/> <xfm:string name="city"/> <xfm:string name="state"/> <xfm:string name="zip"/> </xfm:case> <xfm:case name="uk" condition="property::locale is 'UK'" > <xfm:string name="street"/> <xfm:string name="town"/> <xfm:string name="county"/> <xfm:string name="postcode"/> </xfm:case> <xfm:case name="default"> <xfm:string name="street"/> <xfm:string name="town"/> <xfm:string name="county"/> <xfm:string name="postcode"/> </xfm:case> </xfm:switch>
Example Equivalent Schema Syntax:
<xsd:element name="address"> <xsd:complexType> <xsd:choice> <xsd:sequence> <xsd:element name="street" type="xfm:string"/> <xsd:element name="city" type="xfm:string"/> <xsd:element name="state" type="xfm:string"/> <xsd:element name="zip" type="xfm:string"/> </xsd:sequence> <xsd:sequence> <xsd:element name="street" type="xfm:string"/> <xsd:element name="town" type="xfm:string"/> <xsd:element name="county" type="xfm:string"/> <xsd:element name="postcode" type="xfm:string"/> </xsd:sequence> <xsd:sequence> <xsd:element name="street" type="xfm:string"/> <xsd:element name="town" type="xfm:string"/> <xsd:element name="county" type="xfm:string"/> <xsd:element name="postcode" type="xfm:string"/> </xsd:sequence> </xsd:choice> </xsd:complexType> </xsd:element>
Note that this capability is an extension of the XML Schema choice.
Note: This impacts both the user interface and the XForms Model.
An XForms Model can exploit the switch construct to define a number of variants
and to determine at runtime which single variant should be created in the instance.
The sequence is important, the first case whose condition evaluates
to true will appear in the instance. If no conditions evaluate
as true then a default may be produced by specifying a variant
which has no condition associated with it.
XML Schema allows annotations as foreign namespaced attributes. Adding elements is more problematic. Future versions of this specification will specify in greater detail how XForms datatypes, properties, and structures can be used within XML Schema.
XForms authors may wish to reuse datatypes and structures already defined in an external XML Schema. For use in an XForms application, such schemas may need to be annotated using XForms dynamic properties for expressing run-time constraints.
Future versions of this specification will describe how to add XForms annotations to an external Schema by reference without modifying the original Schema.
One syntax proposal is:
<xfm:annotateElement elementID="age" min="17" max="63" />