JSON Representation of MATLAB Data Types - MATLAB & Simulink (original) (raw)

JavaScript Object Notation or JSON is a text-based data interchange format that can be used across programming languages. Since JSON is independent of programming language, you can represent MATLAB® data types in JSON. 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 notation formats: small and large.

• Small notation 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. You can use small notation to represent scalar and multidimensionaldouble and logical data types, scalar and 1-by-N char data type and scalarstruct.
• Large notation provides a generic representation of MATLAB data types in JSON. The large format uses the JSONobject 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 uses large notation by default.

A JSON object in the large notation contains the following property name-value pairs.

MATLAB Compiler SDK™ provides the following utility functions for data conversion between MATLAB and JSON.

The RESTful API supports the following MATLAB data types.

Numeric Types: double, single and Integers

• The mwdata property must be a JSON array of JSON numbers.
• The mwtype property can be any ofdouble, single,int8, uint8,int16, uint16,int32, uint32,int64, uint64.
• You cannot represent scalar or multidimensionalsingle and integer types using JSON small notation.
• Starting in R2020a, int64 and uint64 numbers maintain precision and range in their JSON representation as they are not converted to double.

Scalar Numeric Types: double, single and Integers

• The mwdata property must be a JSON array containing one JSON number representing the MATLAB scalar value.
• The mwsize property must be a JSON array containing 1,1.

JSON Representation of Scalar Numeric Types: double,single and Integers

Multidimensional Numeric Types: double, single and Integers

• The mwdata property must be a JSON array containing data from multidimensional arrays in column-major order. This ordering corresponds to the default memory layout in MATLAB.
• You must represent double arrays, except N-by-1double arrays, with nested JSON arrays when using small notation
• You cannot represent multidimensionalsingle and integer types using JSON small notation.

Numeric Types: NaN, Inf, and -Inf

• NaN, Inf, and-Inf are numeric types whose underlying MATLAB class can be either double orsingle only. You cannot representNaN, Inf, and-Inf as an integer type in MATLAB.

Numeric Types: Complex Numbers

• The mwdata property values must contain the real and imaginary parts of the complex number represented side by side.
• You must set an additional property mwcomplex with the value of true.
• The mwtype property can be any ofdouble, single,int8, uint8,int16, uint16,int32, uint32,int64, uint64.
• You cannot represent complex numbers using small notation.

JSON Representation of Complex Numbers

Character Array

• The mwdata property must be an array of JSONstrings.
• The mwtype property must have the value ofchar.
• You can represent scalar characters and 1-by-N character arrays in small notation.
• You cannot represent multidimensional character arrays in large notation.

JSON Representation of char

Logical

• The mwdata property must contain only JSONtrue or false boolean values. For multidimensional logical data, represent the values in column-major order.
• The mwtype property must have the value oflogical.
• In the small notation, you must represent multidimensionallogical arrays with nested JSON arrays.

JSON Representation of logical

Cell Array

• The mwdata property must be a JSONarray that contains the values of the cells in their JSON representation.
• The mwtype property must have the value ofcell.
• You cannot represent cell arrays using small notation.

  MATLAB Data Type	JSON Large Notation
  cell	{ "mwdata": [], "mwsize": [], "mwtype": "cell" }

• Although you must represent cell arrays using large notation only, if the data type of a cell element supports small notation, you can represent that element in small notation when encoding thecell array in JSON.
  The following table shows an example.

  MATLAB Data: cell Array	JSON Large Notation with somecell elements in Small Notation	JSON Large Notation with all cell elements in Large Notation
  {'Primes',[10 23 199],{false,true,'maybe'}}	{ "mwdata": ["Primes", [[10, 23, 199]], { "mwdata": [false, true, "maybe"], "mwsize": [1, 3], "mwtype": "cell" } ], "mwsize": [1, 3], "mwtype": "cell" }	{ "mwdata": [{ "mwdata": ["Primes"], "mwsize": [1, 6], "mwtype": "char" },{ "mwdata": [10, 23, 199], "mwsize": [1, 3], "mwtype": "double" },{ "mwdata": [{ "mwdata": [false], "mwsize": [1, 1], "mwtype": "logical" },{ "mwdata": [true], "mwsize": [1, 1], "mwtype": "logical" },{ "mwdata": ["maybe"], "mwsize": [1, 5], "mwtype": "char" }], "mwsize": [1, 3], "mwtype": "cell" }], "mwsize": [1, 3], "mwtype": "cell" }

