JSON Representation of MATLAB Data Types

This topic describes the JSON representation of MATLAB^® data types. JavaScript Object Notation or JSON is a text-based, programming-language independent data interchange format. The JSON standard is defined in RFC 7159 and can represent four primitive types and two structured types. Since JSON is programming language independent, you can represent MATLAB data types in JSON. For more about MATLAB data types, see Fundamental MATLAB Classes (MATLAB).

Using the JSON representation of MATLAB data types, you can:

• Represent data or variables in the client code to serve as inputs to the MATLAB function deployed on the server.

• Parse the response from a MATLAB Production Server™ instance for further manipulation in the client code.

The response from the server contains a JSON array, where each element of the array corresponds to an output of the deployed MATLAB function represented as a JSON object.

You can represent MATLAB data types in JSON using two formats: small and large.

• Small format provides a simplified representation of MATLAB data types in JSON. There is a one-to-one mapping between MATLAB data types and their corresponding JSON representation. MATLAB data types that are scalar and of type double, logical, and char can be represented using the small notation. Multidimensional MATLAB arrays of type double, logical, and struct can also be represented using small notation.

• Large format provides a generic representation of MATLAB data types in JSON. The large format uses the JSON object notation consisting of property name-value pairs to represent data. You can use large notation for any MATLAB data type that cannot be represented in small notation. The response from the MATLAB Production Server always uses large notation.

A JSON object contains the following property name-value pairs:

Property Name	Property Value
"mwtype"	JSON string representing the type of data. The property value is specified within "". "double" | "single" "int8" | "uint8" | "int16" | "uint16" "int32" | "uint32" | "int64" | "uint64" "logical" | "char" | "struct" | "cell"
"mwsize"	A JSON array representing the dimensions of the data. Specify the property value by enclosing the dimensions as a comma-separated list within [] .
"mwdata"	JSON array representing the actual data. The property value is specified by enclosing the data as a comma-separated list within [] .
"mwcomplex" (when representing complex numbers.)	Set to JSON true .

MATLAB Compiler SDK™ has four utility functions that make converting data between MATLAB and JSON simpler. They are:

Function Name	Purpose
mps.json.encode (MATLAB Compiler SDK)	Convert MATLAB data to JSON text using MATLAB Production Server JSON schema
mps.json.decode (MATLAB Compiler SDK)	Convert a character vector or string in MATLAB Production Server JSON schema to MATLAB data
mps.json.encoderequest (MATLAB Compiler SDK)	Convert MATLAB data in a server request to JSON text using MATLAB Production Server JSON schema
mps.json.decoderesponse (MATLAB Compiler SDK)	Convert JSON text from a server response to MATLAB data

JSON Representation of MATLAB Data Types

• Numeric Types: double, single

• Numeric Types: NaN, Inf, -Inf

• Numeric Types: Integers

• Numeric Types: Complex Numbers

• Characters

• Logical

• Cell Arrays

• Structures

• Empty Arrays: []

• Multidimensional Arrays

Numeric Types: double, single

MATLAB Data Type	JSON Small Notation	JSON Large Notation
double	number	{ "mwtype": "double", "mwsize": [1,1], "mwdata": [number] }
single	No small representation.	{ "mwtype": "single", "mwsize": [1,1], "mwdata": [number] }
Example:
double(12.905)	12.905	{ "mwtype": "double", "mwsize": [1,1], "mwdata": [12.905] }
single(20.15)	No small representation.	{ "mwtype": "single", "mwsize": [1,1], "mwdata": [20.15] }
42	42	{ "mwtype": "double", "mwsize": [1,1], "mwdata": [42] }

Numeric Types: NaN, Inf, -Inf

• NaN,Inf,-Inf are numeric types whose underlying MATLAB class can be either double or single only. NaN, Inf,-Inf cannot be represented as an integer type in MATLAB.

MATLAB Data Type	JSON Small Notation	JSON Large Notation
NaN	{"mwdata":"NaN"}	{ "mwtype": "double", "mwsize": [1,1], "mwdata": ["NaN"] } Or { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"NaN"}] }
Inf	{"mwdata":"Inf"}	{ "mwtype": "double", "mwsize": [1,1], "mwdata": ["Inf"] } Or { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"Inf"}] }
-Inf	{"mwdata":"-Inf"}	{ "mwtype": "double", "mwsize": [1,1], "mwdata": ["-Inf"] } Or { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"-Inf"}] }
[] empty double	[]	{ "mwtype": "double", "mwsize": [0,0], "mwdata": [ ] }

Numeric Types: Integers

• Integer types from MATLAB cannot be represented using JSON small notation.

MATLAB Data Type	JSON Large Notation
int8, uint8, int16, uint16 int32, uint32, int64, uint64	{ "mwtype": "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" , "mwsize": [1,1], "mwdata": [number] }
Example:
int8(23)	{ "mwtype": "int8", "mwsize": [1,1], "mwdata": [23] }
uint8(27)	{ "mwtype": "uint8", "mwsize": [1,1], "mwdata": [27]}

