The JSON_SERIALIZE function takes a HASH, LIST, or structure variable and converts it into a JSON (JavaScript Object Notation) string.

This routine is written in the IDL language. Its source code can be found in the file json_serialize.pro in the lib subdirectory of the IDL distribution.

Tip: The JSON_SERIALIZE converts a LIST or HASH into raw JSON with no "pretty" printing. To output prettified JSON (with appropriate indenting and line breaks), you can bypass JSON_SERIALIZE and print out your LIST or HASH using Implied Print.

Examples

Convert a LIST of IDL values into a JSON string

mylist = LIST(!TRUE, !NULL, 42, 3.14, "Hello")
json = JSON_SERIALIZE(mylist)
PRINT, json

IDL prints:

[true,null,42,3.14,"Hello"]

Convert a HASH of key-value pairs into a JSON string

myhash = HASH("Planet", "Jupiter", "Index", 5, "Mass", 1.9d27, "Units", "kg")
json = JSON_SERIALIZE(myhash)
PRINT, json

IDL prints:

{"Planet":"Jupiter","Index":5,"Units":"kg","Mass":1.9e27}

Convert an IDL structure into a JSON string

struct = {PLANET: "Jupiter", INDEX: 5, MASS: 1.9d27, UNITS: "kg"}
json = JSON_SERIALIZE(struct)
PRINT, json

IDL prints:

{"PLANET":"Jupiter","INDEX":5,"MASS":1.9e27,"UNITS":"kg"}

Syntax

Result = JSON_SERIALIZE(Value, /LOWERCASE, PRECISION=value, /PRETTY)

Return Value

The result is a string containing the JSON string. If the input value is a LIST, then the JSON string will be encoded as a JSON array, with square brackets and comma-separated values. If the input value is a HASH, then the JSON string will be encoded as a JSON object, with curly braces and key-value pairs.

When converting IDL variables, the following rules are used:

  • Undefined variables (or !NULL) become "null".
  • Boolean variables are passed on as "true" or "false".
  • All bytes and integers are passed on unchanged. If these are converted back using JSON_PARSE, they will be type LONG64.
  • All floating-point numbers are passed on unchanged, although any trailing zeroes are removed. If these are converted back using JSON_PARSE, they will be type DOUBLE.
  • All strings are surrounded by double-quotes. The following special characters will be escaped: \\ (backslash), \" (double quote), \b (backspace 8b), \f (form feed 12b), \n (line feed 10b), \r (carriage return 13b), \t (tab 9b). Note that forward slash characters are not escaped - this allows URL's to still look normal in the resulting JSON. Also note that the string "!NULL" is a special case, and will be converted into the "null" value.
  • LIST values become JSON arrays, with each list element being converted using the above rules.
  • Structure tagname-value pairs become JSON objects, with each value being converted using the above rules. You can use the LOWERCASE keyword to change the tagnames to lowercase.
  • HASH key-value pairs become JSON objects, with each value being converted using the above rules.

Note: Since the HASH stores its key-value pairs in an arbitrary order, the key-value pairs in the resulting JSON string may be in a different order than the order in which the keys were added to the hash.

Arguments

Value

Value must be a HASH, LIST, or structure variable.

Keywords

LOWERCASE

By default, when serializing an IDL structure, all of the structure tag names are in uppercase within the resulting JSON string. Set the LOWERCASE keyword to use lowercase for the structure tag names.

PRECISION

Set the PRECISION keyword to a number between 1 and 17 to set the number of digits to output for floating-point numbers. By default, the precision is 8 digits for single precision and 17 digits for double precision. A smaller precision will result in a smaller JSON string but may result in a loss of precision when the numbers are converted back.

Note: Unnecessary trailing zeroes are automatically removed from all numbers, regardless of the precision setting.

PRETTY

Set this keyword to output the JSON in a "pretty" format with line breaks and indentation using spaces. The output will still be a scalar string, with embedded line feed characters.

Resources and References

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write, and for machines to parse and generate. JSON was designed as an alternative to XML, and is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. Further details can be found at http://www.json.org.

Version History

8.2

Introduced
8.4

All byte values are now encoded as integers (instead of true/false).

Added LOWERCASE keyword.

Boolean variables are encoded as true/false.

8.8.3

 Added PRECISION keyword.
8.9 Added PRETTY keyword.

See Also

JSON_PARSE, HASH, LIST, HttpRequest