4 Datatypes


Contents

This chapter is normative.

4.1 Introduction

This chapter sets out a core set of datatypes that all XForms Processors support. The XForms Model chapter describes the different ways that an XForms Model can be represented. For the purposes of this chapter, the most important distinction is "simple syntax" (defined by XForms) versus "Schema Syntax" (defined in [XSchema-1] and [XSchema-2]).

All XForms datatypes reuse and extend XML Schema [XSchema-2] datatypes, including all the constraining facets. These are called static facets, since they are predefined and unchangeable. In many cases, XForms defines like-named facets in the XForms namespace, which are semantically equivalent, however an XForms Dynamic Constraint can be used to define the facet. This allows the XForms facets to be dynamic, and freely change their evaluated constraint at run-time.

The XForms Model uses these datatypes to define how the submitted values bind to the instance data. For instance, here is how you could define a "leavingDate", bound to an element in the instance data, which must have a value later in time than a "startingDate":

<date name="leavingDate" min="startingDate" />
<date name="startingDate" max="leavingDate" />

Here the constraints are totally dynamic, and in fact mutually dependent.

It is important to note that XForms dynamic constraints cannot change any underlying static constraints specified in an XML Schema.

XForms Validation Rule: Whenever XForms facets and Schema facets have potentially conflicting values, the one that restricts the value space to the smallest subset is used.

For instance, here's an example of an XForms facet that conflict with underlying schema static constraints:

Example of conflicting facets:
<xsd:complexType name="myNumber">
  <xsd:restriction base="xform:number">
    <xsd:maxInclusive value="20"/>
    <xform:maxInclusive value="100"/>
  </xsd:restriction>
</xsd:complexType>
This example shows a Schema maxInclusive facet alongside a conflicting XForms maxInclusive facet. In this case, the XForms facet would have no effect, since the more restrictive constraint, value="20", is used.

Like XML Schema, XForms datatypes are based on value spaces which have lexical space representations. For each datatype defined, the following will be specified:

4.2 String

The XForms datatype string is derived from the XML Schema [XSchema-2] datatype string.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

Example: A value of "hello" would be represented as:

XForms Facets defined:

The XForms string datatype inherits the static facets of its XML schema base datatype, which are:

length, minLength, maxLength, pattern, enumeration, whiteSpace

4.3 Boolean

The XForms datatype boolean is derived from the XML Schema [XSchema-2] datatype Boolean.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

Example: A true value would be represented as:

XForms Facets defined: No additional facets.

The XForms Boolean datatype inherits the static facets of its XML schema base datatype, which are:

pattern, whiteSpace

4.4 Number

The XForms datatype number is derived from the XML Schema [XSchema-2] datatype decimal.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

Example: A value of -42 would be represented as:

XForms Facets defined:

The XForms number datatype inherits the static facets of its XML schema base datatype, which are:

precision, scale, pattern, whiteSpace, enumeration, maxInclusive, maxExclusive, minInclusive, minExclusive

Numeric calculations should be performed on the internal value space values (not the lexical space values) using decimal arithmetic, except where the resource constraints preclude this.

4.5 Currency

The XForms datatype currency is derived from the XForms datatype string.

Lexical Representation: a list of 3 character currency codes, as defined in defined in [ISO 4217]. This is considered an open list--additional currency codes not defined there are allowable.

Canonical Representation: No leading or trailing whitespace is allowed.

Example: A value 'US Dollars' would be represented as:

XForms Facets defined: The XForms currency datatype inherits all facets of its XForms base datatype. These are:

4.6 Monetary Values

