Contact Us 1-800-596-4880

DataWeave Variables

DataWeave 2.2 is compatible and bundled with Mule 4.2. This version of Mule reached its End of Life on May 2, 2023, when Extended Support ended.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

DataWeave is a functional programming language where variables behave just like functions. Before you begin, note that DataWeave version 2 is for Mule 4 apps. For a Mule 3 app, refer to the DataWeave 1.0 documentation set in the Mule 3.9 documentation. For other Mule versions, you can use the version selector for the Mule Runtime table of contents.

A variable is assigned a value, which is either a constant (such as var msg = "hello") or a lambda expression such as () → "hello".

DataWeave 1.0 variables are described in the Mule 3.9 documentation.

Here are some examples of DataWeave 2.0 variable assignments:

Example: Variable Assignment in a DataWeave Script
%dw 2.0
output application/json
var msg = "Hello"

var msg2 = (x = "ignore") -> "hello"

var toUpper = (aString) -> upper(aString)

var combined = (function, msg="universe") -> function(msg ++ " WORLD")
---
[
   msg: msg,
   msg2: msg2(),
   toUpper: toUpper(msg),
   combined: combined(toUpper, "hello"),
   combined2: combined(((x) -> lower(x) ++ " Today"), msg)
]

The script above results in this output:

Example: Output
[
  {
    "msg": "Hello"
  },
  {
    "msg2": "hello"
  },
  {
    "toUpper": "HELLO"
  },
  {
    "combined": "HELLO WORLD"
  },
  {
    "combined2": "hello world Today"
  }
]

In these examples:

  • The msg var is assigned to a constant.

  • msg2 is assigned to an expression that maps to a constant, so msg2() behaves the same way as msg, without the ().

  • The toUpper variable maps an input parameter to the DataWeave upper function. So it is used like a more traditional function in other languages as toUpper(aString).

  • The combined variable accepts a function as an input parameter, then applies that function name to the second msg argument. The second msg argument is optional because a default value universe is specified.

The result of the expression combined(toUpper, " world") is to apply the toUpper function defined earlier in the header to the msg parameter value world. The supplied second argument world overrides the msg="universe" default value, so the result is HELLO WORLD. The expression combined(toUpper), which omits the second argument, uses the default msg value to return "combined": "UNIVERSE WORLD".

The combined2: combined(x) → lower(x) ++ " Today", msg) defines the lambda expression that you can reuse in different contexts. In the example, combined2 key defines the expression “in place” at the time the function is called.

Note that these types of “in place” expressions are called closures in languages like JavaScript.

DataWeave includes syntactic sugar to make it easier to access lambda expressions that are assigned to a variable as functions. To do this, you replace the var directive with the fun directive, and replace the arrow in the lambda expression with an equal sign (=). You also move the lambda expression arguments next to the function name so the syntax looks like a function declaration in other procedural programming languages. This allows you to use variables as if they were functions. So the previous example can be equivalently written as:

%dw 2.0
output application/json
var msg = "Hello"

var toUpper = (aString) -> upper(aString)
var toLower = (aString) -> lower(aString)

fun msg2(optParm = "ignore") = "hello"

fun toTitle(text: String) = toLower(text[0]) ++ toUpper(text[1 to -1])

fun combined(function, msg="universe") = function(msg ++ " world")
---
[
   msg: msg,
   msg2: msg2(),
   toUpper: toTitle(msg),
   combined: combined(toUpper, msg),
   combined2: combined((x) -> lower(x) ++ " today", msg)
]

This example produces the same result:

[
  {
    "msg": "Hello"
  },
  {
    "msg2": "hello"
  },
  {
    "toUpper": "hELLO"
  },
  {
    "combined": "HELLO WORLD"
  },
  {
    "combined2": "hello world today"
  }
]

The important distinction in DataWeave is that functions are variables, and every function is just a syntactical renaming of the underlying var syntax, which allows you to pass function names or lambda expressions as arguments to other functions. The fun syntax allows you to access the powerful functional programming aspects of DataWeave while also being able to write simpler expressions as function calls you might be more familiar with.

Also notice that DataWeave variables (and functions) can specify any number of optional arguments by providing default values, so long as all those optional arguments are last in the argument list.

Variable Scopes

You can initialize and use both global and local variables in DataWeave scripts.

  • Global variables are initialized in the header of the DataWeave script and can be referenced by name from anywhere in the body of a DataWeave script.

    The header of a DataWeave script accepts a var directive that initializes a variable, for example: var language='Español'. You can declare multiple global variables on separate lines in the header.

  • Local variables are initialized in the body of the DataWeave script and can be referenced by name only from within the scope of the expression where they are initialized.

    The syntax for initializing a local variable looks like this:

    do {
          [type <name> = <type expression>]*
          [var <name> = <expression>]*
          [fun <name>(<params>*) = <expression>]*
          [ns <name> <nsUri>]*
          ---
          <body>
    }

