1. Welcome to ejson

Introduction

ejson is a JSON encoding/decoding library for Erlang. It gives a declarative interface for jsx by which we need to specify conversion rules and ejson will convert tuples according to the rules.

Using ejson one should define rules which gives a mapping for each field of a record describing how to convert the field possible values to JSON. ejson is intended to create such a conversion system with which one can easily decode JSONs back to Erlang records. So at first the rules can seem to be complicated but there reason is that we can convert and parse (encode and decode) terms and JSONs.

Simple example

-module(people).
%% You can specify in rebar.config, erlang.mk, too.
-compile({parse_transform, ejson_trans}).

%% Record definitions are not needed for ejson but you.
-record(person, {name, birth_year, projects}).
-record(project, {name, budget, successful}).

-json({person, {string, "name"}, {number, "yearOfBirth"},
               {list, "projects", [{type, project}]}]}).
-json({project, {string, "name"}, {number, "budget"},
                {boolean, "isSuccessful"}]}).

%% parse_transform generates to_json/1 and from_json/{1,2} local functions

start() ->
    Jim = #person{
        name = "Jim",
        birth_year = 1967,
        projects = [#project{name = "Authoring",
                             budget = 100000
                             successful = true}]},
    {ok, Json} = to_json(Jim),
    io:format("~s~n", [Json]),
    {ok, Person} = from_json(Json, person).  %% Specify the the expected type here

The person record results in a JSON like this:

{
    "name": "Jim",
    "yearOfBirth": 1967,
    "projects": [
       {
           "name": "Authoring",
           "budget": 100000,
           "isSuccessful": true
       }
    ]
}

How does ejson work?

ejson (by the help of ejson_trans parse transform) reads compiled modules which are compiled with that parse transform. It collected all -json(...) wild attributes to get the conversion rules. It also defined 3 functions in those modules (if are not defined already).

to_json(Record) -> {ok, JSON::binary()} | {error, Reason::term()}.
from_json(Json) -> {ok, Record::term()} | {error, Reason::term()}.
from_json(Json, ExpectedType::atom()) -> {ok, Record::term()} | {error, Reason::term()}.

Those function are not exported since they are intended to use in the underlying module. to_json/1 converts records to json binaries, from_json/2 parse json binary and apply the rules to extract the record specified in the second parameter. In ejson we can convert records in a way that the JSON will contain a meta-type field (__rec field) which stores from what record the JSON has been converted. So in that way we can use from_json/1 to decode records back. The only disadvantage of that method is that JSONs will contain a __rec field, so picky applications may not accept those JSONs (or remove that field when sending JSONs back).