json-static

Introduction
============

json-static is a syntax extension of OCaml that can make the use of
JSON data easier. From a special type declaration, the camlp4 preprocessor
generates the code that converts between a JSON "abstract syntax tree"
and specialized OCaml data structures such as objects, polymorphic variants,
lists, arrays, tuples, etc.

It will at the same time check that the structure of the JSON document
is correct and produce OCaml data which is statically typed.
For example, the following declaration defines the type of a point object:

  type json point = < x: float; y: float >

This automatically makes two functions available, with the following signature:

  val json_of_point : point -> Json_type.t
  val point_of_json : Json_type.t -> point

Json_type.t is the type of parsed JSON data, which is provided by 
the json-wheel library.

Function json_of_point would convert an OCaml object of type point into
a JSON object. point_of_json works the other way around, and fails 
by raising the Json_type.Json_error exception 
if the input JSON data doesn't have the right format.


Installation
============

Installation:
  make
  make install

Uninstallation:

  make uninstall


Usage
=====

Basically, you must preprocess your OCaml file(s) with 
camlp4o pa_json_static.cmo. Once installed using the standard
procedure (ocamlfind), you can compile a file using these commands:

# compile
ocamlfind ocamlopt -c yourfile.ml -syntax camlp4o -package json-static

# link
ocamlfind ocamlopt -o yourprog yourfile.cmx -linkpkg -package json-wheel

Build tools like OCamlMakefile take care of this nicely.


Syntax
======

You must write a special type declaration that describes the expected
format of the JSON data. There is a predefined mapping from OCaml types
to JSON:

OCaml type              JSON type         Properties of JSON data
----------              ---------         -----------------------

string                  String
float                   Number            not an int
int                     Number            an int
number*                 Number            a float or an int
bool                    Boolean

list                    Array             homogenous
array                   Array             homogenous
tuple                   Array             fixed length

(string * 'a) assoc**   Object            an object read as an associative list
(string, 'a) Hashtbl.t  Object
object or record        Object            additional methods/fields are ignored

option                  any               null means None

polymorphic variants    String or Array   a String for constructors without
                                          an argument, 
                                          or an Array of length 2
                                          where the first element is a
                                          String that represents the 
                                          constructor
                                          and the second element is the
                                          argument.

classic variants        String or Array   a String for contructors without 
                                          an argument,
                                          or an Array where the first element
                                          is the String that represents the
                                          constructor and the rest are the
                                          arguments. Unlike polymorphic
                                          variants, there may be several 
                                          arguments (just don't use parentheses
                                          around them in the type definition).

X.t***                  defined by X.of_json and X.to_json


---
*: the number type is an alias for float, but accepts JSON ints and converts
   them to OCaml floats.
**: the assoc type is an alias for list, but converts from a JSON object.
***: X can be any simple module name, but module fields t, of_json and to_json
     are mandatory.

A type definition is done like regular type definitions, but the keyword
"json" is placed just after "type", as in:

  type json t = int * float
       ^^^^

The type cannot be polymorphic, i.e. it doesn't support type parameters.
A small set of basic types are supported (see table above). Other type
names can be used only if they are part of the same definition.
This works:

  type json a = b
  and b = int list

But the following doesn't work:

  type json b = int list

  type json a = b  (* b is unknown to the preprocessor *)


In addition to the basic syntax for type declarations, a few extensions
have been added:

1) Object labels or variant names can be followed by an arbitrary string.
   When it is the case, this defines the string to be found in the JSON
   data.

2) Object methods can be preceded by a questionmark. If it is the case,
   JSON objects that do not have this field could still be read. 
   Their value is set to null instead of being undefined and causing an error.

3) A default value can be specified a after a method definition.
   The syntax is a "=" followed by an expression. The expression should
   be a constant. The default expression is used whenever 
   the JSON null value is encountered, even if the type converter
   knows how to deal with null.

4) Records and variant types must be named, as always in OCaml. Reusing
   an existing definition is possible by using the "predefined" keyword
   as in 
     type point = predefined { x : float; y : float }
   or
     type t = predefined A | B of bool * t

   Predefined read-only records or variant types (private)
   cannot be used as of version 0.9.3 of this program.


A common use of optional methods without a default argument is when omitting
an object field is allowed and considered equivalent to a null value.

Optional methods of a type that doesn't accept the null value don't make
much sense but are not rejected. The following is most likely an error:

  type json point = < ?x : int >

(if field "x" is not found in the JSON object, then the error would be
that null is not a valid int, instead of saying that field "x" is missing)

It should be either

  type json point = < ?x : int option >

or

  type json point = < ?x : int = 0 >



Example 1
=========

The following definition is correct:

type json point = < x: number; y: number >
and coords = point array

It can load successfully the following JSON data:

[ { "x": 1, "y": 0.5 },
  { "x": 0, "y": 0.3333333 } ]


Full example:

(* File example1.ml *)

type json point = < x: number; y: number >
and coords = point array

let json_string = "
  [ { \"x\": 1, \"y\": 0.5 },
    { \"x\": 0, \"y\": 0.3333333 } ]
"

let json_tree = Json_io.json_of_string json_string
let my_coords = coords_of_json json_tree
let _ = Array.iter (fun p -> Printf.printf "(%g, %g)\n" p#x p#y) my_coords

(* EOF *)

Save the example as "example1.ml", compile it and run it:

$ ocamlfind ocamlopt -o example1 -linkpkg -package json-static -syntax camlp4o example1.ml
$ ./example1
(1, 0.5)
(0, 0.333333)




Example 2
=========

This example shows you the representation that we chose for sum types in JSON:

(* File example2.ml *)

type json colors = [ `Black 
                   | `White 
                   | `Rgb of (float * float * float)
                   | `Any "*" ] list

let my_colors = [ `Black; `White; `Any;
                  `Rgb (1., 0., 0.);
                  `Rgb (0., 1., 0.);
                  `Rgb (0., 0., 1.) ]

let _ = print_endline (Json_io.string_of_json (json_of_colors my_colors))

(* EOF *)


$ ocamlfind ocamlopt -o example2 -linkpkg -package json-static -syntax camlp4o example2.ml
$ ./example2
[
  "Black",
  "White",
  "*",
  [ "Rgb",
    [ 1.0,
      0.0,
      0.0 ]
  ],
  [ "Rgb",
    [ 0.0,
      1.0,
      0.0 ]
  ],
  [ "Rgb",
    [ 0.0,
      0.0,
      1.0 ]
  ]
]

Note how we specified that `Any translates into "*" rather than "Any".
The same technique is available to rename object methods, and it is crucial
when some existing JSON format uses method names that are not valid
OCaml identifiers.