From MemberWiki

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.

Chapter 8: Datatypes

Introduction

This chapter describes the various attributes and elements used to specify the datatype for a particular value, along with any additional constraints associated with that value. The starting point for data typing is the datatype attribute, which specifies the raw datatype for an object (e.g., "String", "Object", or a class name reference such as "MyNamespace.MyClass").

Other attributes and child elements provide supplemental datatype information to the datatype attribute:

• The format attribute can be used to specify a higher-level datatype for the value, such as "color" (for a CSS color value), "length" (for a CSS length value), "email" or "address" that developer tools can use to determine which specialized user interfaces to use for property editing (for example, visual color pickers for color values)
• Various Constraint attributes, such as isInteger, minimum and maximum, that specify constraints on the value.
• The <option> and <options> elements can be used to identify a specific set of valid values.
• The <enum> element can be used to specify a reusable enumeration that can be referenced by the datatype attribute.

Subsequent sections describe the datatype attribute and the other related attributes and elements.

Attribute summary

The following table summarizes the data typing attributes defined in this chapter:

Attribute collection: datatype_supplemental_attributes

Various elements in OpenAjax Metadata refer to the datatype_supplemental_attributes attribute collection, which consists of the format attribute and the Constraint attributes:

datatype_supplemental_attributes = (
  format?  &  isInteger_attribute?  &  
  maximum_attribute?  &  max_items_attribute?  &  max_length_attribute?  &  
  minimum_attribute?  &  min_items_attribute?  &  min_length_attribute?  &
  pattern_attribute?  
)

'datatype' attribute

The datatype attribute specifies basic datatype information about a particular value. Various elements within OpenAjax Metadata have a datatype attribute, including <property>, <parameter>, <exception> and <returnType>.

The datatype attribute can be any of the following. Developer tools MUST attempt to match the value of datatype against the constructs listed below in the order listed below:

• A core datatype from the JavaScript language as defined by the ECMA-262 specification. See below for a list of supported core datatypes.
• One of the following DOM objects:
  • HTMLElement - an HTML element node within an HTML document.
  • Window - a DOM Window object within an HTML document.
  • Document - a DOM Document object within an HTML document.
  • Node - a DOM Node object within an HTML document.
• A JavaScript class name that is a class reference to an object name within the JavaScript runtime environment, using JavaScript dot notation.
• A reference to a <config> element. In this case, the datatype attribute MUST be an exact string match with the name attribute of a <config> element within the same metadata file and that is within scope of the referencing element. (See the discussion of the <config> element in the Properties chapter.)
• A reference to a <enum> element. In this case, the datatype attribute MUST be an exact string match with the name attribute of a <enum> element. For widgets, the <enum> element MUST be defined in the same metadata file. For JavaScript APIs, the <enum> MAY be defined in the same or other metadata file within the same collection of JavaScript files (e.g., within an Ajax library).

The following (mostly taken from the ECMA-262 specification) are the allowable JavaScript core datatypes:

• null
• Boolean or boolean
• Number or number
• String or string
• Object or object
• Function or function
• Array or array
• Date or date
• RegExp or regexp
• Error or error
• void - Only valid as a method return type.
• * (asterisk character) - indicates any datatype is allowed

The syntax for datatype also allows for a small number of syntactical constructs that can be used in conjunction with any of the above datatypes. All are variations of the following:

• Bracket syntax (e.g., [...] as a alternate way to indicate an Array type)
• Vertical bar (pipe) as a separator when the data can be one of multiple different types (e.g., Number|Boolean)

For arrays in which each element must be of a particular type, the type of the value may be specified inside the brackets.

datatype="Array[Number]
datatype="[Number]"

(The above examples are equivalent.)

The bracket notation may include a pipe symbol inside, as in:

datatype="[Number|Object]"

which indicates an Array whose elements can be either a Number or Object.

It is also possible to use brackets inside of a pipe construct, such as:

datatype="Number|[Object]"

A developer tool MUST check the value for datatype to see if it matches one of the constructions defined in this specification. If the value does not match any of the constructions defined in this specification, it is permissible for developer tools to use heuristics to attempt to determine the intended datatype. If the value does not match any of the constructions defined in this specification and if heuristic approaches do not recognize the value, the developer tool SHOULD assume a datatype of "*".

The default value for the datatype attribute is String.

Each possible datatype has a default value, as described in the following table.

If a <property>, <parameter> or <returnType> element has a datatype attribute whose value is "Object", "[Object]", or a list of datatypes that includes "Object" (e.g., "String|Object"), then that element MAY contain <property> or <properties> sub-elements. In this case, the <property> elements provide details about the properties on the Object.

