JSON

Powerful JSON serialization and deserialization with automatic class conversion and custom formatting

BoxLang provides comprehensive JSON (JavaScript Object Notation) support with automatic serialization of BoxLang data types, including classes, queries, arrays, structs, and more. The JSON engine is built on Jackson Jr and includes custom serializers for BoxLang-specific types.

Built on Jackson Jr: BoxLang uses the high-performance Jackson Jr library with custom serializers and deserializers for BoxLang types. This ensures fast, reliable JSON processing with full control over the serialization format.

📋 Table of Contents

💻 JSON in Code

Let's explore JSON operations with practical examples:

// Create complex data structure
user = {
    id: 1,
    name: "Alice Johnson",
    email: "[email protected]",
    active: true,
    roles: [ "admin", "developer" ],
    metadata: {
        lastLogin: now(),
        preferences: { theme: "dark", language: "en" }
    }
};

// Serialize to JSON
json = user.toJSON();
println( json );

// Pretty print for readability
prettyJson = jsonSerialize( user, pretty: true );
println( prettyJson );

// Deserialize back to BoxLang data
restored = json.fromJSON();
println( "Name: " & restored.name );

// Validate JSON
if ( isJSON( json ) ) {
    println( "Valid JSON!" );
}

// List to JSON
tags = "programming,boxlang,json,tutorial";
jsonTags = tags.listToJSON();
println( jsonTags ); // ["programming","boxlang","json","tutorial"]

📚 JSON Built-In Functions (BIFs)

BoxLang provides JSON BIFs that can be called as functions or member methods on compatible types.

Core JSON Functions

Function

Purpose

Member Method Available

jsonSerialize()

Convert data to JSON string

toJSON() on most types

jsonDeserialize()

Parse JSON string to data

fromJSON() on strings

isJSON()

Validate JSON string

jsonPrettify()

Format JSON for readability

jsonPrettify() on strings

Member Method Support

The toJSON() member method is available on:

✅ Structs - myStruct.toJSON()
✅ Arrays - myArray.toJSON()
✅ Queries - myQuery.toJSON()
✅ Classes - myClass.toJSON() (with automatic property serialization)
✅ Numbers - 123.toJSON()
✅ Booleans - true.toJSON()
✅ Strings - "text".listToJSON() (converts list to JSON array)

The fromJSON() member method is available on:

✅ Strings - jsonString.fromJSON()

📤 JSON Serialization (jsonSerialize / toJSON)

Convert any BoxLang data to JSON format using jsonSerialize() or the toJSON() member method.

Basic Serialization

// Function syntax
person = { name: "Luis Majano", company: "Ortus Solutions", year: 2006 };
json = jsonSerialize( person );

// Member method syntax (preferred)
json = person.toJSON();

// Both produce: {"name":"Luis Majano","company":"Ortus Solutions","year":2006}

Supported Data Types

BoxLang automatically serializes all native types:

// Simple values
jsonSerialize( 42 );                    // "42"
jsonSerialize( true );                  // "true"
jsonSerialize( "Hello" );               // '"Hello"'

// Complex types
jsonSerialize( [ 1, 2, 3 ] );          // "[1,2,3]"
jsonSerialize( { a: 1, b: 2 } );       // '{"a":1,"b":2}'

// Dates (ISO 8601 format)
jsonSerialize( now() );                // "2025-12-09T14:30:00Z"

// Queries (see Query Serialization section)
qry = queryNew( "id,name", "integer,varchar", [ { id: 1, name: "Test" } ] );
jsonSerialize( qry );                  // Array of structs by default

🎨 Pretty Printing

Format JSON with indentation for readability:

data = {
    name: "John Doe",
    age: 30,
    address: {
        street: "123 Main St",
        city: "Anytown",
        country: "USA"
    },
    hobbies: [ "reading", "cycling", "photography" ]
};

// Compact (default)
compactJson = data.toJSON();
// {"name":"John Doe","age":30,"address":{...}}

// Pretty formatted
prettyJson = jsonSerialize( data, pretty: true );
/* Output:
{
  "name" : "John Doe",
  "age" : 30,
  "address" : {
    "street" : "123 Main St",
    "city" : "Anytown",
    "country" : "USA"
  },
  "hobbies" : [ "reading", "cycling", "photography" ]
}
*/

// Great for configuration files
writeFile( "config.json", appConfig.toJSON( pretty: true ) );

// Or use jsonPrettify on existing JSON
uglyJson = '{"a":1,"b":{"c":2}}';
prettyJson = uglyJson.jsonPrettify();