• For more information on MATLABcell data type, see cell (MATLAB).

Structure Array

• The mwdata property must be a JSON object that contains name-value pairs, where the name matches a field in thestruct and value is a JSON array that represents the data in the field.
• The mwtype property must have the value ofstruct.
• Although you must represent multidimensional struct arrays using JSON large notation, if the data type of astruct value supports small notation, you can represent that value in small notation when encoding thestruct in JSON.
• You can represent only a scalar struct in small notation.
  JSON Representation of struct arrays

  MATLAB Data Type	JSON Small Notation (valid only for a scalar struct)	JSON Large Notation
  struct	JSON object	{ "mwdata": {} "mwsize": [], "mwtype": "struct" }

• MATLAB Data: Scalar Structure Array	JSON Small Notation	JSON Large Notation
  struct('name','John Smith','age',15)	{ "name" : "John Smith", "age" : 15 }	{ "mwdata": { "age": [{ "mwdata": [15], "mwsize": [1, 1], "mwtype": "double" }], "name": [{ "mwdata": ["John Smith"], "mwsize": [1, 10], "mwtype": "char" }] }, "mwsize": [1, 1], "mwtype": "struct" }

• Although you can represent 1-by-1 struct arrays in small notation, if the data type of a struct value does not support small notation, you must represent that value in large notation when encoding the struct in JSON.

  MATLAB Data: 1-by-1 Structure Array	JSON Small Notation with somestruct values in Large Notation	JSON Large Notation with allstruct values in Large Notation
  struct('Name',{{'Casper','Ghost'}},... 'Age',{[14,17,18]},... 'Date', {736676})	{ "Age": [[14, 17, 18]], "Date": 736676, "Name": { "mwdata": ["Casper", "Ghost"], "mwsize": [1, 2], "mwtype": "cell" } }	{ "mwdata": { "Age": [{ "mwdata": [14, 17, 18], "mwsize": [1, 3], "mwtype": "double" }], "Date": [{ "mwdata": [736676], "mwsize": [1, 1], "mwtype": "double" }], "Name": [{ "mwdata": [{ "mwdata": ["Casper"], "mwsize": [1, 6], "mwtype": "char" }, { "mwdata": ["Ghost"], "mwsize": [1, 5], "mwtype": "char" }], "mwsize": [1, 2], "mwtype": "cell" }] }, "mwsize": [1, 1], "mwtype": "struct" }

• Although you must represent multidimensional struct arrays using JSON large notation, if the data type of astruct value supports small notation, you can represent that value in small notation when encoding thestruct in JSON.

  MATLAB Data: Multidimensional Structure Array	JSON Large Notation with somestruct values in Small Notation	JSON Large Notation with allstruct values in Large Notation
  struct( 'Name',{'Casper','Ghost';... 'Genie' ,'Wolf'},... 'Ages',{14,17;... 20,23} )	{ "mwdata":{ "Ages":[14,20,17,23], "Name":["Casper","Genie","Ghost","Wolf"] }, "mwsize":[2,2], "mwtype":"struct" }	{ "mwdata":{ "Ages":[{ "mwdata":[14], "mwsize":[1,1], "mwtype":"double" },{ "mwdata":[20], "mwsize":[1,1], "mwtype":"double" },{ "mwdata":[17], "mwsize":[1,1], "mwtype":"double" },{ "mwdata":[23], "mwsize":[1,1], "mwtype":"double" }], "Name":[{ "mwdata":["Casper"], "mwsize":[1,6], "mwtype":"char" },{ "mwdata":["Genie"], "mwsize":[1,5], "mwtype":"char" },{ "mwdata":["Ghost"], "mwsize":[1,5], "mwtype":"char" },{ "mwdata":["Wolf"], "mwsize":[1,4], "mwtype":"char" }] }, "mwsize":[2,2], "mwtype":"struct" }