If a <property>, <parameter> or <returnType> element has a datatype attribute whose value is "Function" or a list of datatypes that includes "Function" (e.g., "String|Function"), then that element MAY contain <parameter>, <parameters>, <returnType>, or <returnTypes> sub-elements. In this case, the <parameter> and <returnType> elements provide details about the parameters and return types for the Function.

'format' attribute

The format attribute provides supplemental datatype information that allows for specialized user interfaces (for example, visual color pickers for color values) within developer tools. For example, URLs, IDs, e-mail addresses, and hex color values are all strings, but each is likely to be represented by a different user interface element, and each of those elements will require a different type of field validation. The format attribute gives developer tools a hint about what is needed.

The following table shows the list of defined values for format.

Developer tool implementers and widget developers SHOULD exercise care with format="html" to prevent malicious source code injection. Developers SHOULD avoid simple innerHTML assignment of HTML fragments (which might contain executable JavaScript logic, such as within onmouseover attributes or within <a href="javascript:..."> elements). Instead, an alternate approach would be to run the HTML fragment through a filtering process that only allows a safe set of elements and attributes to be included in the fragment.

The format attribute supports custom datatypes via URI syntax. For example, format="http://www.example.com/types/geospatial". In either case, the custom datatype SHOULD be designed to avoid collisions with datatypes defined by other parties, and SHOULD provide suitable documentation for the given datatype.

Constraint attributes

The following sibling attributes to the datatype attribute define constraints on a value.

Note that if the 'format' attribute exists on an element along with one or more constraint attributes, then the 'format' attribute takes precedence and developer tools MAY ignore the constraint attributes.

'isInteger' attribute

A Boolean value indicating whether the value MUST be restricted to an integer value. Applies only to numeric datatypes.

'minimum' attribute

A numeric or date value indicating the minimum acceptable value (inclusive). If this value is not specified, then numeric values have no minimum. This attribute SHOULD be supported by developer tools and MUST apply only to numeric and date values. See the description of the 'defaultValue' on the <property> element defined in the Properties chapter for the allowed format of date values.

'maximum' attribute

A numeric or date value indicating the maximum acceptable value (inclusive). If this value is not specified, then numeric values have no maximum. This attribute SHOULD be supported by developer tools and MUST apply only to numeric and date values. See the description of the 'defaultValue' on the <property> element defined in the Properties chapter for the allowed format of date values.

'min_length' attribute

An integer value indicating the minimum number of characters in a string value. If this value is not specified, then the string can consist of as few as zero characters. This attribute SHOULD be supported by developer tools and MUST apply only to string values.

'max_length' attribute

An integer value indicating the the maximum number of characters in a string value. If this value is not specified, then the string has no maximum length. This attribute SHOULD be supported by developer tools and MUST apply only to string values.

'min_items' attribute

An integer value indicating the minimum number of elements in an array value. If this value is not specified, then the array can consist of as few as zero elements. This attribute SHOULD be supported by developer tools and MUST apply only to array values.

'max_items' attribute

An integer value indicating the maximum number of elements in an array value. If this value is not specified, then there is no maximum on the number of elements in the array. This attribute SHOULD be supported by developer tools and MUST apply only to array values.

'pattern' attribute

A string value that is permissible as the first parameter to an ECMAScript RegExp() constructor function, indicating a pattern against which a string value should match. The value of this attribute SHOULD NOT be a regular expression literal (i.e., it SHOULD NOT include begin and end slash characters). For example, for a pattern that matches a sequence of digits, use pattern="[0-9]*" instead of pattern="/[0-9]*/". This attribute SHOULD be supported by developer tools and MUST apply only to string values.

<option>

The <option> element specifies a single option within an enumeration.

Here is an example:

<option value="CA">
  <label>California</label>
</option>

The 'value' attribute holds the (non-localizable) internal value for the given option. The <label> sub-element holds the (potentially localizable) display string for the item. If there is no <label> sub-element, then the value attribute MUST be used as the label.

Schema

option_element = element option {
  option_content  &  option_attributes  &  foreign_nodes
}
option_content = (
  descriptive_elements  &
  label_element?
)
option_attributes = (
  value  
)

Child content

This element might contain any of the following sub-elements:

• descriptive_elements such as <description> and <example>
• Zero or one <label> sub-element

Attribute summary

<options>

The <options> element holds zero or more <option> child elements. For additional information about plural elements such as <options>, refer to the Plurals and Singular Elements chapter.

Schema

options_element = element options {
  options_content  &  options_attributes  &  foreign_nodes
}
options_content = (
  descriptive_elements  &  
  option_element*
)
options_attributes = (
  name?  &
  multiple?  &  unconstrained?  
)

Child content

This element might contain any of the following sub-elements:

• descriptive_elements such as <description> and <example>
• Zero or more <option> sub-elements

Attribute summary

Attribute details

'name' attribute

The optional name attribute defines a grouping name for a set of <option> sub-elements. The name MUST be globally unique within the context of current container object.

'multiple' attribute

The multiple attribute is a Boolean value indicating whether the user can select multiple items from the list. If multiple is true, then datatype MUST be one of Array, String or Number as follows:

• When datatype is an Array (i.e., datatype="Array", datatype="[]" or datatype="[itemtype]", where itemtype is one of the primitive datatypes defined in this chapter such as String, Number or Object), and the parent element is a <property> or <parameter> element, then the value MUST be in the form of a JavaScript array that holds the corresponding value from all of the value attributes corresponding to the <option> elements that the user has selected. If itemtype is provided, then each item MUST be of the datatype specified by itemtype; otherwise, each item MUST be a String. For example, if there are two options:
    <options multiple="true" datatype="Array">
    <option value="1"><label>Choice 1</label></option>
    <option value="2"><label>Choice 2</label></option>
  <options>
and the user selects both options, then the resulting value is the following JavaScript array:
    ["1","2"]

• When datatype is String, then the value is a String which holds the space-separated concatenation of the string representation from all of the value attributes corresponding to the <option> elements that the user has selected. For example, if there are two options:
    <options multiple="true" datatype="String">
    <option value="1"><label>Choice 1</label></option>
    <option value="2"><label>Choice 2</label></option>
  <options>
and the user selects both options, then the resulting value is the following JavaScript string (but without the quotes):
    "1 2"
• When datatype is Number, then the value is an integer which holds the numeric OR operation from all of the value attributes corresponding to the <option> elements that the user has selected. In this case, the values MUST be non-negative integers, and usually will be a power of 2 (e.g., 1, 2, 4, 8, etc) to align the the OR operation. For example, if there are two options:
    <options multiple="true" datatype="Number">
    <option value="1"><label>Choice 1</label></option>
    <option value="2"><label>Choice 2</label></option>
  <options>
and the user selects both options, then the resulting value is the JavaScript number "3" (the result of OR'ing together the values 1 and 2).

'unconstrained' attribute

The unconstrained attribute is a Boolean value indicating whether the user MAY enter a value that is different from the list of options. The default value is false, indicating that the user MUST choose from the enumeration list.

Additional information

The <options> element and <option> elements do not have a datatype attribute; instead, the collection of options will inherit the datatype from the <options> element's parent (or <option> element's grandparent if the <option> element is a child of an <options> element). The parent element's (or grandparent element's) datatype attribute allows the developer tool to determine whether the selected value has the correct type. (Note: it is the responsibility of the metadata author to ensure that datatype and the possible values identified by <option> elements are consistent.)

<label>

The <label> element is a child element of <option> and provides a display string for the given option.

Schema

label_element = element label {
  label_content  &  label_attributes  &  foreign_attributes
}
label_content = (
  plain_text_or_html
)
label_attributes = (
  lang?  &  locid?  &  type? 
)

Child content

The <label> element can contain either Plain text or HTML markup.

Attribute summary

<enum>

The <enum> element defines a reusable enumeration definition that can be referenced from a 'datatype' attribute. A reference to an <enum> element indicates that the given object is restricted to the set of values defined by this <enum> element.

For widgets, the <enum> element MUST be defined in the same metadata file. For JavaScript APIs, the <enum> MAY be defined in the same or other metadata file within the same collection of JavaScript files (e.g., within an Ajax library).

Schema

enum_element = element enum {
  enum_content  &  enum_attributes  &  foreign_nodes
}
enum_content = (
  descriptive_elements  &
  option_element*  &  options_element*
)
enum_attributes = ( 
  name  &  datatype? 
)

Child content

This element might contain any of the following sub-elements:

• descriptive_elements such as <description> and <example>
• Zero or more <option> as direct children of the <enum> element
• A single <options> child element, which in turn contains zero or more <option> child elements

Attribute summary

Attribute details

'name' attribute

The optional name attribute defines a name for this enumeration that can be referenced by a 'datatype' attribute. The name MUST be globally unique within the context of a particular JavaScript library.

'datatype' attribute

The datatype attribute specifies the datatype of the result when the user selects or enters a value. The 'datatype' datatype attribute allows a developer tool to determine whether the value has the correct type. (Note: it is the responsibility of the metadata author to ensure that datatype and the possible values identified by <option> elements are consistent.)

Refer to the description of the 'multiple' attribute on the <option> for rules concerning multiple selection.