serializeJSON

Converts a ColdFusion value into a JSON (JavaScript Object Notation) string.

serializeJSON(data[, queryFormat[, useSecureJSONPrefix[, useCustomSerializer]]]) → returns string

Member Function Syntax

someVar.toJSON([queryFormat[, useSecureJSONPrefix[, useCustomSerializer]]])

CF8+

Lucee

BL 1.0.0+

Argument Reference

data any
Required

A serializable ColdFusion data value

queryFormat any
Default: `row`

This specifies how to serialize ColdFusion queries. Prior to CF 11+, this would only accept Boolean values. If it is a Boolean, the false value is equivalent to 'row' and true is 'column'.

Values:

row
column
struct
false
true

useSecureJSONPrefix boolean
Default: `false`

CF 11+ When Prefix Serialized JSON is enabled in the ColdFusion Administrator, then by default this function inserts the secure JSON prefix at the beginning of the JSON.

useCustomSerializer boolean
Default: `true`

CF 11+ Use custom serializer if defined. See: https://helpx.adobe.com/coldfusion/developing-applications/changes-in-coldfusion/restful-web-services-in-coldfusion.html

Compatibility

ColdFusion:

Version 8+ CF11+ Added useSecureJSONPrefix and useCustomSerializer arguments. Changed queryFormat (formerly known as serializeQueryByColumns) from a boolean type to also allowing strings, adding the 'struct' functionality in the process. The default for queryFormat can be set using the newly added Application.cfc setting this.serialization.serializeQueryAs. Also added Application.cfc settings this.serialization.preserveCaseForStructKey and this.serialization.preserveCaseForQueryColumn. CF2016+ Added member syntax.

Lucee:

Member syntax added for Lucee5.3.8+

BoxLang:

Version 1.0.0+ Transpiled to JSONSerialize in BoxLang.

Links more information about serializeJSON

JSON Overview - Overview of the JSON spec.
- A CFC that provides JSON serialization and deserialization. It is written in CFML so it works on versions prior to CF8. It may be useful if you are experiencing automatic type conversion issues with the built-in serializeJSON function.

Examples
Sample code invoking the serializeJSON function

Serialize a Struct

Serialize a CF Struct into a JSON representation

person = {name="Pete Freitag", company="Foundeo"};
writeOutput( serializeJSON(person) );

Expected Result: {"COMPANY":"Foundeo","NAME":"Pete Freitag"}

Serialize a Struct with Member Syntax

Serialize a CF Struct into a JSON representation using toJSON

person = {name="Pete Freitag", company="Foundeo"};
writeOutput( person.toJSON() );

Expected Result: {"COMPANY":"Foundeo","NAME":"Pete Freitag"}

Lower Case Keys

Same as above but they variable names are case-sensitive by quoting them.

person = {"name"="Pete Freitag", "company"="Foundeo"};
writeOutput( serializeJSON(person) );

Expected Result: {"company":"Foundeo","name":"Pete Freitag"}

ACF Possible Issues

Adobe ColdFusion may incorrectly serializes some strings if they can be automatically converted into other types, like numbers or booleans. One workaround is to use a CFC with cfproperty to specify types. Another workaround is to prepend chr(2) to the value and it will be forced to a string, however that is an unofficial / undocumented workaround.

person = { "phone"="123456789", "firstname"="no","lastname"="yes" };
writeOutput( serializeJson(person) );

Expected Result: {"phone":123456789,"firstname":false,"lastname":true}

Using setMetadata to force types

As of CF 2016.0.2+ you can call setMetadata() as a member function on a struct to force a type

myStruct = {"zip"="00123"};
myStruct.setMetadata( { "zip": "string" } );
writeOutput(serializeJSON(myStruct));

Expected Result: {"zip":"00123"}

Serialize a Query as an array of structs

Serialize a CF Query into a JSON representation of an array of structs

news = queryNew("id,title",
    "integer,varchar",
    [ {"id":1,"title":"Dewey defeats Truman"}, {"id":2,"title":"Man walks on Moon"} ]);
writeOutput(serializeJSON(news, "struct"));

Expected Result: [{"ID":1,"TITLE":"Dewey defeats Truman"},{"ID":2,"TITLE":"Man walks on Moon"}]

© 2012–present Foundeo, Inc. and the CFDocs contributors.
Licensed under the MIT License.
ColdFusion is a trademark of Adobe Systems Incorporated.
https://cfdocs.org/serializejson