IDE Issue 7

From MemberWiki

Contents 1 IDE Issue 7: Datatypes 1.1 Introduction 1.2 Existing industry practice 1.3 Analysis and discussion 1.4 Jon's proposed resolution

IDE Issue 7: Datatypes

Introduction

This issue is about the set of datatypes that we will allow for properties.

This is an issue within the IDE WG, but we are attempting to be good OpenAjax citizens and do the right thing not only for us but also for other parties that might leverage our work. Here are some of the constituencies who are likely to be interested in this topic:

• IDE WG: Our main interest to provide an IDE with information about the datatype for a given property so it can know what sort of user interface to provide for editing that data. For example, an "enum" might correspond to a popup menu, a "date" might correspond to a popup calendar widget, and or special inline integer value editing logic that might constrain values to the range of 0 to 100.
• Gadgets TF: One would expect that the Gadgets TF has a similar interest, where a mashup tool might want to present a property editor dialog where an "enum" might be presented to the user as a popup menu, etc.
• JSON Schema: Some parts of the industry have expressed a strong interest in providing some sort of formal schema definition language for JSON payloads that are passed around by the Hub's pub/sub system. They are likly to be interested if OpenAjax Alliance defines a standard set of datatypes.

Related to the question about how to represent datatypes are the following:

• Custom property editors: See IDE Issue 6
• Suitable for other uses of datatypes: For example, our list of datatypes could be used to document return values (in addition to property values) and used by a future JSON Schema spec
• Validation regular expressions: Some values can be validated against a regular expression
• Validation scripts: Some situations are more complicated and require script logic in order to perform validation
• Change events: HTML has the onchange event, which is often used to trigger validation scripts. Ajax widgets probably need something like that.
• Constraints: At the 2007-12-12 Gadgets and 2007-12-13 IDE phone calls, we were leaning away from attempting to define our own constraint system, but final decisions haven't been made yet.
• Extensibility: We seem to be in agreement that we want to allow an extensibility option so that developers can define their own new datatypes if we can manage that without complicating things for the greater majority who will be happy with a common set of built-in datatypes

Existing industry practice

There is a separate wiki page that shows the datatypes used by various relevant technologies, including:

• JavaScript language
• W3C specs (in particular, HTML and CSS)
• XML Schema Datatypes
• JSON Schema
• Google Gadgets

Here is that wiki page:

• IDE Issue 7 Existing Practice

Analysis and discussion

For both IDEs and mashups, we have recognized that an important "customer" of our set of datatypes will be tools that want to attach datatype-specific editors for property editing dialogs. For example, if a field has a "date" datatype, then perhaps a popup calendar would appear. For an enum, perhaps a popup menu would appear. For text-entry fields, we also saw high value for identification of things such as the range of an integer value (e.g., positive integer or a range from 1-100). Here are some of the field types that are reasonably common that lend themselves to custom properties editors:

• enum (could map to a menu)
• date (could map to a calendar)
• time (could map to a list the hours in the day)
• address (could map to a map or multiple fields for street, city, state/province, country, and postal code)
• phone number
• email
• credit card number

Because of existing industry practice and momentums, here are some of the datatypes found in popular technologies that we would like to cover because of current high levels of industry usage:

• All of the JavaScript types: (except perhaps undefined and null) today's Ajax controls take parameters that use all of the built-in JavaScript datatypes
• All of the Google Gadgets types: Google has created a highly popular platform that has sufficient momentum as to be considered a defacto standard

During discussion within a recent IDE phone call, we discussed an approach where it might be OK to define a large number of datatypes, some "advanced" and some "core", so long as each "advanced" datatype had a fallback within the core set. Tools MUST implement the core datatypes and either SHOULD or MAY implement the advanced datatypes. For example, "string" would be in the core and would be the ultimate fallback. We might choose to have an "integer" datatype with the core set and offer "positive integer" within the advanced set, with "integer" as its fallback.

Jon's proposed resolution

Here is a summary of what I propose:

