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
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] } |
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"] } { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"NaN"}] } |
Inf | {"mwdata":"Inf"} | { "mwtype": "double", "mwsize": [1,1], "mwdata": ["Inf"] } { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"Inf"}] } |
-Inf | {"mwdata":"-Inf"} | { "mwtype": "double", "mwsize": [1,1], "mwdata": ["-Inf"] } { "mwtype": "double", "mwsize": [1,1], "mwdata": [{"mwdata":"-Inf"}] } |
[] empty double | [] | { "mwtype": "double", "mwsize": [0,0], "mwdata": [ ] } |
Integer types from MATLAB cannot be represented using JSON small notation.
MATLAB Data Type | JSON Large Notation |
---|---|
| { "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]} |
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] } |
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"] } |
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] } |
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"] } ] } |
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 []
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": [ ] } |
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.
double
, single
, NaN
, Inf
, -Inf
, IntegersIn 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:
MATLAB Data Type | JSON Large Notation |
---|---|
[1 - 2i;... 3 + 7i] | { "mwtype": "double", "mwsize": [2,1], "mwcomplex": true, "mwdata": [1, -2, 3, 7] } |
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"] } |
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] } |
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 ] } |
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] } } |