DeserializeJSON

Last updated on Apr 27, 2021 05:38:57 AM GMT | Also Applies to ColdFusion

Description

Converts a JSON (JavaScript Object Notation) string data representation into CFML data, such as a CFML structure or array.

Returns

The data value in ColdFusion format: a structure, array, query, or simple value.

Syntax

DeserializeJSON(JSONVar[, strictMapping, useCustomSerializer])

History

ColdFusion 11: Added the attribute, useCustomSerializer.

ColdFusion 8: Added this function

Parameters

Parameter	Description
JSONVar	A valid JSON string expression.
strictMapping	A Boolean value that specifies whether to convert the JSON strictly, as follows: true: (Default) Convert the JSON string to ColdFusion data types that correspond directly to the JSON data types. false: Determine if the JSON string contains representations of ColdFusion queries, and if so, convert them to queries.
useCustomSerializer	true/false. Whether to use the customSerializer or not. The default value is true. The custom serializer will always be used for deserialization. If false, the JSON deserialization will be done using the default ColdFusion behavior.

Parameter

Description

JSONVar

A valid JSON string expression.

strictMapping

A Boolean value that specifies whether to convert the JSON strictly, as follows:

true: (Default) Convert the JSON string to ColdFusion data types that correspond directly to the JSON data types.
false: Determine if the JSON string contains representations of ColdFusion queries, and if so, convert them to queries.

useCustomSerializer

true/false. Whether to use the customSerializer or not. The default value is true. The custom serializer will always be used for deserialization. If false, the JSON deserialization will be done using the default ColdFusion behavior.

Usage

This function is useful any time a ColdFusion page receives data as JSON strings. It is useful in ColdFusion applications that use Ajax to represent data on the client browser, and lets you consume JSON format data from the client-side Ajax JavaScript. You can also use it on pages that get data from services that supply data as JavaScript function calls with JSON parameters. The DeserializeJSON function converts each JSON data type directly into the equivalent ColdFusion data type, as follows:

If the strictMapping parameter is true (the default), all JSON objects become CFML structures.
If the strictMapping parameter is false, ColdFusion determines if JSON objects represent queries and, if so, converts them to ColdFusion query object. All other JSON objects become ColdFusion structures. The DeserializeJSON function recognizes a JSON structure as a query and converts it properly if the structure uses either of the two query representation formats described in the SerializeJSON reference.
JSON Arrays, Strings, and Numbers become ColdFusion arrays, strings, and numbers.
Since ColdFfusion 10, JSON null values become undefined.
JSON string representations of a dates and times remain strings, but ColdFusion date/time handling code can recognize them as representing dates and times.

Example

The following example parses JSON data and converts the JSON data into a ColdFusion structure.

<cfscript>
  record=deserializeJSON(
'{
"firstname": "John",
"lastname": "Smith",
"age": "36",
"address":{
      "number":"12345",
      "street":"my_street",
      "city":"any city"
}
}'
);
  writeOutput(record.firstname & " ");
  writeOutput(record.lastname & " ");
  writeOutput(record.address.number & " ");
  writeOutput(record.address.street & " ");
</cfscript>

Expected output:

John Smith 12345 my_street