🔑 Key Casing Preservation

BoxLang preserves the exact casing of struct keys in JSON:

// Case-sensitive keys (quoted)
person = {
    "firstName": "Luis",
    "lastName": "Majano",
    "company": "Ortus Solutions"
};
person.toJSON();
// {"firstName":"Luis","lastName":"Majano","company":"Ortus Solutions"}

// Case-insensitive keys (unquoted) - stored uppercase
person = {
    firstName: "Luis",
    lastName: "Majano",
    company: "Ortus Solutions"
};
person.toJSON();
// {"FIRSTNAME":"Luis","LASTNAME":"Majano","COMPANY":"Ortus Solutions"}

Best Practice: Always quote struct keys if you need exact casing in JSON output, especially for REST APIs and JavaScript interoperability.

📊 Query Serialization

Queries can be serialized in three different formats using the queryFormat argument:

users = queryNew(
    "id,name,email",
    "integer,varchar,varchar",
    [
        { id: 1, name: "Alice", email: "[email protected]" },
        { id: 2, name: "Bob", email: "[email protected]" }
    ]
);

// Format: "struct" (default) - Array of structs
jsonSerialize( users, queryFormat: "struct" );
/* [
    {"id":1,"name":"Alice","email":"[email protected]"},
    {"id":2,"name":"Bob","email":"[email protected]"}
] */

// Format: "row" or "false" - Columns and row data arrays
jsonSerialize( users, queryFormat: "row" );
/* {
    "columns": ["id","name","email"],
    "data": [
        [1,"Alice","[email protected]"],
        [2,"Bob","[email protected]"]
    ]
} */

// Format: "column" or "true" - Columns and column data
jsonSerialize( users, queryFormat: "column" );
/* {
    "rowCount": 2,
    "columns": ["id","name","email"],
    "data": {
        "id": [1,2],
        "name": ["Alice","Bob"],
        "email": ["[email protected]","[email protected]"]
    }
} */

// Member method syntax
json = users.toJSON( queryFormat: "struct" );

Default Format: Queries serialize as arrays of structs (queryFormat="struct") when no format is specified. This is the most common format for REST APIs.

🎯 Class Serialization (The Magic!)

BoxLang makes it incredibly easy to serialize classes to JSON with automatic property introspection. The BoxClassSerializer intelligently converts class instances to JSON by examining their properties and respecting serialization annotations.

Automatic Property Serialization

/**
 * User class with automatic JSON serialization
 */
class User {
    property name="id" type="numeric";
    property name="username" type="string";
    property name="email" type="string";
    property name="createdDate" type="date";
    property name="roles" type="array";

    function init( id, username, email ) {
        variables.id = arguments.id;
        variables.username = arguments.username;
        variables.email = arguments.email;
        variables.createdDate = now();
        variables.roles = [ "user" ];
        return this;
    }
}

// Create instance
user = new User( 1, "alice", "[email protected]" );

// Serialize to JSON - automatically includes all properties!
json = user.toJSON();
/* {
    "id": 1,
    "username": "alice",
    "email": "[email protected]",
    "createdDate": "2025-12-09T14:30:00Z",
    "roles": ["user"]
} */

🔒 Controlling Serialization with Annotations

Use annotations to control what gets serialized:

/**
 * User class with serialization control
 */
@serializable( true )
@jsonExclude( "createdBy,modifiedBy" )
class User {
    property name="id" type="numeric";
    property name="username" type="string";
    property name="email" type="string";

    // Exclude sensitive data
    @jsonExclude( true )
    property name="password" type="string";

    @serializable( false )
    property name="passwordHash" type="string";

    // Exclude audit fields via class annotation
    property name="createdBy" type="string";
    property name="modifiedBy" type="string";

    // This will be included
    property name="active" type="boolean";
}

user = new User();
user.id = 1;
user.username = "alice";
user.email = "[email protected]";
user.password = "secret123";        // Won't be serialized
user.passwordHash = "hashed...";     // Won't be serialized
user.createdBy = "admin";            // Won't be serialized
user.active = true;

json = user.toJSON();
/* {
    "id": 1,
    "username": "alice",
    "email": "[email protected]",
    "active": true
} */

🎨 Custom toJSON() Method

Override serialization completely with your own toJSON() method:

class User {
    property name="id" type="numeric";
    property name="firstName" type="string";
    property name="lastName" type="string";
    property name="email" type="string";
    property name="passwordHash" type="string";

