json-wheel: JSON library for OCaml

Introduction

From www.json.org:

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999.

This implementation follows RFC 4627. We use key/value lists to represent JSON objects, and lists to represent JSON arrays. The library also provides pretty-printing and optional support for C-style comments.

Documentation

Ocamldoc-generated documentation is available.

Download

This software was written by Mika Illouz and Martin Jambon, with some contributions by Gerd Stolpmann. It is distributed under a BSD license. The current version is 1.0.6; see Changes.

We also recommend json-static which greatly simplifies the job of converting from generic JSON data to specialized OCaml types (JSON objects -> OCaml objects, etc.).

Notes

The JSON parser, in the default mode, conforms to the specifications of RFC 4627, with only some limitations due to the implementation of the corresponding OCaml types:

• ints that are too large to be represented with the OCaml int type cause an error. The limit depends whether it is a 32-bit or 64-bit platform (see min_int and max_int).
• floats may be represented with reduced precision as they must fit into the 8 bytes of the "double" format.
• The size of OCaml strings is limited to about 16MB on 32-bit platforms, and much more on 64-bit platforms (see Sys.max_string_length).

The UTF-8 encoding is supported, however no attempt is made at checking whether strings are actually valid UTF-8 or not. Therefore, other ASCII-compatible encodings such as the ISO 8859 series are supported as well.

JSON equivalents of OCaml types

JSON provides only two kinds of containers which are very flexible, while OCaml provides a greater variety of containers which are more specialized. Here is a suggestion on how you could convert OCaml data to JSON, assuming you have a choice.

There is now a camlp4 syntax extension, json-static, that generates converters between OCaml and Json_type.t all by itself, using only type declarations. It allows the programmer to ignore the middle column of this table:

"abc"

1234

3.14

1.

-1.23e12

true

String "abc"

Int 1234

Float 3.14

Float 1.

Float (-1.23e12)

Bool true

"abc"

1234

3.14

1.0

-1.23e12

true

(* List *)
[ "Hello"; "World" ]

(* Array *)
[| "Hello"; "World" |]

Array [ String "Hello";
        String "World" ]

[ "Hello", "World" ]

("abc", 1234)

Array [ String "abc"; Int 1234 ]

[ "abc", 1234 ]

(* Record *)
{ x = 0; 
  y = 1; 
  show = true }

(* Object *)
object 
  method x = 0 
  method y = 1 
  method show = true 
end

Object [ "x", Int 0; 
         "y", Int 1; 
         "show", Bool true ]

{ "x": 0,
  "y": 1,
  "show": true }

(* Association list *)
[ "x", 0; 
  "y", 1 ]

Object [ "x", Int 0; 
         "y", Int 1 ]

{ "x": 0,
  "y": 1 }

None

Some "abc"

Null

String "abc"

null

"abc"

(* No argument *)
A

`A

(* One argument *)
B "abc"

`B "abc"

(* One argument of type tuple *)
Coord (123, 456)

`Coord (123, 456)

(* Several arguments *)
Coord2 (123, 456)

(* No argument *)
String "A"

(* One argument *)
Array [ String "B",
        String "abc" ]

(* One argument of type tuple *)
Array [ String "Coord", 
        Array [ Int 123,
                Int 456 ] ]

(* Several arguments *)
Array [ String "Coord2", 
        Int 123, 
        Int 456 ]

/* No argument */
"A"

/* One argument */
[ "B", "abc" ]

/* One argument of type tuple */
[ "Coord", [ 123, 456 ] ]

/* Several arguments */
[ "Coord2", 123, 456 ]

JSON vs. Freddy XML

The XML to JSON mapping which is proposed by JsonML is a good illustration of the flexibility of JSON.

Simple examples

On the OCaml side, here are two examples of the typical operations that you would perform:

(* Program that builds a JSON object and saves it into a file *)
open Json_type

let obj = Object [ "x", Int 1;
                   "y", Int 2 ]
let _ = Json_io.save_json "point.js" obj

(* Program that reads a JSON object from a file and converts it
   into a specialized type. 
   Uses file "point.js" created by the previous example. *)
open Json_type
open Json_type.Browse

let json_obj = Json_io.load_json "point.js"
let tbl = make_table (objekt json_obj)
let x = int (field tbl "x")
let y = int (field tbl "y")
let _ = Printf.printf "x = %i\ny = %i\n" x y

Maybe you are using JSON to communicate between a web page and a HTTP server that serves JSON data. There are two options for reading pure JSON data:

• Use eval, after adding parentheses around the JSON code: eval('(' + responseText + ')'),
• or use a proper JSON parser for JavaScript, which is considered more secure, but really you are requesting stuff only from your own server anyway.

Read more about this at json.org.

Now, one of the most exciting features of asynchronous HTTP requests from JavaScript (or "AJAX" if you like the term), is to request information from other websites than your own and include it in your pages. Well, this is disabled by the web browsers... probably just to annoy programmers, since you can emulate the same functionality, with unfortunately even less safety. The principle is the following:

1. The client-side javascript creates a URL that should return the data that we need from a server.
2. Then it inserts a script element, e.g. <script type="text/javascript" src="http://example.com/query?x=123&y=true" /> anywhere in the document.
3. You guessed it, the server must serve real javascript code that will be magically downloaded and executed (if not already cached by the browser). Normally it would be a simple callback performed on JSON data.

For more information, visit the Yahoo! Web Services page on JSON.