Expressions
Relevant source files
The following files were used as context for generating this wiki page:
- packages/frontend/editor-ui/src/app/utils/expressions.test.ts
- packages/testing/playwright/tests/ui/9-expression-editor-modal.spec.ts
- packages/testing/playwright/tests/ui/11-inline-expression-editor.spec.ts
- packages/testing/playwright/tests/ui/14-data-transformation-expressions.spec.ts
- packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/expressions_tutorial.json
- packages/@n8n/ai-workflow-builder.ee/evaluations/chains/evaluators/expressions-evaluator.ts
- packages/@n8n/ai-workflow-builder.ee/src/chains/prompts/base/expression-rules.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-transformation.ts
- packages/nodes-base/nodes/If/If.node.json
Expressions are the core mechanism in n8n for creating dynamic workflows. They act as the "glue" that allows nodes to reference and manipulate data from other nodes. An expression is a small piece of code, typically JavaScript, enclosed in double curly braces {{ }}. When a workflow runs, these expressions are evaluated and replaced with their resulting dynamic values.
This system enables powerful data-linking, transformation, and conditional logic, forming the foundation of complex automations. From simple data mapping to intricate data manipulation using JavaScript functions, expressions provide the flexibility to connect and control the flow of information between different services and operations within a workflow.
Syntax and Structure
The fundamental syntax for an expression is a piece of JavaScript code wrapped in double curly braces. For parameter fields that contain a mix of static text and expressions, the entire string must be prefixed with an equals sign =.
Sources: packages/frontend/editor-ui/src/app/utils/expressions.test.ts:50-52, packages/@n8n/ai-workflow-builder.ee/src/chains/prompts/base/expression-rules.ts:3-5
Anatomy of an Expression
The diagram below breaks down a typical n8n expression used to access data from another node.
This diagram illustrates the components of a common n8n expression.
Sources: packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/expressions_tutorial.json:100-106, packages/@n8n/ai-workflow-builder.ee/evaluations/chains/evaluators/expressions-evaluator.ts:14-16
Critical Formatting Rules
To ensure expressions are parsed and executed correctly, the following rules are critical:
- Equals Sign (
=) Prefix: An=prefix is required for expressions that are mixed with static text (e.g.,="Hello {{ $json.name }}"). It is also required for pure expressions to be correctly identified (e.g.,={{ $json.name }}). - Double Curly Braces: Expressions must always be wrapped in double curly braces
{{ }}. Single braces will not be evaluated. - No Special Characters: Avoid using emojis or other special characters within the expression's code, as they can break parsing.
Sources: packages/@n8n/ai-workflow-builder.ee/src/chains/prompts/base/expression-rules.ts:3-9
Expression Evaluation
Expressions are evaluated in the UI to provide a live preview and at runtime during workflow execution. The evaluation logic can handle static values, objects, arrays, and dynamic data from other nodes.
Live Preview in UI
The expression editors in the n8n UI provide a live preview of the expression's output. This is a key feature for debugging and building workflows.
- Static Data: Simple JavaScript like
{{ 1 + 2 }}or{{ "ab" + "cd" }}is resolved instantly. - Dynamic Data: To resolve expressions that reference data from previous nodes (e.g.,
{{ $json.myStr }}), those nodes must have been executed at least once. If not, the editor will display a message like[Execute previous nodes for preview].
The following diagram shows the user interaction flow for getting a live preview.
This sequence shows how the expression editor provides a live preview by communicating with the evaluation service.
Sources: packages/testing/playwright/tests/ui/9-expression-editor-modal.spec.ts:88-106, packages/testing/playwright/tests/ui/11-inline-expression-editor.spec.ts:133-141
AI-based Evaluation
In some contexts, like the AI workflow builder, an AI model is used to evaluate the correctness of expressions based on a set of rules. This helps ensure that generated workflows are syntactically correct. Violations are categorized by severity.
| Violation Type | Description | Point Deduction |
|---|---|---|
| Critical | Invalid JS syntax, referencing non-existent nodes/fields. | 40-50 |
| Major | Missing required = prefix, referencing undefined variables. | 20-25 |
| Minor | Inefficient but working expressions, outdated syntax. | 5-10 |
Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/chains/evaluators/expressions-evaluator.ts:59-74
Data Access Patterns
Expressions provide a rich set of variables and selectors to access data from various parts of the workflow.
Key Variables and Selectors
| Syntax | Description | Example |
|---|---|---|
$json | Accesses the json data object from the single item of the directly preceding node. | {{ $json.name }} |
$input.item | Accesses the current item being processed. Similar to $json but more explicit. | {{ $input.item.json.myStr }} |
$('Node Name') | Selects a node by its name to access its output data. | {{ $('Source Data').item.json.name }} |
.item / .first() / .last() | Selectors to get the current, first, or last item from a node's output. .item is often equivalent to .last(). | {{ $('Source Data').last().json.name }} |
.all() | Gets data from ALL output items of a node, returning it as an array of objects. | {{ $('Split Out Skills').all().map(item => item.json.skills).join(', ') }} |
$parameter | Accesses the current node's own parameters. | {{ $parameter["operation"] }} |
$now / $today | Special variables for accessing the current date and time. | {{ $now.format('MMMM d, yyyy') }} |
$env / $vars / $secrets | Access environment variables, workflow static data, and secrets. | {{ $env.MY_API_KEY }} |
$execution | Provides metadata about the current workflow execution, like its ID. | {{ $execution.id }} |
Sources: packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/expressions_tutorial.json, packages/@n8n/ai-workflow-builder.ee/evaluations/chains/evaluators/expressions-evaluator.ts:20-31, packages/testing/playwright/tests/ui/9-expression-editor-modal.spec.ts:83-86
Accessing Nested Data and Arrays
Expressions use standard JavaScript dot notation and bracket notation to access nested data.
- Nested Objects: Access properties with
.(e.g.,{{ $json.contact.email }}). - Arrays: Access elements by index
[n]. Arrays are zero-indexed, so the first element is[0]. (e.g.,{{ $json.skills[1] }}). - Arrays of Objects: Combine both to access a property of an object within an array (e.g.,
{{ $json.projects[0].status }}).
JavaScript in Expressions
Beyond simple data retrieval, expressions can execute arbitrary JavaScript, including built-in methods and n8n-specific helper functions.
Native JavaScript Functions
You can use standard JavaScript objects and methods on your data.
- String Methods:
{{ $json.myStr.toLowerCase() }} - Number Methods:
{{ $json.myNum.toPrecision(3) }} - Math Object:
{{ Math.round($json.age / 7) }} - Object Inspection:
{{ Object.keys($json.contact) }} - JSON Utilities:
{{ JSON.stringify($json.contact, null, 2) }}
Sources: packages/testing/playwright/tests/ui/14-data-transformation-expressions.spec.ts:26-32, 60-66, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/expressions_tutorial.json:216-231, 288-294, 312-318
n8n Helper Methods
n8n extends native JavaScript types with useful helper methods for common data transformation tasks.
- String Helpers:
{{ $json.myStr.extractEmail() }} - Array Helpers:
{{ $json.myArr.first() }},{{ $json.myArr.last() }}
Sources: packages/testing/playwright/tests/ui/14-data-transformation-expressions.spec.ts:44-50, 92-98
Frontend Utilities
The frontend contains several utility functions for handling and manipulating expression strings.
| Function | Description |
|---|---|
stringifyExpressionResult | Converts an expression result object into a displayable string. Handles errors, nulls, and empty strings. |
unwrapExpression | Removes the {{ }} wrapper from an expression string. For example, {{ $json.foo }} becomes $json.foo. |
removeExpressionPrefix | Removes the leading = from a string, if present. |
completeExpressionSyntax | Autocompletes partial expressions, like turning test {{ into =test {{ }}. |
shouldConvertToExpression | Determines if a string contains {{ }} and should be converted into an expression field. |
Sources: packages/frontend/editor-ui/src/app/utils/expressions.test.ts
Conclusion
Expressions are a cornerstone of n8n's functionality, providing the essential capability to create dynamic, data-driven workflows. They bridge the gap between nodes by allowing users to access, manipulate, and transform data using a flexible and powerful JavaScript-based syntax. From simple variable substitution to complex logical operations, mastering expressions is key to unlocking the full potential of n8n for building sophisticated automation.
Sources: CONTRIBUTING.md, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/expressions_tutorial.json