Note that DataWeave variables cannot be reassigned. They are also distinct from variables that are part of the Mule message (such as target variables). DataWeave variables do not persist beyond the scope of the script in which they are initialized.

Naming Rules for Variables

You can declare any variable name that is a valid identifier. See Rules for Declaring Valid Identifiers for more details.

Example: Global DataWeave Variables

This example defines a do operation that initializes a language variable with the constant value Español and returns that constant value. The body of the DataWeave script calls the do operation using the variable myVar, which populates the <language/> element in the XML output with the value Español.

Transform
%dw 2.0
output application/xml
var myVar = do {
    var language = "Español"
    ---
    language
}
---
{
  document: {
    language: myVar,
    text: "Hola mundo"
  }
}
Output
<?xml version='1.0' encoding='UTF-8'?>
<document>
  <language>Español</language>
  <text>Hola mundo</text>
</document>

Examples: Local DataWeave Variables

To initialize local variables, you can use either literal expressions, variable reference expressions, or functional expressions. These expressions can reference any other local variables within their scope or any input or global variables.

As a best practice, declare local variables within do scopes (see Flow Control in DataWeave). The alternative method of declaring a scope with the using keyword is no longer recommended and available only to provide compatibility.

You can only reference a local variable by name from within the scope of the expression that initializes it. The declaration can be prepended to any literal expression. The literal delimits the scope of the variable, so you cannot reference any variable outside of its scope.

The examples that follow show initialization of local variables.

Example: Scoped to a Simple Value

The following example sets the local variable myVar in a do scope. It calls do from the body of the DataWeave script:

%dw 2.0
output application/json
---
do {
      var myVar = 2
      ---
      3 + myVar
}

The result is 5.

Example: Scoped to an Array Literal

The following example sets the local variable myVar in a do scope and uses it to set the value of the second element in the array to 2:

%dw 2.0
output application/json
---
do {
      var myVar = 2
      ---
      [1, myVar, 3]
}

The result is [ 1, 2, 3]

Example: Scoped to the Object literal

In the following example, references to all the variables are valid. fn and ln are defined and called within the do scope. The global myVar variable is also accessible from that scope.

%dw 2.0
var myVar = 1234
var myDo =  do {
    var fn = "Annie"
    var ln = "Point"
    ---
    {
      id : myVar,
      firstname : fn,
      lastname : ln
    }
}
output application/xml
---
{ person : myDo }
<?xml version='1.0' encoding='UTF-8'?>
<person>
  <id>1234</id>
  <firstname>Annie</firstname>
  <lastname>Point</lastname>
</person>
Example: Invalid Reference That Is Outside the Scope

The following example produces an error because fromDoScope is referenced from outside the scope of do. As a consequence, the concatenation operation (++) cannot append the name-value pair to the collection.

%dw 2.0
var myVar = 1234
var myDo =  do {
    var fn = "Annie"
    var ln = "Point"
    var fromDoScope = "Platform"
    ---
    {
      id : myVar,
      firstname : fn,
      lastname : ln
    }
}
output application/xml
---
{
    person : myDo ++ { "outsideDoScope" : fromDoScope }
}

The invalid example returns this error: Unable to resolve reference of fromDoScope.

Example: Reference That Is Inside a Function

The following example passes the string HELLO to the test function defined in the header. The do scope accepts the string, converts it to lowercase, and then concatenates that string to the suffix variable, which is also defined in the header of the scope.

%dw 2.0
fun test(param1: String) = do {
    var suffix = "123"
    fun innerTest(str: String) = lower(str)
   ---
   innerTest(param1 ++ suffix)
}
output application/json
---
test("HELLO")

The result is "hello123".

Variables Assigned as Lambda Expressions

When a variable is assigned a lambda expression, it behaves just like a function. Like a function, the lambda expression for a variable assignment can include parameters that can be used in the right-hand side expression, such as (string) → upper(string), which will convert any string to uppercase.

Other variables can also be passed as arguments to another variable’s lambda expression. This example shows how the toUpper variable’s lambda expression can be passed by name into the addSuffix variable’s lambda expression.

%dw 2.0
output application/json
var toUpper = (aString) -> upper(aString)

var addSuffix = (msg, aFunction, suffix) -> aFunction(msg ++ suffix)
---
addSuffix("hello", toUpper, " world") //result is "HELLO WORLD"