YODEL Data Types

Yodel supports several data types. With the addition of "binary" these types mirror those types available in JavaScript (it being assumed that YODEL will most often be used to pass structured data between a server and JavaScript client in AJAX-style applications).

A word about Recordsets

YODEL provides no standard datatype for recordsets (as might be returned by a SQL-based database query). This is primarily because such an element is easily represented by existing data types and also because no such concept exists in many languages (including JavaScript). Recordsets may be described in YODEL as:

An object of arrays. In this scenario a recordset is treated as a collection of named columns. Each property of the objects is a column of the recordset and represented by an array of values.
An array of objects. In this version the recordset is treated as a collection of objects: each object represents a row of data while all the objects are collected into an array.

YODEL makes no recommendation on which of these options is preferred but suggests that any decision be clearly documented. In the interest of flexibility, it's suggested that, if possible, serializers implement support for both options (perhaps through a user-selectable parameter).

YODEL supports the following data types:

object

Objects are string-indexed collections of name/value pairs. Depending on the languages they are also called structures, dictionaries or maps. Object property (key) names are defined using the <d> tag's fields attribute. Each entry in the fields value correlates positionally to a child <d> tag (if no fields are provided or if there are more children than fields names the current integer position of the child is used at the property name).

The values contained in an object can be of any type (including other objects or arrays) and can be nested arbitrarily deeply.

Consider a simple object:

     <d type="object" fields="firstname, lastname">
          <d type="string">John</d>
          <d type="string">Doe</d> 
     </d>

In this case we have two propeties "firstname" and "lastname". The value of "firstname" (the first child <d> tag) is the string "John" and the value of "lastname" (the second child <d> tag) is the string "Doe".

array

Arrays are (most often) numerically indexed collections of values. YODEL arrays begin with the value zero. Array values can be of arbitrary types (YODEL array elements do not have to share the same data type).

A simple array of weekdays might be represented as such:

     <d type="array">
          <d>Monday</d>
          <d>Tuesday</d> 
          <d>Wednesday</d>
          <d>Thursday</d> 
          <d>Friday</d>
     </d>

The default behavior can be overidden by populated the <d> tag's fields attribute. If this attribute is populated the values provided will be used as the index labels. This optional facility allows you to generate sparse arrays and array-based hash maps if you need to.

To represent a sparse array of weekend days using their ordinal value as the index you might do:

     <d type="array" fields="1,7">
          <d>Sunday</d> 
          <d>Saturday</d>
     </d>

Arrays specified with non-numeric fields should be deserialized into the most appropriate data structure for the target language. JavaScript, for example, allows non-numeric array indexes. ColdFusion does not however and so a structure (which does allow non-numeric indexes) should be substituted.

null

A programmtic null (an explicit statement of no value). Consuming languages which do not have the concept of null may deserialize null values as empty strings. A null <d> tag does not need an ending tag:

     <d type="null" />

undefined

A programmtic indication of a specified, but uninitialized field. If the consuming language permits the field should be created, but left uninitialized. If this is not possible the field may be deserialized as an empty string. Like null undefined requires no end tag:

     <d type="undefined" />

There are very few reasons why you would ever explicitly require undefined values. Its purpose here is mostly to provide an option for times when a property of an object has been uninitialized before serialization. Using undefined also gives you another option for describing sparse arrays. To define a sparse array of weekdays using the ordinal value of the day as the index could be done like this:

     <d type="array">
          <d type="undefined" />
          <d>Monday</d>
          <d>Tuesday</d> 
          <d>Wednesday</d>
          <d>Thursday</d> 
          <d>Friday</d>
     </d>

It should be noted that in nearly all cases using the fields attribute to define a sparse array will result in a smaller packet than using the the undefined data type.

string

Strings are ambiguous sets of characters. Strings in YODEL can be of any length and can contain any characters legal in XML CDATA fields. The following list of character classes should be accepted by YODEL deserializers:

& (ampersand)
< (less-than sign)
> (greater-than sign)
' or ' (apostrophe / single quote)
" (double quote)

(Note that the ' entity was added to the XML specification but not the HTML specification. Some browsers, such as Internet Explorer, will not escape it. However it still sees common use. For that reason it's recommend that if serializers want to escape the single quote that they use the ' entity but that deserializers support both.)

number

In YODEL numbers are represented as floating point values. The possible range of numbers is implementation-dependent. When deserializing out-of-range numbers implementors are encouraged to either throw an error or return a null value and to fully and clearly document their decision.

boolean

YODEL accepts as TRUE either the string "true", the number 1, the letter "y" or the word "yes". It accepts as FALSE the string "false", the number zero, the letter "n" or the word "no". The boolean value is included as the content of the <d> tag:

     <d type="boolean">true</d>

date

YODEL accepts dates in a subset of the ISO 8601 date and time format as noted by the W3C. For example either: 2004-08-22T12:07:32.234-05:00 (local time with Timezone information) or 2004-08-22T17:07:32.234Z (UTC time). The following rules apply:

Year should always be four digits, months and days always two digits.
Time is in a 24-hour clock.
Hours, minutes and seconds should always be two digits.
Millisecond values (fractional second values) are optional.
Timezone information is optional. Deserializers should follow these rules:
- If no timezone information is provided the time should be consider "local time".
- If a timezone offset is provided it should be used to convert the time to the local time.
- If the UTC indicator ("Z") is provided the time should be left as UTC.

binary

YODEL provides basic support for binary ("blob") objects. Binary objects are represented as BASE64-encoded strings. YODEL provides no native capacity to validate binary objects. Not all languages which support YODEL can support binary objects: implementations on these platforms should leave the encoded representation intact but are not required to do more than that.