1. Consolidate 'jsType' and 'xsdType' into a single attribute, type which can take one of the values listed in the "Datatype" column below or a QName for a custom datatype
2. Supplemental, related attributes are below. Note that there is a limited ability to constrain certain popular datatypes, such as min/max for numerics and maximum string length:
   • description - long string describing this property, sometimes placed inside of a bubble note popup to provide more information about this property. If not provided, then tools SHOULD use the property name within any UI that might have used this attribute. (Localizable, Optional)
   • title - short string describing this property, typically used as the label within property editor dialogs. If not provided, then tools SHOULD use the property name within any UI that might have used this attribute. (Localizable, Optional)
   • default - one of the core built-in types. This attribute MUST be supported by conforming tools.
   • required - boolean. If true, this property MUST have a value in order for the data set to be valid. This attribute MUST be supported by conforming tools. This attribute MUST be supported by conforming tools. (JSON Schema has an "optional" property instead. OK with me to use "optional" instead.)
   • readonly - boolean. If true, this property SHOULD be visible but read-only to the user. This attribute MUST be supported by conforming tools. This attribute MUST be supported by conforming tools.
   • hidden - boolean. If true, this property SHOULD be hidden from the user and therefore tools MUST not show display this property to the user in property editor dialogs. This attribute MUST be supported by conforming tools.
   • min - for numeric types, 'string' and 'array'. An integer. For numeric types, indicates the minimum acceptable value (inclusive). For strings, the mininum number of characters. For arrays, the minimum number of array entries. If this value is not specified, then numeric values have no minimum, a 'string' can consists of as few as zero characters, and an array can contain as few as zero entries. This attribute SHOULD be supported by conforming tools and MUST only apply to numeric values.
   • max - for numeric types, 'string' and 'array'. An integer. For numeric types, indicates the maximum acceptable value (inclusive). For strings, the maxinum number of characters. For arrays, the maximum number of array entries. If this value is not specified, then numeric values have no maximum, a 'string' can any number of characters, and an array can contain any number of entries. This attribute SHOULD be supported by conforming tools and MUST only apply to numeric values.
   • pattern - for type 'string' or 'normalizedString', 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.
   • onchange - validation JavaScript to execute when the value changes. This attribute SHOULD be supported by conforming tools and tools MUST only apply it to string values. (??? Need to think this through)
   • fallbackType - for use when type is a QName.
   • (Note: JSON schema from JSON.com also has 'unique', 'nullable', 'unconstrained', and 'transient'. OK with me to add any or all of these, but they seemed low-usage features.)
3. The set of built-in datatypes fall into two categories, a core set and an advanced set of built-in datatypes
4. Core built-in datatypes MUST be supported by conforming tools
5. Advanced built-in datatypes either SHOULD be supported or MAY be supported, but in either case the tool MUST support the fallback datatype
6. For simplicity and to minimize discussion, we base our core set to align with the datatypes found in JavaScript
7. We add various additional datatypes (e.g., enum, date, address) to cover common industry datatypes, particularly ones which lend themselves to custom property editors (e.g., a 'date' field might be edited via a popup calendar)
8. We leverage QNames for extensibility. OpenAjax-defined datatypes are expressed as simple strings, such as "number" and "date". Other organizations may define their own datatypes, but when reference within the 'type' attribute, these custom datatypes MUST be expressed as QNames (e.g., type="acme:temperature") and attribute fallbackType MUST be provided and identify one of the core datatypes.
9. At this time, we do not define a mechanism for defining the formal schema for custom datatypes, but we do require that custom datatypes MUST be documented fully and unambiguously, perhaps with plain text write-ups, but in the future we might advocate the use JSON Schema if such a standard ever appears. (Note: to leverage JSON Schema in the future, we might add a new tag to our metadata format that associates a QName-defined custom datatype with a JSON schema definition.)

In the table below, the MSM column (MUST/SHOULD/MAY) indicates whether conforming tools MUST support the given datatype, or SHOULD support intelligent editing of the given datatype (but MUST support the fallback), or MAY support intelligent editing for the given datatype (but MUST support the fallback). Datatypes labelled MUST or SHOULD are expected to have the highest levels of usage across the industry.

