Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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 NameProperty 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 NamePurpose
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

MATLAB Data TypeJSON Small NotationJSON Large Notation
doublenumber
{
   "mwtype": "double",
   "mwsize": [1,1],
   "mwdata": [number]
}
singleNo 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]
}
4242
{
   "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 TypeJSON Small NotationJSON 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 TypeJSON 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 TypeJSON 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 TypeJSON Small NotationJSON Large Notation
charstring
{
   "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 TypeJSON Small NotationJSON Large Notation
logicaltrue | false
{
   "mwtype": "logical",
   "mwsize": [1,1],
   "mwdata": [true | false]
}
Example:  
logical(1) or truetrue
{
   "mwtype": "logical",
   "mwsize": [1,1],
   "mwdata": [true]
}
logical(0) or falsefalse
{
   "mwtype": "logical",
   "mwsize": [1,1],
   "mwdata": [false]
}

Cell Arrays

MATLAB Data TypeJSON 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 TypeJSON Small NotationJSON 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 TypeJSON Small NotationJSON 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 TypeJSON Small NotationJSON 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

 writeReadJsonExample.js

Numeric Types: Complex Numbers

MATLAB Data TypeJSON 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 TypeJSON 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 TypeJSON Small NotationJSON 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 TypeJSON 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 TypeJSON 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]
             }
}