Unified Message Structure¶

XML¶

XML is the least efficient format to use among the supported ones, and is mainly kept as a way for getting output that is easy-to-read, for instance for debugging or inspection.

message User {
  required int32  id = 1;
  required bool   isActive = 2;
  required string firstName = 3;
  required string lastName = 4;
  required float  height = 5;
  optional uint32 age = 6;
}

<User>
  <id>42</id>
  <isActive>1</isActive>
  <firstName>John</firstName>
  <lastName>Doe</lastName>
  <height>1.80</height>
</User>

message HeightMap {
  required uint32 width = 1;
  required uint32 height = 2;
  repeated int32  valueList = 3;
}

<HeightMap>
  <width>2</width>
  <height>2</height>
  <valueList>
   <value>1</value>
   <value>10</value>
   <value>7</value>
   <value>3</value>
  </valueList>
</HeightMap>

message PhoneBook {
  message PhoneNumber {
      required string number = 1;
      optional string extension = 2;
  }
  repeated PhoneNumber phoneNumberList = 1;
}

<PhoneBook>
  <phoneNumberList>
    <phoneNumber>
      <number>12345678</number>
      <extension>+47</extension>
    </phoneNumber>
    <phoneNumber>
      <number>555-768</number>
    </phoneNumber>
  </phoneNumberList>
</PhoneBook>

JSON¶

JSON uses the order of the fields to pack messages into JSON lists. Lists were chosen to cut down on the amount of information that is needed to send.

All integer types are encoded/decoded as textual numbers. Size and sign are checked for when decoding numbers. Boolean type is encoded/decoded as a textual number with 0 being false and 1 being true. Other values are not allowed. Strings are encoded as UTF-8 JSON strings. Binary data is encoded as JSON strings containing the base-64 representation of the binary data. Messages are encoded as JSON lists with the order of the fields being kept. Missing elements are sent as the null type. In addition, trailing elements which are missing are cut off from the list. Repeated types are encoded as JSON lists.

For more details on JSON see RFC 4627 or visit http://json.org

For instance this structure:

message DummyData {
  required int32 id = 1;
  required string name = 2;
  repeated int32 fib = 3;
}

Could be encoded like this:

[1,"foo",[1,1,2,3,5]]

Using more optional fields:

message DummyData {
  required int32 id = 1;
  optional string name = 2;
  message SubData {
    required uint32 field1 = 1;
    optional uint32 field2 = 2;
    optional uint32 field3 = 3;
  }
  required SubData msg = 4;
}

Could be encoded like this:

[1,null,[4]]

While this would be just as valid:

[1,null,[4,null,null]]

Protocol Buffers¶

PB is the most efficient way to transport data for languages that excel at encoding/decoding binary data (e.g. C/C++). Other languages like JavaScript and Python might be better off with using JSON.

PB is explained in detail at the main site: http://code.google.com/apis/protocolbuffers/docs/overview.html

C++¶

The C++ generator translates the message structures into C++ classes. This allows C++ code to interact with messages using native structures. Encoding and decoding is handled as a separate layer and is generated.

Javascript¶

Code generation for JavaScript is designed around the fact that JavaScript code will use JSON for formatting messages on the wire. This means that there is little need for encoding/decoding of data. Extended code generation is available when RPC (services) are in use.

To aid in debugging incoming JSON data the system can generate code that outputs JSON data to a human-readable form.

Python¶

Java¶