JSON.md

title	layout	sortBy
JSON Notes	post	6

Babel's default protocol is JSON. JSON maps nicely to data structures in a variety of languages.

All types may be null. However, Babel-generated code initializes lists and maps, so they will usually not be null. Member initializers can also be used to prevent a value from being null.

When struct members are null, they are not written to the JSON. This behavior should be standard across all supported languages.

Lists and maps can contain null values and those will be written to the output.

Babel Type	JSON Representation	Notes
bool	null true false
byte	null 8	Bytes are unsigned.
int8	null -8 8
int16	null -16 16
int32	null -32 32
int64	null "-64" "64"	Quoted to make large values safe for JavaScript.
float32	null -3.14 3.14
float64	null -3.14159 3.14159
string	null "" "Hello, world"
datetime	null "2013-09-09T13:44:22.341-05:00" "2013-09-09T18:44:22.341Z"	Standard format string with a required time zone offset. "Z" is allowed to designate UTC time.
decimal	null "-99.987" "99.987"	Quoted to make long values safe for JavaSceript.
char	null "A"	Should contain exactly one character.
binary	null "YXNhZGFzZAo="	Base64-encoded string containing binary data.
list	null [ ] [ 3, null, 5, 6]	The code makes every attempt to keep lists initialized; you should generally not see null. Lists may contain null values, however. Items in a list all have the same type and can be any type supported by Babel, including lists, maps, and user-defined types.
map	null { } { "3":"hello", "4":null, "5":"world" }	The code makes every attempt to keep maps initialized; you should generally not see null. Maps can have null values, but keys may not be null. Keys are all of the same type and must be a primitive type. Keys are always quoted regardless of type. Values are all of the same type and can be any type supported by Babel, including lists, maps, and user-defined types.
enum	null "Texas"	Enumerations are represented as a string containing the name. The ordinal value is not transmitted but can be used by client code.
const		Consts have no impact on the JSON format.
struct	null { } { "X":32, "Y":["a","b"] }	Structures serialize their members like a map of named items. Members with a null value are not serialized. Maps and lists should not be null; they will appear as empty.
void		void is only allowed on method returns. The server should provide an empty response for void methods.

Methods

Methods transmit parameters in the HTTP request and receive the return value in the HTTP response.

Parameters

Parameters are serialized like an anonymous struct. If the function is:

bool CanHazCheeseburger(string nameOfCat, float64 weight);

Then the parameter list would look like:

{
	"nameOfCat": "Moxy",
	"weight": 13.3
}

Just like regular structs, a null parameter does not need to be written. Thus, if all parameters were null, the client might send:

{}

This is actually what a client should send when there are no parameters. However, Babel libraries should also accept empty data in this case.

Return Values

Return values are sent directly with no wrapper object.

Primitive Types

A function returning a primitive type returns it directly in the response:

int32 GetData();

Returns:

34

Keep in mind that the service might return null.

struct

A function returning a struct:

MyStruct GetData();

Returns:

{ "X": 32 }

It could also return a struct will all null members:

{ }

Keep in mind that the service might return null.

list

A function returning a list:

list<string> GetData();

Returns:

[ "Bob", null, "Jane" ]

It could also return an empty list:

[ ]

Babel libraries should convert a null response to an empty list, but this is not a guarantee. Don't forget to check for null.

map

A function returning a map:

map<string,int32> GetData();

Returns:

{ "Bob": 12, "Jane": 24 }

It could also return an empty map:

{ }

Babel libraries should convert a null response to an empty map, but this is not a guarantee. Don't forget to check for null.

void

A function with no return:

void SayHello();

Should not return any data in the HTTP response.

General Rules

• Don't write struct members which are null.
• Always return a response unless the return type is void.
• Minify the JSON response if possible.
• Lists can have null entries.
• Maps can have null values, not not null keys.