Datatype	MSM	Fallback	Comment
The core set of built-in datatypes. (Matches the datatypes found in JavaScript and then adds "any" and "void".)Conforming tools MUST support the core set of datatypes
string	MUST	N/A	(empty string is possible, but not null)
number	MUST	N/A	-
boolean	MUST	N/A	-
null	MUST	N/A	-
undefined	MUST	N/A	-
arrays	MUST	N/A	Within the core set, this is an array of strings
objects	MUST	N/A	This represents a container that recursively holds other variables, each of which has a name, a datatype, default value, and whatever else we decide
any	MUST	N/A	This datatype allows a value that might consist of any of the above datatypes.
void	MUST	N/A	Only applicable to the return values from functions.
Advanced datatypes, part I. These numeric datatypes take their formal definition comes from XML Schema Datatypes spec. Conforming tools MUST support at least the fallback datatypes for each of the advanced built-in datatypes and MAY support any of the advanced built-in datatypes.
integer	SHOULD	number	-
float	SHOULD	number	-
double	SHOULD	number	-
decimal	SHOULD	number	-
nonPositiveInteger	SHOULD	number	-
long	SHOULD	number	-
nonNegativeInteger	SHOULD	number	-
negativeInteger	SHOULD	number	-
int	SHOULD	number	-
unsignedLong	SHOULD	number	-
positiveInteger	SHOULD	number	-
short	SHOULD	number	-
unsignedInt	SHOULD	number	-
byte	SHOULD	number	-
unsignedShort	SHOULD	number	-
unsignedByte	SHOULD	number	-
Advanced datatypes, part II. These datatypes are defined to match the standard datatypes found in Google Gadgets. Conforming tools MUST support at least the fallback datatypes for each of the advanced built-in datatypes and either SHOULD or MAY support any of the advanced built-in datatypes.
enum	SHOULD	string	Delivered to a tool as a one-level deep JSON associative array, where property names are the internal index and property value is the string that is displayed to the user. Assumption is that tool will substitute localized versions of the displayed strings
location	SHOULD	string	Delivered to a tool as a one-level deep JSON associative array, such as {lat:#, long:#}. Need to research this some more to figure out details about this datatype.
Advanced datatypes, part III. These datatypes have high levels of utility and are either reasonable to implement or acceptable to use the fallback datatype. Conforming tools MUST support at least the fallback datatypes for each of the advanced built-in datatypes and either SHOULD or MAY support any of the advanced built-in datatypes.
uri	SHOULD	string	Need to point to a spec for format and rules. What about relative URIs?
ID	SHOULD	string	Need to point to a spec for format and rules
QName	SHOULD	string	Need to point to a spec for format and rules (probably XML Namespaces)
color	SHOULD	string	The <color> construct in CSS 2.1
length	SHOULD	string	The <length> construct in CSS 2.1
date	SHOULD	string	Need to point to a spec for format
time	SHOULD	string	The <time> construct in CSS 2.1
duration	SHOULD	string	SMIL 2.1 clock values (http://www.w3.org/TR/2005/REC-SMIL2-20051213/smil-timing.html#Timing-ClockValueSyntax)
email	SHOULD	string	Need to point to a spec for format
phone	MAY	string	Need to point to a spec for format
address	MAY	string	Need to point to a spec for format. Note: tools will often choose to present this property as multiple type-in fields (e.g., street, city, country, postal code, etc).
cardnumber	MAY	string	For credit card numbers. Need to point to a spec for format
language	MAY	string	Need to point to a spec for format
richtext	MAY	string	HTML body content with optional formatting, such as DIV's, P's and SPAN's, similar to the body content of richly formatted email messages.
base64Binary	MAY	string	Need to point to a spec for format

The proposed default values for 'type' and 'fallbackType' are any.

Features that are notably absent from this proposal:

• Exclusive ranges (e.g., the value can be between 0 and 1 but cannot be exactly 0 or 1)
• Stock symbol datatypes, such as those found in Google Gadgets. The cost/benefit ratio of such as standard datatype did not seem justifiable. First off, we try to avoid defining any complex types here (i.e., types that need to be conveyed as a structure or array), and simple stock symbol values can be represented as a string with length=4.
• Attributes 'unique', 'nullable', 'unconstrained', and 'transient' from JSON Schema
• Datetypes 'schema', 'person', 'page', and 'html' from JSON Schema. (Although there is a 'richtext' datatype above that uses HTML syntax.)
• Google (recently?) has added a "group" attribute for their Gadget-to-Gadget pub/sub feature in Google Gadgets. Not sure where they are going with this one...