Permalink
acbcdf6 Aug 17, 2013
1 contributor

Users who have contributed to this file

364 lines (242 sloc) 9.54 KB

MessagePack format specification

This spec is updated. See spec.md for the updated version.

MessagePack saves type-information to the serialized data. Thus each data is stored in type-data or type-length-data style. MessagePack supports following types:

  • Fixed length types
    • Integers
    • nil
    • boolean
    • Floating point
  • Variable length types
    • Raw bytes
  • Container types
    • Arrays
    • Maps

Each type has one or more serialize format:

  • Fixed length types
    • Integers
      • positive fixnum
      • negative fixnum
      • uint 8
      • uint 16
      • uint 32
      • uint 64
      • int 8
      • int 16
      • int 32
      • int 64
    • Nil
      • nil
    • Boolean
      • true
      • false
    • Floating point
      • float
      • double
  • Variable length types
    • Raw bytes
      • fix raw
      • raw 16
      • raw 32
  • Container types
    • Arrays
      • fix array
      • array 16
      • array 32
    • Maps
      • fix map
      • map 16
      • map 32

To serialize strings, use UTF-8 encoding and Raw type.

See this thread to understand the reason why msgpack doesn't have string type: [https://github.com/msgpack/msgpack/issues/121]

Integers

positive fixnum

save an integer within the range [0, 127] in 1 bytes.

+--------+
|0XXXXXXX|
+--------+
=> unsigned 8-bit 0XXXXXXX

negative fixnum

save an integer within the range [-32, -1] in 1 bytes.

+--------+
|111XXXXX|
+--------+
=> signed 8-bit 111XXXXX

uint 8

save an unsigned 8-bit integer in 2 bytes.

+--------+--------+
|  0xcc  |XXXXXXXX|
+--------+--------+
=> unsigned 8-bit XXXXXXXX

uint 16

save an unsigned 16-bit big-endian integer in 3 bytes.

+--------+--------+--------+
|  0xcd  |XXXXXXXX|XXXXXXXX|
+--------+--------+--------+
=> unsigned 16-bit big-endian XXXXXXXX_XXXXXXXX

uint 32

save an unsigned 32-bit big-endian integer in 5 bytes.

+--------+--------+--------+--------+--------+
|  0xce  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+
=> unsigned 32-bit big-endian XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

uint 64

save an unsigned 64-bit big-endian integer in 9 bytes.

+--------+--------+--------+--------+--------+--------+--------+--------+--------+
|  0xcf  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+--------+--------+--------+--------+
=> unsigned 64-bit big-endian XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

int 8

save a signed 8-bit integer in 2 bytes.

+--------+--------+
|  0xd0  |XXXXXXXX|
+--------+--------+
=> signed 8-bit XXXXXXXX

int 16

save a signed 16-bit big-endian integer in 3 bytes.

+--------+--------+--------+
|  0xd1  |XXXXXXXX|XXXXXXXX|
+--------+--------+--------+
=> signed 16-bit big-endian XXXXXXXX_XXXXXXXX

int 32

save a signed 32-bit big-endian integer in 5 bytes.

+--------+--------+--------+--------+--------+
|  0xd2  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+
=> signed 32-bit big-endian XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

int 64

save a signed 64-bit big-endian integer in 9 bytes.

+--------+--------+--------+--------+--------+--------+--------+--------+--------+
|  0xd3  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+--------+--------+--------+--------+
=> signed 64-bit big-endian XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

Nil

nil

save a nil.

+--------+
|  0xc0  |
+--------+

Boolean

true

save a true.

+--------+
|  0xc3  |
+--------+

false

save a false.

+--------+
|  0xc2  |
+--------+

Floating point

float

save a big-endian IEEE 754 single precision floating point number in 5 bytes.

+--------+--------+--------+--------+--------+
|  0xca  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+
=> big-endian IEEE 754 single precision floating point number XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