Numeric Types: Complex Numbers

• Complex numbers from MATLAB cannot be represented using JSON small notation.

• When representing complex numbers from MATLAB in JSON:

  • A property named mwcomplex is added to the JSON object, and it’s property value is set to true.

  • The property values for the mwdata property contain the real and imaginary parts represented side-by-side.

MATLAB Data Type	JSON Large Notation
a + bi	{ "mwtype": "double", "mwsize": [1,1], "mwcomplex": true, "mwdata": [a b] }
Example:
3 + 4i	{ "mwtype": "double", "mwsize": [1,1], "mwcomplex": true, "mwdata": [3,4] }

Characters

MATLAB Data Type	JSON Small Notation	JSON Large Notation
char	string	{ "mwtype": "char", "mwsize": [1,1], "mwdata": [string] }
Example:
'a'	"a"	{ "mwtype": "char", "mwsize": [1,1], "mwdata": ["a"] }
'hey, jude'	"hey, jude"	{ "mwtype": "char", "mwsize": [1,9], "mwdata": ["hey, jude"] }

Logical

MATLAB Data Type	JSON Small Notation	JSON Large Notation
logical	true | false	{ "mwtype": "logical", "mwsize": [1,1], "mwdata": [true | false] }
Example:
logical(1) or true	true	{ "mwtype": "logical", "mwsize": [1,1], "mwdata": [true] }
logical(0) or false	false	{ "mwtype": "logical", "mwsize": [1,1], "mwdata": [false] }

Cell Arrays

MATLAB Data Type	JSON Large Notation
cell	{ "mwtype": "cell", "mwsize": [<cell dimensions>], "mwdata": [<cell data>] }
Example:
{'Primes', [10 23 199],{false,true,'maybe'}}	{ "mwtype": "cell", "mwsize": [1,3], "mwdata": ["Primes", { "mwtype": "double", "mwsize": [1,3], "mwdata": [10,23,199] }, { "mwtype": "cell", "mwsize": [1,3], "mwdata": [false, true,"maybe"] } ] }

Structures

MATLAB Data Type	JSON Small Notation	JSON Large Notation
struct		{ "mwtype": "struct", "mwsize": [<struct dimensions>], "mwdata": [<struct data>] }
Example:
struct('name', 'John Smith', 'age', 15)	{ "name" : "John Smith", "age" : 15 }	{ "mwtype": "struct", "mwsize": [1,1], "mwdata": { "age": [ { "mwdata": [15], "mwsize": [1,1], "mwtype": "double" } ], "name": [ { "mwdata": ["John Smith"], "mwsize": [1,10], "mwtype": "char" } ] } }
x = struct('Name',{{'Casper','Ghost'}},... 'Age',{[14,17,18]},... 'Date', {736676});	No small representation.	{ "mwtype":"struct", "mwsize":[1,1], "mwdata":{ "Name": [{"mwdata": {'Casper','Ghost'}, "mwsize":[1,2], "mwtype":"string"}], "Age": [{"mwdata":[14,17,18], "mwsize":[1,3], "mwtype":"double"}], "Date": [{"mwdata":[736676], "mwsize":[1,1], "mwtype":"double"}]} }

Empty Arrays: []

• Empty arrays [] cannot be of type struct.

MATLAB Data Type	JSON Small Notation	JSON Large Notation
[]	[]	{ "mwtype": "double" | "single" "int8" | "uint8" | "int16" | "uint16" "int32" | "uint32" | "int64" | "uint64" "logical" | "char" | "cell" , "mwsize": [0,0], "mwdata": [ ] }

Multidimensional Arrays

Most multidimensional arrays from MATLAB cannot be represented using JSON small notation. The exceptions are: double, logical, and struct. Specify all data from multidimensional arrays in column-major order in the mwdata property of the JSON object. This ordering corresponds to the default memory layout in MATLAB.

Numeric Types: double, single, NaN, Inf, -Inf, Integers

In the JSON representation of multidimensional numeric arrays:

• The mwtype property can take any of the following values:

  "double" | "single" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64'

• The mwsize property is specified by enclosing the dimensions as a comma-separated list within [] .

MATLAB Data Type	JSON Small Notation	JSON Large Notation
[1,2,3;... 4,5,6]	[[1,2,3],[4,5,6]]	{ "mwtype": "double", "mwsize": [2,3], "mwdata": [1,4,2,5,3,6] }
[1, NaN, -Inf;... 2, 105, Inf]	[[1,{"mwdata": "NaN"},{"mwdata": "-Inf"}],[2,105,{"mwdata": "Inf"}]]	{ "mwtype": "double", "mwsize": [2,3], "mwdata": [1, 2, "NaN", 105, "-Inf", "Inf"] }
[ 1 2; 4 5; 7 8 ]	[[1, 2], [4, 5], [7, 8]]	{ "mwtype": "double", "mwsize": [3,2], "mwdata": [1,4,7,2,5,8] }
a(:,:,1) = 1 2 3 4 5 6 a(:,:,2) = 7 8 9 10 11 12	[[[1,7],[2,8]],[[3,9],[4,10]],[[5,11],[6,12]]]	{ "mwtype": "double", "mwsize": [3,2,2], "mwdata": [1,3,5,2,4,6,7,9,11,8,10,12] }