    /**
     * Custom JSON serialization
     * Combines firstName and lastName into fullName
     * Excludes sensitive data
     */
    function toJSON() {
        return {
            "id": variables.id,
            "fullName": "#variables.firstName# #variables.lastName#",
            "email": variables.email,
            "initials": "#variables.firstName.left(1)##variables.lastName.left(1)#"
        };
    }
}

user = new User();
user.id = 1;
user.firstName = "Alice";
user.lastName = "Johnson";
user.email = "[email protected]";
user.passwordHash = "secret...";

json = user.toJSON();
/* {
    "id": 1,
    "fullName": "Alice Johnson",
    "email": "[email protected]",
    "initials": "AJ"
} */

🔄 Recursive Class Handling

BoxLang automatically handles recursive class references:

class Company {
    property name="id" type="numeric";
    property name="name" type="string";
    property name="employees" type="array";
}

class Employee {
    property name="id" type="numeric";
    property name="name" type="string";
    property name="company" type="Company";
}

company = new Company();
company.id = 1;
company.name = "Ortus Solutions";
company.employees = [];

employee = new Employee();
employee.id = 1;
employee.name = "Luis Majano";
employee.company = company;

company.employees.append( employee );

// Serializes without infinite recursion!
json = company.toJSON();
// Recursive references are handled gracefully

📋 Class Serialization Annotations Reference

| Annotation | Scope | Purpose | Example | |------------|-------|---------|---------|------| | @serializable | Class/Property | Enable/disable serialization | @serializable( false ) | | @jsonExclude | Class/Property | Exclude from JSON | @jsonExclude( true ) | | @jsonExclude (list) | Class | Exclude multiple properties | @jsonExclude( "password,secret" ) |

Best Practice: Use property-level @jsonExclude( true ) for individual fields and class-level @jsonExclude( "field1,field2" ) with a comma-separated list for multiple fields. Implement custom toJSON() methods for complex transformation logic.

How It Works: The BoxClassSerializer introspects the class's property definitions, filters out excluded properties, and serializes the variables scope values. Only properties defined with the property keyword are included in serialization.

📥 JSON Deserialization (jsonDeserialize / fromJSON)

Parse JSON strings back into BoxLang data structures using jsonDeserialize() or the fromJSON() member method.

Basic Deserialization

// Function syntax
json = '{"name":"Luis Majano","company":"Ortus Solutions","year":2006}';
person = jsonDeserialize( json );

// Member method syntax (preferred)
person = json.fromJSON();

// Access deserialized data
writeOutput( person.name );      // "Luis Majano"
writeOutput( person.company );   // "Ortus Solutions"

Strict Mapping Mode

Control how JSON objects are mapped to BoxLang types:

json = '{"name":"Alice","scores":[95,87,92]}';

// Strict mapping (default) - everything becomes structs
data = jsonDeserialize( json, strictMapping: true );
// { name: "Alice", scores: [95, 87, 92] }

// Non-strict mapping - may preserve Java types
data = jsonDeserialize( json, strictMapping: false );

Supported JSON Types

BoxLang deserializes JSON to native types:

// Primitives
jsonDeserialize( "42" );                    // 42 (numeric)
jsonDeserialize( "true" );                  // true (boolean)
jsonDeserialize( '"Hello"' );               // "Hello" (string)
jsonDeserialize( "null" );                  // null

// Arrays
jsonDeserialize( "[1,2,3]" );              // [1, 2, 3]
jsonDeserialize( '["a","b","c"]' );        // ["a", "b", "c"]

// Objects (become structs)
jsonDeserialize( '{"a":1,"b":2}' );        // { a: 1, b: 2 }

// Nested structures
json = '{
    "user": {
        "name": "Alice",
        "age": 30,
        "roles": ["admin", "developer"]
    }
}';
data = json.fromJSON();
writeOutput( data.user.name );              // "Alice"
writeOutput( data.user.roles[1] );          // "admin"

Validation Before Deserialization

Always validate JSON before deserializing:

function processJSON( string jsonData ) {
    if ( !isJSON( jsonData ) ) {
        throw( type="InvalidJSON", message="Invalid JSON provided" );
    }

    return jsonData.fromJSON();
}

// Safe deserialization
try {
    data = processJSON( userInput );
    // Process data...
} catch ( any e ) {
    writeOutput( "Error: #e.message#" );
}

✅ JSON Validation (isJSON)

Test if a string contains valid JSON:

// Valid JSON
isJSON( '{"name":"Alice"}' );           // true
isJSON( '[1,2,3]' );                    // true
isJSON( '"Hello"' );                    // true
isJSON( 'true' );                       // true
isJSON( '42' );                         // true

