JSON

A JSON variable stores structured data as a dynamic map-like object. It's perfect for storing complex, nested data structures with key-value pairs, making it ideal for API responses, configuration objects, or any hierarchical data.

When to Use

Use JSON variables when you need to:

• Store API response data with multiple fields

• Manage complex configuration objects

• Store user profiles or settings

• Handle nested or hierarchical data

• Group related data together

• Store objects with dynamic or unknown keys

Structure

JSON variables use key-value pairs and support nesting:

{
  "name": "John Doe",
  "age": 30,
  "email": "[email protected]",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "country": "USA"
  },
  "preferences": {
    "darkMode": true,
    "notifications": false
  },
  "tags": ["developer", "designer"]
}

Common Use Cases

1. Storing API Responses

Store structured data from API calls:

Variable: userData (JSON)
Initial Value: {}

On API Success:
  Set State: userData = ${apiResponse.data}

Text Widget:
  Text: ${concat("Welcome, ", userData.name)}

Text Widget:
  Text: ${userData.email}

2. Configuration Objects

Store app settings or configurations:

Variable: appConfig (JSON)
Value: {
  "theme": "dark",
  "language": "en",
  "itemsPerPage": 20,
  "enableAnalytics": true
}

Text Widget:
  Text: ${concat("Current theme: ", appConfig.theme)}

3. User Profiles

Manage user information:

Variable: userProfile (JSON)
Value: {
  "id": "123",
  "name": "Jane Smith",
  "avatar": "https://example.com/avatar.jpg",
  "role": "admin",
  "lastLogin": "2025-11-05"
}

Avatar Widget:
  Image URL: ${userProfile.avatar}

Text Widget:
  Text: ${userProfile.name}

4. Form Data

Collect multiple form fields in one object:

Variable: formData (JSON)
Initial Value: {
  "firstName": "",
  "lastName": "",
  "email": "",
  "phone": ""
}

Note: To update individual form fields, you'll need to reconstruct the entire JSON object with the updated values.

5. Nested Data Structures

Handle complex hierarchical data:

Variable: product (JSON)
Value: {
  "id": "prod_123",
  "name": "Laptop",
  "price": 999.99,
  "specs": {
    "cpu": "Intel i7",
    "ram": "16GB",
    "storage": "512GB SSD"
  },
  "reviews": {
    "average": 4.5,
    "count": 127
  }
}

Text Widget:
  Text: ${product.name}

Text Widget:
  Text: ${concat("$", product.price)}

Text Widget:
  Text: ${concat("CPU: ", product.specs.cpu)}

Accessing JSON Data

Dot Notation

Access properties using dots:

${userData.name}
${userData.address.city}
${product.specs.cpu}

Using jsonGet Function

Access properties using the jsonGet (or get) function:

${jsonGet(userData, 'name')}
${jsonGet(userData, 'address.city')}
${jsonGet(product, 'specs.cpu')}

Nested Properties

Access deeply nested data:

${user.profile.settings.preferences.darkMode}
${jsonGet(user, 'profile.settings.preferences.darkMode')}

Dynamic Keys

Access properties dynamically using the jsonGet function:

${jsonGet(userData, keyName)}
${jsonGet(config, settingKey)}

Modifying JSON Data

Replacing Entire Object

Replace the whole JSON object:

You can also construct new JSON objects by modifying the response:

Set State: userData = ${apiResponse.data.user}

Working with JSON

JSON Operators

The primary JSON operator available is:

• jsonGet() (alias: get()) - Access nested properties using path notation

See the JSON Operators documentation for detailed usage.

Accessing Nested Properties

Use jsonGet with dot notation paths:

${jsonGet(userData, 'address.city')}
${jsonGet(product, 'specs.cpu')}
${jsonGet(user, 'profile.settings.darkMode')}

Checking for Properties

Verify if a property exists:

${isNotNull(userData.email)}
${isNotNull(jsonGet(userData, 'address.city'))}

JSON vs List

While both can store complex data:

JSON	List
Key-value pairs	Ordered collection of items
Access by property name	Access by index
Best for structured objects	Best for arrays of items
{"name": "John", "age": 30}	["Apple", "Banana", "Orange"]

Best Practices

• Initialize with structure: Set an initial value with the expected structure, even if empty: {}

• Use consistent naming: Keep property names consistent (camelCase or snake_case)

• Validate before access: Check if properties exist before using them to avoid errors

• Keep structure flat when possible: Deep nesting can be hard to manage; flatten when reasonable

• Use for related data: Group related properties together in a JSON object

• Document structure: Comment or document the expected structure of complex JSON variables

• Handle null/undefined: Always check for missing properties in API responses

Common Patterns

Default Values

Provide fallback values for missing properties:

${if(isNotNull(userData.name), userData.name, 'Guest')}
${if(isNotNull(jsonGet(userData, 'name')), jsonGet(userData, 'name'), 'Guest')}
${if(isNotNull(userData.age), userData.age, 0)}

Conditional Access

Check before accessing nested properties:

${if(userData.address, userData.address.city, 'Unknown')}
${if(jsonGet(userData, 'address'), jsonGet(userData, 'address.city'), 'Unknown')}

Replacing JSON Objects

Update entire objects:

Set State: userData = ${apiResponse.data}
Set State: userProfile = ${apiResponse.data.profile}

Dynamic Property Access

Use jsonGet with variable paths:

Variable: propertyPath (String)
Value: "user.profile.name"

Text: ${jsonGet(data, propertyPath)}

Related Documentation

• JSON Operators - All available JSON manipulation functions

• List Variable - For array-based data

• API Calls - Working with API responses

• Variables Overview - Learn about all variable types