Below is an example of reading and writing multidimensional arrays in column-major order in JavaScript^®. The example uses a JavaScript file sub2ind.js to convert subscripts to linear indices.

Code:

 sub2ind.js

/*
 * Convert subscripts to linear indices
 *
 * Syntax:
 * 
 * linearIndex = sub2ind(dimensions, dim1sub, dim2sub, dim3sub, ...)
 * 
 * Example:
 * Call below will return the linear index of (0, 1) from a 2x3 array
 * 
 * sub2ind([2, 3], 0, 1)
 */
function sub2ind(dims) {
    var indices = Array.prototype.slice.call(arguments, 1);
 
    if(dims.length !== indices.length) {
        throw new Error("number of indices must match number of dimensions");
    }
    var size = 1;
    var index = 0;
    for(var i = 0; i < dims.length; i++) {
        index += indices[i] * size;
        size *= dims[i];
    }
      return index;
  }

 writeReadJsonExample.js

/*
 * First: Write a 5x5 magic square to JSON
 * This example uses sub2ind.js
 */
function write_json_example() {
    var data = 
        [[17, 24,  1,  8, 15],
         [23,  5,  7, 14, 16],
         [ 4,  6, 13, 20, 22],
         [10, 12, 19, 21,  3],
         [11, 18, 25,  2,  9]];

    var mwsize = [5, 5];
    var mwdata = []
    for(var r = 0; r < mwsize[0]; r++) {
        for(var c = 0; c < mwsize[1]; c++) {
            mwdata[sub2ind(mwsize, r, c)] = data[r][c];
        }
    }
    
    var json = JSON.stringify({ 'mwtype' : 'int8', 'mwsize' : mwsize, 'mwdata' : mwdata });
    return json;
}
/*
 * Second: Read 5x5 magic square
 * This example uses sub2ind.js
*/
function read_json_example() {
    var json = JSON.parse('{"mwtype":"int8","mwsize":[5,5],"mwdata":[17,23,4,10,11,24,5,6,12,18,1,7,13,19,25,8,14,20,21,2,15,16,22,3,9]}');
    var mwdata = json.mwdata;
    var mwsize = json.mwsize;
    
    var data = [];
    for(var r = 0; r < mwsize[0]; r++) {
        data[r] = [];
        for(var c = 0; c < mwsize[1]; c++) {
            data[r][c] = mwdata[sub2ind(mwsize, r, c)];
        }
    }
    
    return data;
}

Numeric Types: Complex Numbers

MATLAB Data Type	JSON Large Notation
[1 - 2i;... 3 + 7i]	{ "mwtype": "double", "mwsize": [2,1], "mwcomplex": true, "mwdata": [1, -2, 3, 7] }

Characters

In the JSON representation of multidimensional character arrays:

• The mwtype property must have a value of char .

• The mwdata property must be an array of JSON strings .

MATLAB Data Type	JSON Large Notation
['boston';... '123456']	{ "mwtype": "char", "mwsize": [3,4], "mwdata": ["b1o2s3t4o5n6"] }

Logical

In the JSON representation of multidimensional logical arrays:

• The mwtype property must have a value of logical .

• The mwdata property must contain only JSON true|false values.

MATLAB Data Type	JSON Small Notation	JSON Large Notation
[true,false;... true,false;... true,false]	[[[true,false],[true,false],[true,false]]]	{ "mwtype": "logical", "mwsize": [3,2], "mwdata": [true,true,true,false,false,false] }

Cell Arrays

In the JSON representation of multidimensional cell arrays:

• The mwtype property must have a value of cell .

• The mwdata property must be a JSON array that contains the values of the cells in their JSON representation.

MATLAB Data Type	JSON Large Notation
{ 'hercule', 18540, [33 1 50];... {'agatha',1920,true}, false, 1950 }	{ "mwtype": "cell", "mwsize": [2,3], "mwdata": ["hercule", {"mwtype": "cell", "mwsize": [1,3], "mwdata": ["agatha", 1920, true] }, 18540, false, {"mwtype": "double", "mwsize": [1,3], "mwdata": [33,1,50] },1950 ] }

Structures

In the JSON representation of multidimensional structure arrays:

• The mwdata is a JSON object containing property name-value pairs.

• The name in each property name-value pair matches a field in the structure array.

• The value in each property name-value pair is a JSON array containing values for that field for every element in the structure array. The elements of the JSON array must be in column-major order.

MATLAB Data Type	JSON Large Notation
struct( 'Name',{'Casper','Ghost';... 'Genie' ,'Wolf'},... 'Ages',{14,17;... 20,23} )	{ "mwtype": "struct", "mwsize": [2,2], "mwdata": {"Name": ["Casper", "Genie", "Ghost" , "Wolf"], "Ages": [14,20, 17,23] } }