[Editor's Feedback Request 4.6.money: The monetary datatype is essentially xform:number plus an xform:currency designator. The XForms Working Group does not have consensus on whether a momentary datatype should be an atomic datatype, or a new compound type mechanism is needed for this special case. Both alternatives are specified here. We would appreciate feedback on which alternative is better.]

Alternative A - atomic datatype

The XForms datatype money is derived from the XForms datatype number.

Lexical Representation: currency is represented by concatenating the xform:currency string to the end of the xform:number string, with no whitespace in between.

Canonical Representation: both the xform:number and xform:currency portions must be their individual canonical representation.

Example: A value of 4.37 Euro would be represented as:

XForms Facets defined:

Alternative B - compound datatype

The XForms datatype money datatype consists of two parts, the currency identifier and the value. The currency datatype is derived from the XForms datatype currency. The value subtype is derived from the XForms datatype number.

Lexical Representation: as a compound datatype, there is no single value space, and therefore no single lexical space. See example below.

Canonical Representation: See example below.

Example: A value of 4.37 Euro would be represented as two distinct lexical values:

Editor's Note: This is essentially a shortcut for separately defining instances of the xform:number and xform:currency datatypes, but without independently settable facets. When mapped to instance data, if the datatype is bound to an element, the xform:number and xform:currency portions can be bound to child elements or attributes, possibly in the XForms namespace. If the datatype is bound to an attribute, there is no way to present both portions, since attributes have no children.

XForms Facets defined: same as alternative A.

4.7 Date

The XForms datatype date is derived from the XML Schema [XSchema-2] datatype date.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

Example: A value of '31st January 2000' would be represented as:

A value of '4 years from now' would be represented as:

A value of 'right now' would be represented as a Dynamic Constraint:

XForms Facets defined:

The XForms date datatype inherits the static facets of its XML schema base datatype, which are:

duration, period, pattern, enumeration, whiteSpace, maxInclusive, maxExclusive, minInclusive, minExclusive

Note that a special Dynamic Constraint function, now() is defined. This can be used to specify any min or max facet. Additionally, time values relative to the submission date can be specified using positive or negative durations. The syntax for dates and durations are as per the subset of [ISO 8601] specified for XML Schemas for time instants and durations.

It is recommended that XForms Processors offer date and time pickers which offer date validation and choices from the distant past to the distant future. Small portable devices will likely validate and pick only dates in the range likely for business appointments near the current time; whereas, a full-featured desktop browser, which supports use cases such as historical records search and long-term financial obligations, should offer an extended range of dates. As always, the server must assume that the client has not performed the validation specified in the XForms Model and perform its own validation on the entered date.

4.8 Time

The XForms datatype time is derived from the XML Schema [XSchema-2] datatype time.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema. For XForms Processors that have access to the correct local time zone, this must be included in the canonical representation.

Example: A value of '1:20 PM Eastern Standard Time' (5 hours behind of UTC) would be represented as:

XForms Facets defined:

The XForms time datatype inherits the static facets of its XML schema base datatype, which are:

duration, period, pattern, enumeration, whiteSpace, maxInclusive, maxExclusive, minInclusive, minExclusive

4.9 Duration

The XForms datatype duration is derived from the XML Schema [XSchema-2] primitive datatype timeDuration.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

Example: A value of '1 year, 2 months, 3 days, 10 hours, and 30 minutes' would be represented as:

A value of 'negative 120 days' would be represented as:

XForms Facets defined:

The XForms duration datatype inherits the static facets of its XML schema base datatype, which are:

pattern, enumeration, whiteSpace, maxInclusive, maxExclusive, minInclusive, minExclusive

[Editor's Feedback Request 4.9.precision: Months only provide an approximate means to specify duration since individual months vary in length. The same holds true for years. Is this acceptable?]

4.10 URI

The XForms datatype uri is derived from the XML Schema [XSchema-2] datatype uriReference.

Lexical Representation: uri represents a Uniform Resource Identifier (URI) Reference as defined in Section 4 of [RFC 2396]. A uri may be absolute or relative, and may have an optional fragment identifier. This datatype is used for values representing an absolute Uniform Resource Identifier (URI) as defined in [RFC 2396].

Canonical Representation: as in Schema.

Editor's Note: currently an open issue in Schema is how to handle non-ASCII values in either the URI value space or lexical space. We plan to adopt whatever solution the XML Schema Working Group chooses.

Example: A value of 'http://www.w3.org/' would be represented as:

XForms Facets defined:

The XForms uri datatype inherits the static facets of its XML schema base datatype, which are:

length, minLength, maxLength, pattern, enumeration, whiteSpace

The uriScheme facet allows you to restrict URIs to a limited set of URI schemes. For instance, http or mailto. XForms Processors are encouraged to provide a means to pick or browse addresses, for instance an email address picker. The XForms User Interface may allow users to enter relative URIs, but the internal values will always be absolute URIs.

4.11 Binary

The XForms datatype binary is derived from the XML Schema [XSchema-2] datatype binary.

Lexical Representation: as in Schema.

Canonical Representation: as in Schema.

XForms Facets defined:

The XForms binary datatype inherits the static facets of its XML schema base datatype, which are:

encoding, length, minLength, maxLength, pattern, enumeration, whiteSpace

This is a datatype for use with data appropriate to specific Internet media types. The XForms Processor could use the media type to determine how to prompt the user. For example, an image could be acquired from a digital camera, an image scanner, or a disk file.

In simple syntax, here is a possible representation for a model item that accepts JPEG or PNG images:

<binary name="photo">
  <mediaType>image/jpeg</mediaType>
  <mediaType>image/png</mediaType>
</binary>

Binary data could be packaged either in-place as part of XML instance data or held separately and referenced from XML. Further work is needed to cover the details.

[Editor's Feedback Request 4.11.binary-constraints: Is there a need for facets to further constrain the data, for instance, to place limits on the size of the data? Other kinds of constraints may be appropriate, for example, for audio clips, you might want to set constraints on the bit rate and duration.]

4.12 XForms Facets

For each XForms facet, the following is specified:

4.12.1 XForms Facet: allowCurrency

Availability: Simple, Schema.

Description: indicates allowable currency datatypes.

Legal Values: a list of zero or more 3 letter currency codes (of subtype currency), e.g. USD or GBP.

Default Value: unrestricted.

Applies to:

4.12.2 XForms Facet: enumeration

Availability: Simple, Schema.

Description: restricts the value space of the datatype to a specified list of possible values.

Legal Values: a list of datatype values compatible with the parent datatype.

Default Value: unrestricted.

Applies to:

Editor's Note: the value of an XForms enumeration facet will almost always be a Dynamic Constraint, since the Schema enumeration facet handles static enumerations.

4.12.3 XForms Facet: length

Availability: Simple, Schema.

Description: restricts the value space of the datatype to only values which have the specified length. For string-based and binary-based datatypes, length is measured as in [XSchema-2].

Legal Values: any expression that evaluates to a non-negative xform:number.

Default Value: unrestricted.

Applies to:

4.12.4 XForms Facet: mask

Availability: only Simple.

Description: restricts the value space of the datatype according to a specified set of rules.

Legal Values: a list of 0 or more values representing legal mask syntax.

Default Value: unrestricted.

Applies to:

XML Schema has defined a Regular Expression language which is "similar to the regular expression language used in the Perl Programming language", and can be applied to most built-in datatypes. Regular expression syntax, however, is considered complex by some. Therefore, XForms defines the concept of a mask facet. All mask facets are convertible into regular expressions.

The mask facet is available only using simple syntax. XML schema allows multiple pattern facets to be specified. Similarly, multiple mask or pattern facets, but not a mixture, are permitted in simple syntax.

XForms mask uses the syntax and processing from [WML1.3] format. Some examples:

As with WML format processing, an XForms Processor must ignore invalid masks.

4.12.5 XForms Facet: max

Availability: only Simple.

Description: for numeric datatypes, serves as a shortcut to the maxExclusive facet.

Legal Values: see maxExclusive.

Default Value: see maxExclusive.

Applies to:

4.12.6 XForms Facet: maxExclusive

Availability: only Schema.

Description: restricts the value space to values below the specified exclusive upper bound.

Legal Values: any expression that evaluates to a value compatible with the parent datatype.

Default Value: unrestricted.

Applies to:

4.12.7 XForms Facet: maxInclusive

Availability: only Schema.

Description: restricts the value space to values below the specified inclusive upper bound.

Legal Values: any expression that evaluates to a value compatible with the parent datatype.

Default Value: unrestricted.

Applies to:

4.12.8 XForms Facet: maxLength

Availability: only Schema.

Description: restricts the value space of the datatype to a maximum length. For string-based, binary-based, and list-based datatypes, length is measured as in [XSchema-2].

Legal Values: any expression that evaluates to a non-negative xform:number.

Default Value: unrestricted.

Applies to:

4.12.9 XForms Facet: mediaType

Availability: Simple, Schema.

Description: restricts the value space of the datatype to specific mime-types.

Legal Values: a list of zero or more mime-types.

Default Value: unrestricted.

Applies to:

4.12.10 XForms Facet: min

Availability: only Simple.

Description: for numeric datatypes, serves as a shortcut to the minExclusive facet.

Legal Values: see minExclusive.

Default Value: see minExclusive.

Applies to:

4.12.11 XForms Facet: minExclusive

Availability: only Schema.

Description: restricts the value space to values above the specified exclusive lower bound.

Legal Values: any expression that evaluates to a value compatible with the parent datatype.

Default Value: unrestricted.

Applies to:

4.12.12 XForms Facet: minInclusive

Availability: only Schema.

Description: restricts the value space to values above the specified inclusive lower bound.

Legal Values: any expression that evaluates to a value compatible with the parent datatype.

Default Value: unrestricted.

Applies to:

4.12.13 XForms Facet: minLength

Availability: only Schema.

Description: restricts the value space of the datatype to a minimum length. For string-based and binary-based datatypes, length is measured as in [XSchema-2].

Legal Values: any expression that evaluates to a non-negative xform:number.

Default Value: unrestricted.

Applies to:

4.12.14 XForms Facet: precision (applied to numeric datatypes)

Availability: Simple, Schema.

Description: for numeric datatypes, restricts the value space to values with the specified number of digits total are significant. Numeric datatypes always use precision along with scale, and precision must be greater than or equal to scale.

Legal Values: for numeric datatypes, any expression that evaluates to a non-negative xform:number.

Default Value: unrestricted.

Applies to:

4.12.14.1 XForms Facet: precision (applied to date and time datatypes)

Availability: only Simple.

Description: for date and time datatypes, restricts the value space to values that include significant data in the specified precision.

Legal Values: for date and time datatypes, any expression that evaluates to "years", "months", "days", "hours", "minutes", or "seconds". Note that large precisions, such as "years" may be meaningless for time datatypes, and small precisions, such as "seconds" may be meaningless for date datatypes.

Default Value: unrestricted.

Applies to:

4.12.15 XForms Facet: scale

Availability: Simple, Schema.

Description: for numeric datatypes, restricts the value space to values with the specified number of digits after the decimal. E.g. scale="0" restricts the value space to integers. Numeric datatypes always use precision along with scale, and precision must be greater than or equal to scale.

Legal Values: any expression that evaluates to a non-negative xform:number.

Default Value: unrestricted.

Applies to:

4.12.16 XForms Facet: uriScheme

Availability: Simple, Schema.

Description: restricts the value space of a datatype to the set of values that conform to one or more URI schemes, such as http, ftp, mailto, news, or ldap.

Legal Values: a list of zero or more strings that represent URI schemes.

Default Value: unrestricted.

Applies to: