From MemberWiki

Notes:

• This wiki page holds a portion of the latest internal editorial draft for what ultimately will become the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification.

Here is the proposed way for the IDE WG to edit this specification:

• All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say Tentatively approved or Approved) represents preliminary proposed text that requires further review and discussion.
• Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
• When an item has been deemed complete by the WG chair due to committee consensus, then the annotation Approved will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
• When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation Tentatively approved will be placed at the end of given block of text (e.g., paragraph or bullet).

6 Datatypes

Need to do an editorial pass. Some of the text here doesn't completely reflect all of the recent developments in other parts of this document.

Introduction

This chapter describes the various elements and attributes used to specify the datatype for a particular value and any additional constraints associated with that value. The starting point for datatyping is the datatype attribute, which is described in the next section.

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

• Some attributes and elements such as format (list the others here also) augment the datatyping information provided by the datatype attribute
• Other attributes list them here define constraints on the value, such as minimum and maximum value for a Number

Subsequent sections describe these other attributes and elements.

The datatype attribute

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

This datatype attribute can be any of the following. User agents must attempt to match the value of datatype against the constructs listed below in order:

• Various core datatypes from the JavaScript language as defined by the ECMA-262 specification. See below for a list of supported JavaScript core datatypes.
• Various browser object types
  • HTMLElement. The value HTMLElement indicates a primitive datatype indicating a HTML element node with an HTML document.
  • Window. The value Window indicates a DOM Window object within an HTML document.
  • Document. The value Document indicates a DOM Document object within an HTML document.
  • Node. The value Node indicates a DOM Node object within an HTML document.
• A JavaScript class name. In this case, the value is a "class reference" to an (absolute) object name within the JavaScript runtime environment, often using JavaScript dot notation for the class, or an enumeration definition (i.e., an <enum> element). For example, let's assume a hypothetical JavaScript class name "FooToolkit.io.httpreq", where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript class (i.e., has an appropriate constructor function). Usually, when the datatype attribute is used as a class reference there is a separately-defined <class> or <enum> element whose name attribute specifies the name of the class.
• 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 document and that is within scope of the referencing element. (See the discussion of the <config> element in the API Metadata chapter.)

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:

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

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

• null 2008-01-24 Tentatively approved. 2008-04-24 Draft Consensus to rename from "Null" to "null".
• Boolean or boolean
• Number or number
• String or string
• Object or object
• Function or function
• Array or array
• Date or date 2008-01-31 Need to warn developers about browser incompatibilities with Date.toString(), so use UTC or something else.
• RegExp or regexp
• Error or error
• void - Only valid as a method return type. 2008-01-24 Tentatively approved. 2008-08-05 We decided whether to use "Undefined" instead of "void" since the former is a ECMA type and the latter isn't, but some browsers actually treat no return as different than return Undefined, and Undefined is only a spec-internal thing and objects shouldn't have that type, so we decided to keep "void".
• * (asterisk character) - 2008-01-24 Tentatively approved, but still need to decide whether it is "any" or "Any" or either. 2008-04-24 Draft Consensus to express as "*" instead of "Any" or "any".

(Note: the Global and Math objects defined in ECMA-262 are excluded because it functions only as a static class and therefore does not have a constructor.)

A given value may support multiple datatypes, such as both null and Object or both String and Object. To support these scenarios, the supported datatypes are separated by a pipe symbol, as in:

datatype="Number|Object"

which indicates a scalar that can be either a Number or Object.

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

datatype="[Number]"

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]"

It is possible to specify the datatype of the elements of an Array by using bracket syntax to indicate the datatype instead of using the string "Array". Therefore, the following two examples are equivalent: Need to clean this up per resolution on 2008-07-08 about Array being equivalent to [*].

A user agent 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 user agents 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 user agent should assume a datatype of Object.