• For more information on MATLABstruct data type, see struct (MATLAB).

String Array

• The mwdata property must be a JSON array containing strings in column-major order.
• The mwtype property must have the value ofstring.
• You cannot represent string arrays using small JSON notation.
  JSON Representation of string arrays

  MATLAB Data Type	JSON Large Notation
  string	{ "mwdata": [JSON string], "mwsize": [], "mwtype": "string" }
  MATLAB Data: Scalar, Single-dimensional, Multidimensional, and missing (MATLAB) string Arrays	JSON Large Notation
  ------------------------------------------------------------------------------------------------------------------------------	-----------------------------------------------------------------------------------------------
  "abc"	{ "mwdata": ["abc"], "mwsize": [1, 1], "mwtype": "string" }
  ["abc"]	{ "mwdata": ["abc"], "mwsize": [1, 1], "mwtype": "string" }
  ["abc" "de"]	{ "mwdata": ["abc", "de"], "mwsize": [1, 2], "mwtype": "string" }
  ["abc" "de"; "fg" "hi"]	{ "mwdata": ["abc", "fg", "de", "hi"], "mwsize": [2, 2], "mwtype": "string" }
  string(missing)	{ "mwdata": [{"mwdata": "missing"}], "mwsize": [1, 1], "mwtype": "string" }

• For more information on MATLABstring data type, see string, " " (MATLAB).

Enumeration

• The mwdata property must be a JSON array of strings denoting the enumeration members.
• The mwtype property must be set to the class of the enumerations in the array.
• You cannot represent an enumeration using small JSON notation.
  JSON Representation of enumeration

  MATLAB Data Type	JSON Large Notation
  enumeration	{ "mwdata": [JSON string], "mwsize": [], "mwtype": "" }
  The following table shows examples of JSON representation of anenumeration.
  Use the following enumeration for the examples. For more information, seeDefine Enumeration Classes (MATLAB).
  classdef Colors
  enumeration

  Black Blue Red  

  end
  end

  MATLAB Data: Object of Enumeration Class	JSON Large Notation
  b = Colors.Black	{ "mwdata": ["Black"], "mwsize": [1, 1], "mwtype": "Colors" }
  b = [Colors.Black Colors.Blue]	{ "mwdata": ["Black", "Blue"], "mwsize": [1, 2], "mwtype": "Colors" }

• For more information on MATLABenumeration data type, see enumeration (MATLAB).

Datetime Array

• The mwdata property must be a JSON object containing name-value pairs for TimeStamp and optionally forLowOrderTimeStamp. Values forTimeStamp and LowOrderTimeStamp are JSON representation of the double data type.
  • The TimeStamp property values represent the POSIX time in milliseconds elapsed since 00:00:00 1-Jan-1970 UTC (Coordinated Universal Time).
  • The LowOrderTimeStamp property values represent additional resolution in the timestamp. Use this property to maintain precision past milliseconds.
  • Although you must represent datetime arrays using large notation only, since TimeStamp and LowOrderTimeStamp represent values of thedouble data type which supports small notation, you can represent TimeStamp andLowOrderTimeStamp using small notation when encoding datetime arrays in JSON.
• The mwmetadata property must be a JSON object containing name-value pairs for TimeZone andFormat. Values for TimeZone andFormat are JSON representation of thechar data type.
  • The values of the TimeZone andFormat properties contain metadata necessary for recreating the datetime values with timezones in MATLAB in their original display format. This metadata is necessary because the numeric values contained in theTimeStamp andLowOrderTimeStamp arrays are calculated with respect to UTC.
  • You can specify TimeZone andFormat properties forNaT and Inf datetime array values.
  • Although you must represent datetime arrays using large notation only, since TimeZone andFormat represent values of thechar data type which supports small notation, you can represent TimeZone andFormat using small notation when encodingdatetime arrays in JSON.
  • The value for TimeZone can be empty.
  • The default value for Format depends on your system locale. For more information, see Default datetime Format (MATLAB).