double

save a big-endian IEEE 754 double precision floating point number in 9 bytes.

+--------+--------+--------+--------+--------+--------+--------+--------+--------+
|  0xcb  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|
+--------+--------+--------+--------+--------+--------+--------+--------+--------+
=> big-endian IEEE 754 single precision floating point number XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX

Raw bytes

fix raw

save raw bytes up to 31 bytes.

+--------+--------
|101XXXXX|...N bytes
+--------+--------
=> 000XXXXXX (=N) bytes of raw bytes.

raw 16

save raw bytes up to (2^16)-1 bytes. Length is stored in unsigned 16-bit big-endian integer.

+--------+--------+--------+--------
|  0xda  |XXXXXXXX|XXXXXXXX|...N bytes
+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX (=N) bytes of raw bytes.

raw 32

save raw bytes up to (2^32)-1 bytes. Length is stored in unsigned 32-bit big-endian integer.

+--------+--------+--------+--------+--------+--------
|  0xdb  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|...N bytes
+--------+--------+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX (=N) bytes of raw bytes.

Arrays

fix array

save an array up to 15 elements.

+--------+--------
|1001XXXX|...N objects
+--------+--------
=> 0000XXXX (=N) elements array.

array 16

save an array up to (2^16)-1 elements. Number of elements is stored in unsigned 16-bit big-endian integer.

+--------+--------+--------+--------
|  0xdc  |XXXXXXXX|XXXXXXXX|...N objects
+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX (=N) elements array.

array 32

save an array up to (2^32)-1 elements. Number of elements is stored in unsigned 32-bit big-endian integer.

+--------+--------+--------+--------+--------+--------
|  0xdd  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|...N objects
+--------+--------+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX (=N) elements array.

Maps

fix map

save a map up to 15 elements.

+--------+--------
|1000XXXX|...N*2 objects
+--------+--------
=> 0000XXXX (=N) elements map
   where odd elements are key and next element of the key is its associate value.

map 16

save a map up to (2^16)-1 elements. Number of elements is stored in unsigned 16-bit big-endian integer.

+--------+--------+--------+--------
|  0xde  |XXXXXXXX|XXXXXXXX|...N*2 objects
+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX (=N) elements map
   where odd elements are key and next element of the key is its associate value.

map 32

save a map up to (2^32)-1 elements. Number of elements is stored in unsigned 32-bit big-endian integer.

+--------+--------+--------+--------+--------+--------
|  0xdf  |XXXXXXXX|XXXXXXXX|XXXXXXXX|XXXXXXXX|...N*2 objects
+--------+--------+--------+--------+--------+--------
=> XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX (=N) elements map
   where odd elements are key and next element of the key is its associate value.

Type Chart

TypeBinaryHex
Positive FixNum0xxxxxxx0x00 - 0x7f
FixMap1000xxxx0x80 - 0x8f
FixArray1001xxxx0x90 - 0x9f
FixRaw101xxxxx0xa0 - 0xbf
nil110000000xc0
_reserved_110000010xc1
false110000100xc2
true110000110xc3
_reserved_110001000xc4
_reserved_110001010xc5
_reserved_110001100xc6
_reserved_110001110xc7
_reserved_110010000xc8
_reserved_110010010xc9
float110010100xca
double110010110xcb
uint 8110011000xcc
uint 16110011010xcd
uint 32110011100xce
uint 64110011110xcf
int 8110100000xd0
int 16110100010xd1
int 32110100100xd2
int 64110100110xd3
_reserved_110101000xd4
_reserved_110101010xd5
_reserved_110101100xd6
_reserved_110101110xd7
_reserved_110110000xd8
_reserved_110110010xd9
raw 16110110100xda
raw 32110110110xdb
array 16110111000xdc
array 32110111010xdd
map 16110111100xde
map 32110111110xdf
Negative FixNum111xxxxx0xe0 - 0xff