The default value for the datatype attribute is String. 2008-07-22 Draft Consensus: 'datatype' is not required and it defaults to String. (We chose String instead of * because a tool needs to know whether a value of "12" entered into a property editor should be the number 12 or the string "12".

Elements defined in this chapter

2008-07-21 Jon: Right now the schema says <options> can have zero or more <option> elements. Should that be one or more instead? 2008-07-22 Draft Consensus: Leave the schema as zero-or-more. Keeps things simpler and more consistent.

<enum>

2008-04-29 Draft consensus: We approved Bertrand's proposal for an <enum> element and decided it can be a child of <api> , <widget>, and <property>. 2008-07-22 Draft consensus: We concluded that we shouldn't have <enum> as a child of <widget>, and <property>; only <api>.

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

The <enum> element describes not yet written, but for reusable enumeration definitions.

The name attribute not yet written

The datatype attribute not yet written, but we decided that it can be either an ECMAScript core datatype such as String or a classname. 2008-04-29: We decided that for enums, the 'datatype' expresses the expected result of the 'value' attribute, such as String, Number or Boolean, and that if 'value' isn't specified, then use the 'label' and treat as a String. But I'm not sure what exactly we expect a tool to do with the 'datatype' attribute. For example, must a tool do a string-to-number conversion if datatype=Number, or is this just a hint that the tool can use or ignore? 2008-07-08 Tentative Resolution: We concluded that 'datatype' allows the IDE to tell the user if his entry doesn't match what is needed, and that it is the responsibility of the metadata author to keep 'datatype' and the options consistent. If not consistent, then that's a metadata error, which we treat as implementation dependent. Need to update spec per these resolutions

<enums>

enums_element = element enums {
  enums_content  &  enums_attributes  &  foreign_nodes
}
enums_content = (
  descriptive_elements  &  
  enum_element*
)
enums_attributes = (
  name?
)

The <enums> element holds zero or more <enum> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <enums> element in case multiple <enums> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

<option>

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

The <option> element describes not yet written, but has to do with enumerations

The <label> sub-element holds the display string for the item.

The value attribute the value string for the item.

2008-09-12 what happens if no label? Default to the 'value'?

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion. 2008-07-29 DRAFT CONSENSUS: Turn label from an attribute to an element to allow for locid (i.e., localization).

<options>

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

The <options> element holds zero or more <option> child elements.

The multiple attribute is a boolean that, if true, indicates that the user can select any number of items from the list. If false, the user can only select one item. 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 (e.g.,
    <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:
    <code>["1","2"]

• When datatype is String, then the value is a String which holds the space-separated concatentation 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 (e.g.,
    <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 (e.g.,
    <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).

The unconstrained attribute not yet written, is a boolean that if false indicates whether the user must choose from the enumeration list but if true indicates the user can simply enter a new value

The optional name attribute is meant to allow for providing a unique name for this particular <options> element in case multiple <options> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

<label>

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

The <label> element provides a display string. 2008-07-29 DRAFT CONSENSUS: Turn label from an attribute to an element to allow for locid (i.e., localization).

The type attribute specifies a MIME type that specifies the type of the content. For further details, see the section titled "Content that can be plain text or HTML" the Descriptive elements and attributes chapter.

Attributes described elsewhere:

• The locid attribute is defined in the Localization chapter.

The format attribute

The format attribute provides supplemental datatype information that allows for deeper interoperability between software products and for tailored user interfaces within editing tools. Sometimes tools can use the format attribute to provide advanced user interface when the user edits a given property. For example, if a property allows the user to enter the name of a CSS selector, a tool might search the document for a list of CSS selectors that are used in the document. 2008-01-31 TENTATIVE APPROVAL: attribute should be named 'format' instead of 'valueType'.

The following table shows the list of defined values for format. 2008-07-15 TENTATIVE APPROVAL: add 'id' to the list of formats.

Editor: need to add more rigorous references for the above. For example, the HTML4 spec that defines an ID is at: http://www.w3.org/TR/REC-html40/types.html#type-name), but maybe better to use the XML definition for ID.

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 attributes are sibling attributes to the datatype attribute and define constraints on a value.

The isInteger attribute. A boolean, only applies to numeric datatypes. Default is false. If true, says that the value must be restricted to an integer value. 2008-02-?? Tentatively approved.

The minimum attribute. For numeric datatypes and dates. An integer. Indicates the minimum acceptable value (inclusive). If this value is not specified, then numeric values have no minimum. This attribute SHOULD be supported by conforming tools and MUST only apply to numeric and date values. 2008-02-15 Tentatively approved. 2008-02-15: Tentative decision - If ECMA262 has a reliable definition of string comparison, then this will also apply to strings. Need to research.

The maximum attribute. For numeric datatypes and dates. An integer. Indicates the maximum acceptable value (inclusive). If this value is not specified, then numeric values have no maximum. This attribute SHOULD be supported by conforming tools and MUST only apply to numeric and date values. 2008-02-15 Tentatively approved. 2008-02-15: Tentative decision - If ECMA262 has a reliable definition of string comparison, then this will also apply to strings. Need to research

The min_length attribute. For datatype 'String'. An integer. Indicates the minimum number of characters in the string. If this value is not specified, then the string can consists of as few as zero characters. This attribute SHOULD be supported by conforming tools and MUST only apply to string values. 2008-02-15 Tentatively approved.

The max_length attribute. For datatype 'String'. An integer. Indicates the maximum number of characters in the string. If this value is not specified, then there is no limit on the maximum length of the string. This attribute SHOULD be supported by conforming tools and MUST only apply to string values. 2008-02-15 Tentatively approved.

The min_items attribute. For datatype 'Array'. An integer. Indicates the mininum number of elements in the array. If this value is not specified, then the array can have an arbitrarily large number of elements. This attribute SHOULD be supported by conforming tools and MUST only apply to array values. 2008-02-15 Tentatively approved.

The max_items attribute. For datatype 'Array'. An integer. Indicates the maximum number of elements in the array. If this value is not specified, then there is no limit on the maximum number of elements in the array. This attribute SHOULD be supported by conforming tools and MUST only apply array values. 2008-02-15 Tentatively approved.

The pattern attribute. For datatype 'String', indicates a JavaScript regular expression against which the string should match. This attribute SHOULD be supported by conforming tools and tools MUST only apply it to string values. 2008-02-15 Tentatively approved.