// Invalid JSON
isJSON( '{name:"Alice"}' );             // false (unquoted key)
isJSON( "Hello" );                      // false (missing quotes)
isJSON( "" );                           // false (empty string)
isJSON( undefined );                    // false (not a string)

// Practical usage
if ( isJSON( apiResponse ) ) {
    data = apiResponse.fromJSON();
    processData( data );
} else {
    logError( "Invalid JSON response" );
}

📝 List to JSON Conversion

Convert delimited strings (lists) to JSON arrays:

// Default comma delimiter
tags = "programming,boxlang,json,tutorial";
jsonArray = tags.listToJSON();
// ["programming","boxlang","json","tutorial"]

// Function syntax
categories = "tech,science,arts";
json = jsonSerialize( categories.listToArray() );

// Practical example: CSV to JSON
csvLine = "Alice,30,[email protected]";
jsonData = csvLine.listToJSON();
// ["Alice","30","[email protected]"]

// With custom delimiter
path = "home/user/documents/file.txt";
parts = path.listToArray( "/" ).toJSON();
// ["home","user","documents","file.txt"]

🎯 Advanced JSON Techniques

Working with API Responses

// Fetch and parse API response
http url="https://api.example.com/users" result="apiResult";

if ( isJSON( apiResult.fileContent ) ) {
    users = apiResult.fileContent.fromJSON();

    // Process users
    users.each( ( user ) => {
        println( "User: #user.name# (#user.email#)" );
    } );
} else {
    throw( "Invalid JSON response from API" );
}

JSON Configuration Files

// Load configuration from JSON file
configJson = fileRead( expandPath( "./config.json" ) );
config = configJson.fromJSON();

// Use configuration
datasource = config.database.datasource;
cacheTimeout = config.cache.timeout;

// Save updated configuration
config.features.newFeature = true;
fileWrite(
    expandPath( "./config.json" ),
    config.toJSON( pretty: true )
);

Nested Data Transformation

// Complex data structure
order = {
    orderId: 12345,
    customer: {
        id: 1,
        name: "Alice Johnson",
        email: "[email protected]"
    },
    items: [
        { productId: 101, name: "Widget", quantity: 2, price: 29.99 },
        { productId: 102, name: "Gadget", quantity: 1, price: 49.99 }
    ],
    total: 109.97,
    orderDate: now()
};

// Serialize for API transmission
jsonPayload = order.toJSON();

// Send to API
http
    url="https://api.example.com/orders"
    method="POST"
    result="response" {
    httpParam type="header" name="Content-Type" value="application/json";
    httpParam type="body" value=jsonPayload;
}

// Parse response
if ( isJSON( response.fileContent ) ) {
    result = response.fileContent.fromJSON();
    orderId = result.id;
}

JSON Stream Processing

// Process large JSON arrays efficiently
jsonData = fileRead( "large-dataset.json" );
data = jsonData.fromJSON();

// Filter and transform
results = data
    .filter( ( item ) -> item.status == "active" )
    .map( ( item ) -> {
        return {
            id: item.id,
            name: item.name,
            processed: true
        };
    } );

// Save results
fileWrite( "results.json", results.toJSON( pretty: true ) );

🔧 Custom Serializers (Advanced)

BoxLang uses custom serializers for specific types. You can examine these in the BoxLang source:

BoxClassSerializer - Handles class instances with property introspection
BoxQuerySerializer - Handles query objects with format options
BoxStructSerializer - Handles structs and maps
BoxArraySerializer - Handles arrays and lists
DynamicObjectSerializer - Handles Java object proxies
ExceptionSerializer - Handles exception objects
JavaArraySerializer - Handles native Java arrays

These serializers are automatically invoked when their respective types are encountered during JSON serialization.

📖 Function Reference

jsonSerialize( data, [queryFormat], [useSecureJSONPrefix], [useCustomSerializer], [pretty] )

Convert BoxLang data to JSON string.

Arguments:

data (any, required) - Data to serialize
queryFormat (string) - Query format: "struct", "row", "column", "true", "false" (default: "row")
useSecureJSONPrefix (string/boolean) - Add secure prefix (not implemented)
useCustomSerializer (boolean) - Use custom serializer (not implemented)
pretty (boolean) - Pretty print with indentation (default: false)

Returns: String (JSON)

Member Methods:

data.toJSON() - Available on most types
"list,items".listToJSON() - Convert delimited string to JSON array

