5.4.3 JSON data encoding/decoding

JavaScript Object Notation, in short JSON, is a very common human readable and structured data format. GNU Octave supports encoding and decoding this format with the following two functions.

 
: JSON_txt = jsonencode (object)
: JSON_txt = jsonencode (…, "ConvertInfAndNaN", TF)
: JSON_txt = jsonencode (…, "PrettyPrint", TF)

Encode Octave data types into JSON text.

The input object is an Octave variable to encode.

The output JSON_txt is the JSON text that contains the result of encoding object.

If the value of the option "ConvertInfAndNaN" is true then NaN, NA, -Inf, and Inf values will be converted to "null" in the output. If it is false then they will remain as their original values. The default value for this option is true.

If the value of the option "PrettyPrint" is true, the output text will have indentations and line feeds. If it is false, the output will be condensed and written without whitespace. The default value for this option is false.

Programming Notes:

  • Complex numbers are not supported.
  • classdef objects are first converted to structs and then encoded.
  • To preserve escape characters (e.g., "\n"), use single-quoted strings.
  • Every character after the null character ("\0") in a double-quoted string will be dropped during encoding.
  • Encoding and decoding an array is not guaranteed to preserve the dimensions of the array. In particular, row vectors will be reshaped to column vectors.
  • Encoding and decoding is not guaranteed to preserve the Octave data type because JSON supports fewer data types than Octave. For example, if you encode an int8 and then decode it, you will get a double.

This table shows the conversions from Octave data types to JSON data types:

Octave data typeJSON data type
logical scalarBoolean
logical vectorArray of Boolean, reshaped to row vector
logical arraynested Array of Boolean
numeric scalarNumber
numeric vectorArray of Number, reshaped to row vector
numeric arraynested Array of Number
NaN, NA, Inf, -Inf
when "ConvertInfAndNaN" = true
"null"
NaN, NA, Inf, -Inf
when "ConvertInfAndNaN" = false
"NaN", "NaN", "Infinity", "-Infinity"
empty array"[]"
character vectorString
character arrayArray of String
empty character array""
cell scalarArray
cell vectorArray, reshaped to row vector
cell arrayArray, flattened to row vector
struct scalarObject
struct vectorArray of Object, reshaped to row vector
struct arraynested Array of Object
classdef objectObject

Examples:

jsonencode ([1, NaN; 3, 4])
⇒ [[1,null],[3,4]]

jsonencode ([1, NaN; 3, 4], "ConvertInfAndNaN", false)
⇒ [[1,NaN],[3,4]]

## Escape characters inside a single-quoted string
jsonencode ('\0\a\b\t\n\v\f\r')
⇒ "\\0\\a\\b\\t\\n\\v\\f\\r"

## Escape characters inside a double-quoted string
jsonencode ("\a\b\t\n\v\f\r")
⇒ "\u0007\b\t\n\u000B\f\r"

jsonencode ([true; false], "PrettyPrint", true)
⇒ ans = [
     true,
     false
   ]

jsonencode (['foo', 'bar'; 'foo', 'bar'])
⇒ ["foobar","foobar"]

jsonencode (struct ('a', Inf, 'b', [], 'c', struct ()))
⇒ {"a":null,"b":[],"c":{}}

jsonencode (struct ('structarray', struct ('a', {1; 3}, 'b', {2; 4})))
⇒ {"structarray":[{"a":1,"b":2},{"a":3,"b":4}]}

jsonencode ({'foo'; 'bar'; {'foo'; 'bar'}})
⇒ ["foo","bar",["foo","bar"]]

jsonencode (containers.Map({'foo'; 'bar'; 'baz'}, [1, 2, 3]))
⇒ {"bar":2,"baz":3,"foo":1}

See also: jsondecode.

 
: object = jsondecode (JSON_txt)
: object = jsondecode (…, "ReplacementStyle", rs)
: object = jsondecode (…, "Prefix", pfx)
: object = jsondecode (…, "makeValidName", TF)

Decode text that is formatted in JSON.

The input JSON_txt is a string that contains JSON text.

The output object is an Octave object that contains the result of decoding JSON_txt.

For more information about the options "ReplacementStyle" and "Prefix", see matlab.lang.makeValidName.

If the value of the option "makeValidName" is false then names will not be changed by matlab.lang.makeValidName and the "ReplacementStyle" and "Prefix" options will be ignored.

NOTE: Decoding and encoding JSON text is not guaranteed to reproduce the original text as some names may be changed by matlab.lang.makeValidName.

This table shows the conversions from JSON data types to Octave data types:

JSON data typeOctave data type
Booleanscalar logical
Numberscalar double
Stringvector of characters
Objectscalar struct (field names of the struct may be different from the keys of the JSON object due to matlab_lang_makeValidName
null, inside a numeric arrayNaN
null, inside a non-numeric arrayempty double array []
Array, of different data typescell array
Array, of Booleanslogical array
Array, of Numbersdouble array
Array, of Stringscell array of character vectors (cellstr)
Array of Objects, same field namesstruct array
Array of Objects, different field namescell array of scalar structs

Examples:

jsondecode ('[1, 2, null, 3]')
    ⇒ ans =

      1
      2
    NaN
      3

jsondecode ('["foo", "bar", ["foo", "bar"]]')
    ⇒ ans =
       {
         [1,1] = foo
         [2,1] = bar
         [3,1] =
         {
           [1,1] = foo
           [2,1] = bar
         }

       }

jsondecode ('{"nu#m#ber": 7, "s#tr#ing": "hi"}', ...
            'ReplacementStyle', 'delete')
    ⇒ scalar structure containing the fields:

         number = 7
         string = hi

jsondecode ('{"nu#m#ber": 7, "s#tr#ing": "hi"}', ...
            'makeValidName', false)
    ⇒ scalar structure containing the fields:

         nu#m#ber = 7
         s#tr#ing = hi

jsondecode ('{"1": "one", "2": "two"}', 'Prefix', 'm_')
    ⇒ scalar structure containing the fields:

         m_1 = one
         m_2 = two

See also: jsonencode, matlab.lang.makeValidName.