rest/datatypes

2006-02-14T14:24:31Z

JimAncona: /* Analysis */

<h1> Datatypes in HTML </h1>
One of the challenges of using HTML as a data transport is that everything, by default, is a string. This page explores ways to use microformats -- specifically, class names -- to encode data type information, e.g., for use with [[xoxo]] and [[rest/ahah]], in order to allow lossless import/export from various languages. These could also be used with forms to provide [[rest/description]]s of the type of data expected.

__TOC__

== Contributors ==
* Dr. Ernie Prabhakar
* Chris RG
* Mark Rickerby
* Robert Bachmann
* Kevin Marks
* Tantek Çelik

== Examples ==

These are the primary datatypes in a range of different languages and formats. Note that we are only concerned with "primitive" datatypes (loosely defined), as structured datatypes (list/array, hash/dictionary) are handled by [[xoxo]].

{| border="1" cellpadding="2"
|+Datatype comparison table
|-
! Language/format !! string !! float !! integer !! boolean !! data || date/time || null
|-
! [http://www.w3.org/TR/xmlschema-2/#built-in-datatypes XML Schema]
| string || float, double || decimal, integer, etc. || boolean || hexBinary, base64Binary || duration, dateTime, date, time || nil
|-
! [http://ws.apache.org/xmlrpc/types.html XML-RPC]
| string || double || i4, int|| boolean || base64 || dateTime.iso8601 || nil
|-
! [http://developer.apple.com/documentation/Cocoa/Conceptual/PropertyLists/Concepts/XMLPListsConcept.html Mac OS X plists]
| string || real || integer || true, false || data || date || nil
|-
! [http://www.crockford.com/JSON JSON] (JavaScript)
| string || number || number || true, false || N/A || Date || nil
|-
! [http://yaml.org/spec/current.html#id2503753 YAML] tags
| str || int || float || bool || null (base 64) || N/A || null
|-
! [http://java.sun.com/j2se/1.3/docs/guide/jdbc/getstart/mapping.html#table1 SQL (JDBC)]
| char,varchar || float, double, real || decimal, numeric || bit || binary || date, time, timestamp || ?
|-
! [http://www.sysprog.net/ctype.html C]
| char[] || float, double || int, long, short || bool, int || char[] || N/A || (void*)0
|-
! [http://java.sun.com/docs/books/tutorial/java/nutsandbolts/datatypes.html Java]
| char, String || float, double || int, long, short, byte || boolean || N/A || util.Date || null
|-
! [http://www.zend.com/manual/language.types.php PHP]
| string || float (double)|| integer || boolean || array || N/A || NULL
|-
! [http://search.cpan.org/dist/perl/pod/perldata.pod Perl]
| array || scalar || scalar || scalar || array || N/A
|-
! [http://en.wikibooks.org/wiki/Programming:Python_Numbers Python]
| str || float, complex || int, long || bool || binascii, base64 || time,datetime
|-
! [http://www.rubycentral.com/book/ext_ruby.html Ruby] + [http://www.rubycentral.com/book/lib_standard.html lib]
| String || Float || Fixnum, Bignum || TrueClass,FalseClass || Hash || Date || NilClass
|-
! [http://www.rebol.com/docs/core23/rebolcore-16.html REBOL]
| string! || decimal! || integer! || logic! || binary! || date!, time! || none!
|-
|}

== Analysis ==
The most common set of datatypes appears to be those represented by XML-RPC, which (perhaps fortunately) also has historical precedence on the web:
* string
* double
* int [i4] - 4-byte integer (32-bit)
* boolean (0,1)
* base64
** Lets call this 'binary' as the encoding is in the data: url, and DRY applies
** RFC 2426 uses "B", which, when lowercased per microformats [[naming-principles]] is 'b'. -Tantek
* dateTime[.iso8601]

Whlle not perfect, these certainly cover the 80% case, and are reasonably well-defined. That said, there are a number of open questions about how to use them:
# should 'string' also be explicitly specified, or can it be assumed?
#*Assumed, and also defined as utf-8. [[User:Kevin Marks|Kevin Marks]] 16:39, 13 Feb 2006 (PST)
#*Agreed with Kevin. 'string' should be the default if no type is specified. Publishers MAY explicitly specify 'string'.
#*Shouldn't the encoding be that of the page the markup is found on (as specified in the HTTP and HTML specs), rather than defined as utf-8? [[User:Jim Ancona|Jim Ancona]]
# does 'int' always mean 32-bits?
## If so, what should be used for 64-bit integers or cryptographic (256-bit+) numbers?
###Python's 'long' is simple, but ambiguous.
###Ruby's BigNum is clear but much less common.
###XML-Schema has so many types it is hard to say.
###* In this case, XML-Schema makes the distinction that 'int' represents a standard 32 bit integer, while 'integer' represents a signed integer of arbitrary length.
###SQL's "decimal", perhaps?
## If not, how should conforming implementations react to longer integers than they can handle?
##*I think integer is fine - we don't have an explict constraint here. Do you want to define +Inf -Inf and NaN behaviour? Certainly when building testcases and examples include these.

# Is it worth deviating from the standard to allow "dateTime" as an alias? (the one case where XML Schema is actually simpler)
#* See comments below regarding date-time.

== Proposal ==
The proposal is to adopt [http://www.xmlrpc.com/spec/ XML-RPC] scalar values as the class names for typed microformats, with the following caveats:
* the alias 'i4' for integer SHOULD not be used
* the name 'long' MAY be used for 64-bit or longer integers
* for 'dateTime'
** can we make this 'datetime' ? [[User:Kevin Marks|Kevin Marks]] 16:39, 13 Feb 2006 (PST)
** microformats don't use camel case. please see [[naming-principles]]. alternatives (Tantek):
*** date-time (if you consider it to be two words)
*** datetime (as proposed by Kevin, if you think it is one word)
*** dt (reusing the common prefix shared by existing microformat class names: dtstart, dtend, dtreviewed from [[hcalendar|hCalendar]] and [[hreview|hReview]]. We could also make that a general rule for microformat class names for properties which take ISO8601 datetimes. (Tantek)
** the trailing '.iso8601' MUST be omitted, as '.' is not (always?) valid in HTML class names
*** '.' is neither a valid HTML class name, nor a valid character (unescaped at least) in a CSS class selector. - Tantek
** date/time formats SHOULD follow the [http://www.w3.org/TR/NOTE-datetime W3C profile] of [http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]
** a more human-readable rendering may be used, with the ISO8601 value in an "abbr"
* binary data SHOULD be encoded in a [http://en.wikipedia.org/wiki/Data:_URI_scheme data: URI], with an explicit [http://www.htmlhelp.com/reference/html40/special/a.html ContentType] and a human-readable description as the body of the anchor.
* if no datatype is specified, an implementation MAY either attempt to infer a datatype from the syntax of the value, or simply assert that the value is a string. Thus, conforming implementations SHOULD always explicitly label strings.
** Disagree - either we are labelling datatypes and thus labelling string is redundant, or we are trying to guess from syntax. If the latter this whole spec is unnecessary. [[User:Kevin Marks|Kevin Marks]] 16:39, 13 Feb 2006 (PST)
** Agreed with Kevin. Let's keep 'string' as the default, and allow explicit usage of it. -Tantek

To indicate that a particular micforomat uses typed values, precede that microformat with the class name 'typed', as in:

<pre><nowiki>
<ol class="typed xoxo">
</nowiki></pre>

== Example ==

<dl class="typed xoxo">
<dt>key</dt><dd class="string">value</dd>
<dt>integer</dt><dd class="int">137</dd>
<dt>real</dt><dd class="double">3.14159265</dd>
<dt>date</dt><dd class="dateTime">1994-11-05T13:15:30Z</dd>
<dt>date(abbr)</dt><dd class="dateTime"><abbr title="1994-11-05">November 5, 1994</abbr></dd>
<dt>true</dt><dd class="boolean">1</dd>
<dt>false</dt><dd class="boolean">0</dd>
<dt>data</dt><dd class="base64"><a href="data:;base64,sdcfo2JTiXE=" type="image/jpg">my image</a></dd>
</dl>

Example revised with above suggestions:

<dl class="typed xoxo">
<dt>key</dt><dd>value</dd>
<dt>integer</dt><dd class="int">137</dd>
<dt>real</dt><dd class="double">3.14159265</dd>
<dt>date</dt><dd class="datetime">1994-11-05T13:15:30Z</dd>
<dt>date(abbr)</dt><dd class="datetime"><abbr title="1994-11-05">November 5, 1994</abbr></dd>
<dt>true</dt><dd class="boolean">1</dd>
<dt>false</dt><dd class="boolean">0</dd>
<dt>data</dt><dd class="binary"><a href="data:;base64,sdcfo2JTiXE=" type="image/jpg">my image</a></dd>
</dl>

'''Note:''' [[xoxo|XOXO]] always starts with either <code>ol</code> or <code>ul</code>. The <code>dl</code> in XOXO is always used to declare the properties of a specific <code>li</code>. These examples should be updated accordingly. -Tantek

== References ==
* [http://en.wikipedia.org/wiki/Datatype Datatypes] in Wikipedia
* Origional [http://microformats.org/discuss/mail/microformats-discuss/2005-September/001020.html datatype] discussion
* Original [http://homepage.mac.com/drernie/plist.html plist] datatype mapping proposal
* Revised [http://opendarwin.org/~drernie/xoxo-datatypes.html xoxo datatype] proposal

== See Also ==
* [[xoxo]]
* [[naming-principles]]

rest

2005-11-30T21:00:14Z

JimAncona: Fix broken link

= Microformats in REST Web Services =
This the home page for discussion, research, and standards regarding how to optimally use Microformats as the encoding for [http://en.wikipedia.org/wiki/Representational_State_Transfer REST] web services. The goal is for all REST-related information in the microformats world to live under this URL.

== Discussion Forums ==
* [http://microformats.org/discuss/mail/microformats-rest/ uf-rest] discussion list on microformats.org
* [http://groups.yahoo.com/group/rest-discuss/ rest-discuss] @ Yahoo Groups

== Topics ==
=== URLs ===
;[[rest/opacity]]
:Properly Interpreting the "Axiom of URI Opacity"
;[[rest/urls]]
:How should URLs be structured for maximum clarity & discoverability?
=== HTML ===
;[[rest/ahah]]
:Asychronous HTML vs. AJAX
;[[rest/description]]
:What, if anything, is the analogue of WSDL for REST services?
;[[rest/webforms]]
:Upgrading browsers to support PUT and DELETE properly
=== Implementations ===
;[[rest/cgi]]
:CGI is slow, and FastCGI is designed for C parsers. Is there a third option?
;[[rest/rails]]
:Ways to make Ruby on Rails more REST-friendly out of the box.
=== Standards ===
* [http://www.ietf.org/rfc/rfc3205.txt HTTP as a Substrate] - Best Current Practice
* [http://www.faqs.org/rfcs/rfc2483.html text/uri-list] (Section 5, URI Resolution Services)

== Background Research ==
=== Examples ===
* [[rest/examples]]
* [[rest/forms-examples]]

=== Brainstorming ===

* [[rest/brainstorming]]
* [[rest/forms-brainstorming]]

== Proposals ==
Note that these are all preliminary.

* [[http://www.opendarwin.org/~drernie/C395201355/rest-enabled-xhtml-20051019.html REST-Enabled XHTML]] by Dr. Ernie
** original at [[rest/rex-proposal]]
* [http://restylab.php5.cz/dreams/webutopia.html WebUtopia] by Toydi
** more details in rest-discuss thread: [http://groups.yahoo.com/group/rest-discuss/message/5290 "Dreams about ReSTifying web apps"]

== Implementations ==

=== Tools ===
* [[xoxo-sample-code| XOXO parser (python)]]
** also [http://www.opendarwin.org/~drernie/xoxo-plist.py xoxo-plist.py], a pyobjc variant support Mac OS X plists]
* [http://www.opendarwin.org/~drernie/src/ahah.js ahah.js] Asynchronous HTML over HTTP
** was [http://epeus.blogspot.com/2005_05_01_epeus_archive.html#111588374981985824 JAH], an [http://technorati.com/tag/AJAX AJAX] alternative)
* Ruby RESTifarian plugin
$ script/plugin install restifarian # need beta gems/edge rails for this to work
** See also prototype [http://www.onautopilot.com/oss/rails/rest_controller.rb controller]

=== Examples ===
* [http://www.opendarwin.org/~drernie/C499496031/E20051019100520/index.html DARC]: Darwin-Apache-Rails-CoreData
* [http://www.opendarwin.org/~drernie/C499496031/E20051026153908/index.html TurboGear] AddressBook (Mac OS X-only)
=== Sites ===
* [http://www.larrystaton.com Larry Staton Jr.] AHAH-enabled homepage (a first!)

== Participants ==
* [http://www.opendarwin.org/~drernie/C395201355/index.html Dr. Ernie Prabhakar]
* [http://restylab.php5.cz/ toydi]
* [mailto:dimitri.glazkov@gmail.com Dimitri Glazkov]
* [http://www.xrest.org Max Voelkel (xamde)]
* [http://www.loudthinking.com/ David Heinemeier Hansson]

Microformats Wiki - User contributions [en]

rest/datatypes

rest