Skip to main content

​
Overview

The Jsonnet element allows you to embed Jsonnet templates directly within your Elemental notification structure. Jsonnet is a data templating language designed to generate JSON output, making it ideal for programmatically creating structured content, avoiding repetition, and building complex data structures. When to use:
  • Generate dynamic JSON structures based on data
  • Create reusable template logic with functions and variables
  • Build complex nested objects programmatically
  • Avoid repetitive JSON structures
  • Generate locale-specific content programmatically
Jsonnet is an advanced templating feature. It requires knowledge of the Jsonnet language syntax. For simple content, consider using Text elements with Handlebars variables instead.

​
Basic Example

{
  "type": "jsonnet",
  "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Alice\", 30) }"
}

​
Fields

​
type
string
required
The type of element. For Jsonnet elements, this value must be "jsonnet".
​
template
string
required
The Jsonnet template code. This is a string containing valid Jsonnet syntax that will be evaluated to generate JSON output. The template has access to the message data via Jsonnet’s standard variable access.
​
locales
object
Region-specific Jsonnet templates. The object keys are locale codes (e.g., "es", "fr"), and values are Jsonnet template strings that will be used for that locale. See Locales documentation for more details.
​
channels
string[]
An array of channel names. The Jsonnet element will only be rendered for the specified channels. See Control Flow documentation for details.

​
Jsonnet Language Basics

Jsonnet is a data templating language that extends JSON with features like:
  • Variables: local name = "Alice";
  • Functions: local greet(name) = "Hello " + name;
  • Object composition: Merge objects with +
  • Conditionals: if condition then value1 else value2
  • Loops: [x * 2 for x in [1, 2, 3]]
  • Imports: local lib = import "lib.jsonnet";
For complete Jsonnet language documentation, see the official Jsonnet documentation.

​
Examples & Variants

​
Simple Object Generation

Generate a simple JSON object: 
{
  "type": "jsonnet",
  "template": "{ message: \"Welcome!\", timestamp: \"2024-01-15\" }"
}
Output: 
{
  "message": "Welcome!",
  "timestamp": "2024-01-15"
}

​
Using Functions

Create reusable functions: 
{
  "type": "jsonnet",
  "template": "local formatPrice(amount) = \"$\" + std.toString(amount); { price: formatPrice(99.99), discount: formatPrice(49.99) }"
}
Output: 
{
  "price": "$99.99",
  "discount": "$49.99"
}

​
Conditional Content

Generate different content based on conditions: 
{
  "type": "jsonnet",
  "template": "local isPremium = true; { tier: if isPremium then \"premium\" else \"basic\", features: if isPremium then [\"feature1\", \"feature2\", \"feature3\"] else [\"feature1\"] }"
}
Output: 
{
  "tier": "premium",
  "features": ["feature1", "feature2", "feature3"]
}

​
Array Generation

Generate arrays programmatically: 
{
  "type": "jsonnet",
  "template": "{ items: [\"item\" + std.toString(i) for i in [1, 2, 3, 4, 5]] }"
}
Output: 
{
  "items": ["item1", "item2", "item3", "item4", "item5"]
}

​
Localized Templates

Provide different Jsonnet templates for different locales: 
{
  "type": "jsonnet",
  "template": "{ greeting: \"Hello\", name: \"World\" }",
  "locales": {
    "es": "{ greeting: \"Hola\", name: \"Mundo\" }",
    "fr": "{ greeting: \"Bonjour\", name: \"Monde\" }"
  }
}

​
Complex Nested Structures

Build complex nested objects: 
{
  "type": "jsonnet",
  "template": "local user(name, email) = { profile: { name: name, email: email }, settings: { notifications: true } }; { users: [user(\"Alice\", \"[email protected]\"), user(\"Bob\", \"[email protected]\")] }"
}
Output: 
{
  "users": [
    {
      "profile": {
        "name": "Alice",
        "email": "[email protected]"
      },
      "settings": {
        "notifications": true
      }
    },
    {
      "profile": {
        "name": "Bob",
        "email": "[email protected]"
      },
      "settings": {
        "notifications": true
      }
    }
  ]
}

​
Channel-Specific Jsonnet

Render Jsonnet only for specific channels: 
{
  "type": "jsonnet",
  "channels": ["email"],
  "template": "{ format: \"html\", content: \"<p>Email-specific content</p>\" }"
}

​
Best Practices

  • Keep templates readable: Use multi-line strings in your code for complex templates
  • Use functions for reusability: Extract common logic into functions
  • Validate output: Ensure your Jsonnet templates produce valid JSON
  • Test templates: Test Jsonnet templates independently before embedding in Elemental
  • Consider alternatives: For simple content, Handlebars in Text elements may be simpler
  • Error handling: Jsonnet syntax errors will cause rendering to fail, so test thoroughly
Jsonnet templates are evaluated at render time. Syntax errors or runtime errors in Jsonnet will cause the entire notification to fail to render. Always test your Jsonnet templates before deploying.

​
Channel Support

  • Email: ✅ Full support
  • Push: ✅ Supported (JSON output can be used in push payloads)
  • SMS: ⚠️ Limited support (JSON output may need to be stringified)
  • Inbox: ✅ Full support

​
Additional Resources