• The mwtype property must have the value ofdatetime.
• You cannot represent datetime arrays using small JSON notation.
  JSON Representation of datetime arrays

  MATLAB Data Type	JSON Large Notation
  datetime	{ "mwdata": { "LowOrderTimeStamp": "TimeStamp": }, "mwmetadata": { "TimeZone": , "Format": }, "mwsize": [], "mwtype": "datetime" }
  MATLAB Data: Scalar datetime Array	JSON Large Notation withmwdata andmwmetadata in Small Notation
  ----------------------------------	-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  datetime(2015, 3, 24);	{ "mwdata": { "TimeStamp": 1.4271552E+12 }, "mwmetadata": { "Format": "dd-MMM-uuuu", "TimeZone": "" }, "mwsize": [1, 1], "mwtype": "datetime" }
  The following table shows JSON representation for adatetime row vector. SinceLowOrderTimeStamp and TimeStamp contain double values, you need to use nested JSON arrays when representing multidimensional (except N-by-1) arrays ofLowOrderTimeStamp and TimeStamp in small notation.
  MATLAB Data: datetime Row Vector	JSON Large Notation withmwdata andmwmetadata in Small Notation
  --------------------------------------------------------------------------	-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  datetime(2018,1,8,10,... 11,12,(1:5)+(1:5)*1e-6,... 'TimeZone','local');	{ "mwdata": { "LowOrderTimeStamp": [[9.9999999991773336E-7, 1.9999999998354667E-6, 2.9999999999752447E-6, 3.9999999996709334E-6, 4.9999999998107114E-6]], "TimeStamp": [[1.515424272001E+12, 1.515424272002E+12, 1.515424272003E+12, 1.515424272004E+12, 1.515424272005E+12]], }, "mwmetadata": { "Format":"dd-MMM-uuuu HH:mm:ss", "TimeZone": "America\/New_York", }, "mwsize": [1, 5], "mwtype": "datetime" }
  MATLAB Data: datetime Column Vector	JSON Large Notation withmwdata andmwmetadata in Small Notation
  ---------------------------------------------------------------------------	---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  datetime(2018,1,8,10,... 11,12,(1:5)+(1:5)*1e-6,... 'TimeZone','local')';	{ "mwdata": { "LowOrderTimeStamp": [9.9999999991773336E-7, 1.9999999998354667E-6, 2.9999999999752447E-6, 3.9999999996709334E-6, 4.9999999998107114E-6], "TimeStamp": [1.515424272001E+12, 1.515424272002E+12, 1.515424272003E+12, 1.515424272004E+12, 1.515424272005E+12], }, "mwmetadata": { "Format":"dd-MMM-uuuu HH:mm:ss", "TimeZone": "America\/New_York", }, "mwsize": [5, 1], "mwtype": "datetime" }
  MATLAB Data: NaT andInf datetime Array	JSON Large Notation withmwdata andmwmetadata in Small Notation
  --------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  NaT	{ "mwdata": { "TimeStamp": { "mwdata": "NaN" } }, "mwmetadata": { "Format": "dd-MMM-uuuu HH:mm:ss", "TimeZone": "" }, "mwsize": [1, 1], "mwtype": "datetime" }
  datetime(inf,inf,inf)	{ "mwdata": { "TimeStamp": { "mwdata": "Inf" } }, "mwmetadata": { "Format": "dd-MMM-uuuu HH:mm:ss", "TimeZone": "" }, "mwsize": [1, 1], "mwtype": "datetime" }

• For more information on MATLABdatetime data type, see datetime (MATLAB).

Empty Array: []

• Empty arrays [] cannot be of typestruct.

See Also

Topics

• RESTful API for MATLAB Function Execution
• Fundamental MATLAB Classes (MATLAB)

External Websites

• JSON RFC