jsonDeserialize( json, [strictMapping], [useCustomSerializer] )

Parse JSON string to BoxLang data.

Arguments:

json (string, required) - JSON string to parse
strictMapping (boolean) - Force all objects to structs (default: true)
useCustomSerializer (string) - Custom serializer name (not implemented)

Returns: Any (native BoxLang types)

Member Methods:

jsonString.fromJSON() - Parse JSON string

isJSON( var )

Validate if string is valid JSON.

Arguments:

var (any, required) - Value to test

Returns: Boolean

jsonPrettify( var )

Format JSON string with indentation.

Arguments:

var (string, required) - JSON string to format

Returns: String (formatted JSON)

Member Methods:

jsonString.jsonPrettify() - Format JSON string

🎓 Best Practices

✅ Always quote struct keys for exact casing in JSON output
✅ Use isJSON() validation before deserializing user input
✅ Implement custom toJSON() methods for complex class serialization logic
✅ Use jsonExclude annotations to protect sensitive data (passwords, secrets)
✅ Prefer pretty: true for configuration files and debugging
✅ Use queryFormat="struct" for REST API responses (most compatible with JavaScript)
✅ Handle JSON errors gracefully with try/catch blocks
✅ Validate API responses with isJSON() before parsing
✅ Use member methods (toJSON(), fromJSON()) for cleaner, more readable code
✅ Document serialization behavior in class comments when using custom logic

Structures Arrays Queries Classes & O.O.

PreviousQueries NextXML

Last updated 1 month ago

Was this helpful?

hashtag📋 Table of Contents

hashtag💻 JSON in Code

hashtag📚 JSON Built-In Functions (BIFs)

hashtagCore JSON Functions

hashtagMember Method Support

hashtag📤 JSON Serialization (jsonSerialize / toJSON)

hashtagBasic Serialization

hashtagSupported Data Types

hashtag🎨 Pretty Printing

hashtag🔑 Key Casing Preservation

hashtag📊 Query Serialization

hashtag🎯 Class Serialization (The Magic!)

hashtagAutomatic Property Serialization

hashtag🔒 Controlling Serialization with Annotations

hashtag🎨 Custom toJSON() Method

hashtag🔄 Recursive Class Handling

hashtag📋 Class Serialization Annotations Reference

hashtag📥 JSON Deserialization (jsonDeserialize / fromJSON)

hashtagBasic Deserialization

hashtagStrict Mapping Mode

hashtagSupported JSON Types

hashtagValidation Before Deserialization

hashtag✅ JSON Validation (isJSON)

hashtag📝 List to JSON Conversion

hashtag🎯 Advanced JSON Techniques

hashtagWorking with API Responses

hashtagJSON Configuration Files

hashtagNested Data Transformation

hashtagJSON Stream Processing

hashtag🔧 Custom Serializers (Advanced)

hashtag📖 Function Reference

hashtagjsonSerialize( data, [queryFormat], [useSecureJSONPrefix], [useCustomSerializer], [pretty] )

hashtagjsonDeserialize( json, [strictMapping], [useCustomSerializer] )

hashtagisJSON( var )

hashtagjsonPrettify( var )

hashtag🎓 Best Practices

hashtag🔗 Related Documentation

📋 Table of Contents

💻 JSON in Code

📚 JSON Built-In Functions (BIFs)

Core JSON Functions

Member Method Support

📤 JSON Serialization (jsonSerialize / toJSON)

Basic Serialization

Supported Data Types

🎨 Pretty Printing

🔑 Key Casing Preservation

📊 Query Serialization

🎯 Class Serialization (The Magic!)

Automatic Property Serialization

🔒 Controlling Serialization with Annotations

🎨 Custom toJSON() Method

🔄 Recursive Class Handling

📋 Class Serialization Annotations Reference

📥 JSON Deserialization (jsonDeserialize / fromJSON)

Basic Deserialization

Strict Mapping Mode

Supported JSON Types

Validation Before Deserialization

✅ JSON Validation (isJSON)

📝 List to JSON Conversion

🎯 Advanced JSON Techniques

Working with API Responses

JSON Configuration Files

Nested Data Transformation

JSON Stream Processing

🔧 Custom Serializers (Advanced)

📖 Function Reference

jsonSerialize( data, [queryFormat], [useSecureJSONPrefix], [useCustomSerializer], [pretty] )

jsonDeserialize( json, [strictMapping], [useCustomSerializer] )

isJSON( var )

jsonPrettify( var )

🎓 Best Practices

🔗 Related Documentation