DataWeave Reference Documentation

The DataWeave header contains the directives, which define high level information about your transformation. The structure of the Header is a sequence of lines, each with its own Directives. The Header is terminated with '---'.

Through directives you can define:

All directives are declared on the header section of your DataWeave document and act upon the entire scope of it. Directives are a mechanism to declare variables and constants and namespace aliases which need to be referenced in the Document. They are also needed to declare the type of the output of your transform. In Anypoint Studio, you can optionally use them to declare additional inputs. You rarely need them for this as any data arriving in the incoming Mule Message is already implicitly recognized as an input.

The body contains the expression that generates the output structure. Regardless of the types of the input and output, the data model for the output is always described in the standard DataWeave language, and this model that the transform executes.

The data model of the produced output can consist of three different types of data:

When you write your DataWeave file, you define an expression that generates one of the data types listed above.

Literals can be of the following types:

Arrays are sequences of expressions.

These are represented as a comma separated sequence of key:value pairs surrounded by curly braces { }.

Note that both the keys and the values may be expressions.

Input directives allow you to make any number of input sources available in global variables, which can then be referenced in any part of the Transform’s body. To reference one of these, you can just call it by the name you defined in the directive. Remember that the Transform is itself an expression, so the entire body of the transform could be written as a simple variable reference to the input document. Consider the example below, which transforms an incoming JSON document into XML, and where the output XML structure mimics the input JSON structure.

In the DataWeave header, you define constants as directives, these can then be referenced as variables in any part of your transform body, just as you do with input variables. The following creates an XML document and inserts the constant value for Language "Español" in the output language element.

Variables declared in the Transform’s header always have a global scope, to declare and initialize a variable with a limited scope, you can do so in any part of the transform’s body.

You can initialize these variables using literal expressions, variable reference expressions, or functional expressions. They may reference any other scoped variables or any of the input variables or constants in their initialization. The declaration and initialization can be prepended to any literal expression, but you must be aware that the literal they are prepended to delimits their scope. You cannot reference a variable outside its scope.

To declare a variable in the DataWeave body, the following syntax is supported: using (<variable-name> = <expression>) and it must be written before defining the contents of the literal that it exists in. To reference an already initialized variable, you can just call it by the name you defined for it as with any other variable, or you can also write it in the form $<variable-name>.

Consider the following examples:

Scoped to Simple literal

Scoped to Array literal

Scoped to Object literal

Invalid Reference outside of Scope

The complex structure of Objects and Arrays can be navigated using Selector Expressions. Each selector expression returns either an object, an array, or a simple type. A selector always operates within a given context, which can be a reference to a variable, an object literal, an array literal, or the invocation of a function. As DataWeave processes a selector, a new context is set for further selectors, so you can navigate through the complex structures of arrays and objects by using chains of selectors, who’s depth is limited only by the depth of the current context.

There are 4 types of selector expression:

Applying the Single level Explicit Selector, the Descendants Selector, or the Indexed Selector returns the value of the key:value pair that matches the expression.

Note: Each of these selector expressions supports having a '?' appended at the end of the chain. This changes the expression into a query that checks upon the existence of the key. The return type in this case is a boolean true or false.

This selector returns the first value whose key matches the expression, that is, payload.name, which returns the value whose key matches name.

This selector returns an array with all the values whose key matches the expression.

This selector can be applied to String literals, Arrays and Objects. In the case of Objects, the value of the key:value pair found at the index is returned. The index is zero based.

When using the Index Selector with a String, the string is broken down into an array, where each character is an index.

Range selectors limit the output to only the elements specified by the range on that specific order. This selector allows you to slice an array or even invert it.

In order to query for the attributes on an Object, the syntax .@<key-name> is used. If you just use .@ (without <key-name>) it returns an object containing each key:value pair in it.

When the context for selection is an Array, the result is always an Array. Each element on the context Array is queried for matching key:value pairs. In each case, only the value of the key:value pair is returned.

This selector is applied to the context using the form ..<field-name> and retrieves the values of all matching key:value pairs in the sub-tree under the current context. Regardless of the hierarchical structure these fields are organized in, they are all placed at the same level in the output.

There are two selectors modifiers: ? and !. The question mark returns true or false whether the keys are present on the structures. The exclamation mark evaluates the selection and fails if any key is not present.

Returns true if the specified key is present in the object.

In the example above, if a 'name' key does exist in the input, it returns true.

This operation also works with attributes:

You can also use this validation operation as part of a filter:

The example above selects key:value pairs with value "Mariano" ⇒ {name: Mariano, name: Mariano}

Often, you want to use the different elements from the Mule Message that arrive at the DataWeave Transformer in your transform. The following sections show you how to reference each of these.

Similar to Map, but instead of processing only the values of an object, it processes both keys and values, and instead of returning an array with the results of processing these values through the lambda, it returns an object with the key:value pairs that result from processing both key and value of the object through the lambda.

The lambda is invoked with two parameters: key and the value. If these parameters are not named, the key is defined by default as $$ and the value as $.

In the example above, as key and value are not defined, they’re identified by the placeholders $$ and $. For each key:value pair in the input, the key is preserved and the value becomes an object with two properties: one of these is the original value, the other is the result of multiplying this value by a constant that is defined as a directive in the header.

The mapping below performs exactly the same transform, but it defines custom names for the properties of the operation, instead of using $ and $$. Here, 'category' is defined as referring to the original key in the object, and 'money' to the value in that key.

Pluck is useful for mapping an object into an array. Pluck is an alternate mapping mechanism to mapObject. Like mapObject, pluck executes a lambda over every key:value pair in its processed object, but instead of returning an object, it returns an array, which may be built from either the values or the keys in the object.

The lambda is invoked with two parameters: key and the value. If these parameters are not named, the key is defined by default as $$ and the value as $.

Assigns a default value in case no value is found in the input field.

Assigns a random value between 0 and 1

The keyword when conditionally evaluates a part of your DataWeave code, depending on if an expression evaluates to true or to false. You can make a single line conditional, or enclose a whole section in curly brackets. In case the when expression evaluates to false, its corresponding part of the code is ignored, and the code that corresponds to the otherwise expression is executed.

You can also chain several otherwise expressions together, like in the example below:

The keyword unless conditionally evaluates a part of your DataWeave code, depending on if an expression evaluates to true or to false. You can make a single line conditional, or enclose a whole section in curly brackets. In case the unless expression evaluates to true, its corresponding part of the code is ignored, and the code that corresponds to the otherwise expression is executed.

The expression and (in lower case) can be used to link multiple conditions, its use means that all of the linked conditions must evaluate to true for the expression as a whole to evaluate to true.

In the example above, currency is "EUR", unless the payload has BOTH conditions met.

The expression or (in lowercase) can be used to link multiple conditions. Its use means that either one or all of the linked conditions must evaluate to true for the expression as a whole to evaluate to true.

In the example above, currency is "EUR", only when one of the conditions evaluates to true.

The concat operator is defined using two plus signs. You must have spaces on both sides of them.

Evaluates if a condition validates to true and returns a boolean value. Conditions may include and and or operators.

Evaluates if an array or list contains in at least one of its indexes a value that validateso true and returns a boolean value. You can search for a literal value, or match a regex too.

You can evaluate if any value in an array matches a given condition:

You can also use contains to evaluate a substring from a larger string:

Instead of searching for a literal substring, you can also match it against a regular expression:

Coerce the given value to the specified type. DataWeave by default attempts to convert the type of a value before failing, so using this operator to convert is sometimes not required but still recommended.

Returns the type of a provided element (eg: '":string"' , '":number"' )

If you have an array of arrays, this function can flatten it into a single simple array.

If you have two or more separate lists, the zip function can be used to merge them together into a single list of consecutive n-tuples. Imagine two input lists each being one side of a zipper: similar to the interlocking teeth of a zipper, the zip function interdigitates each element from each input list, one element at a time.

Here is another example of the zip function with more than two input lists.

Unzip works similarly to zip except that the input is a single list consisting of two or more embedded lists of elements.

Returns the number of elements in an array (or anything that can be converted to an array)

Pushes a new element to the end of an array.

Applies a reduction to the array. The lambda is invoked with two parameters: the accumulator ($$) and the value ($). Unless specified, the accumulator by default takes the first value of the array.

In some cases, you may want to not use the first element of the array as the initial value of the accumulator. To set the accumulator to be something else, you must define this in a lambda.

Merges an array into a single string value, using the provided string as a separator between elements.

Performs the opposite operation as Join By. It splits a string into an array of separate elements, looking for instances of the provided string and using it as a separator.

Returns the provided array ordered according to the value returned by the lambda. The lambda is invoked with two parameters: index and the value. If these parameters are not named, the index is defined by default as $$ and the value as $.

Partitions an array into a Object that contains Arrays, according to the discriminator lambda you define. The lambda is invoked with two parameters: index and the value. If these parameters are not named, the index is defined by default as $$ and the value as $.

Returns only unique values from an array that may have duplicates. The lambda is invoked with two parameters: index and value. If these parameters are not defined, the index is defined by default as $$ and the value as $.

Replaces a section of a string for another, in accordance to a regular expression, and returns a modified string.

Matches a string against a regular expression, and returns true or false if the regular expression matches the entire string.

Match a string against a regular expression. Match returns an array that contains the entire matching expression, followed by all of the capture groups that match the provided regex.

In the example above, we see that the search regular expression describes an email address. It contains two capture groups, what’s before and what’s after the @. The result is an array of three elements: the first is the whole email address, the second matches one of the capture groups, the third matches the other one.

Returns an array with all of the matches in the given string. Each match is returned as an array that contains the complete match, as well as any capture groups there may be in your regular expression.

In the example above, we see that the search regular expression describes an email address. It contains two capture groups, what’s before and what’s after the @. The result is an array with two matches, as there are two email addresses in the input string. Each of these matches is an array of three elements, the first is the whole email address, the second matches one of the capture groups, the third matches the other one.

Evaluates if two values are similar, regardless of their type. For example, the string "1234" and the number 1234 aren’t equal, but they are recognized as similar.

Returns the provided string with leading and trailing spaces removed.

Returns the provided string in uppercase characters.

Returns the provided string in lowercase characters.

Returns the provided string in camel case.

Returns the provided string with every word starting with a capital letter and no underscores.

Returns the provided string with every word separated by a dash.

Returns the provided string with every word separated by an underscore.

Returns the provided numbers set as ordinals.

Returns the provided string transformed into its plural form.

Returns the provided string transformed into its singular form.

String interpolation allows you to embed variables or expressions directly in a string.

Type ⇒ ':date'

Represented as 'Year'-'Month'-'Date'

The type Date has no time component at all (not even midnight).

Type ⇒ ':time'

Represented as 'Hour':'Minutes':'Seconds'.'Milliseconds'

Type ⇒ ':timeZone'

Timezones must include a + or a - to be defined as such. |03:00| is a time, |+03:00| is a timezone.

Type ⇒ ':datetime'

Date time is the conjunction of 'Date' + 'Time' + 'TimeZone'.

Type ⇒ ':localdatetime'

Date time is the conjunction of 'Date' + 'Time'. Local timezone to use.

Type ⇒ ':period'

Specifies a period of time. Examples |PT9M| ⇒ 9 minutes , |P1Y| ⇒ 1 Year

In order to access the different parts of the date, special selectors must be used.

You can specify a date to be in any format you prefer through using as in the following way:

If you are doing multiple similar conversions in your transform, you might want to define a custom type as a directive in the header and set each date as being of that type.

In Anypoint Studio, it’s easy to view metadata that describes the input and output data of every building block you’re using. When defining a custom type for a particular input or output of your transform, this is represented in the DataWeave transformer’s metadata. Exposing metadata helps you understand what it is you’re integrating to in order to build up the rest of a system, as it lets you know what you need to provide and what you can expect in advance.

Lambdas can be used inside operators such as map, mapObject, etc. or they can be assigned to a variable. When using lambdas with an operator, they can be either named or anonymous.

You can declare functions in the Header and these can be invoked at any point in the Body. You refer to them as you do to any variable or constant: using the form $<function-name>() passing an expression as argument. The result of the expression that is passed as an argument is used in the execution of the function body.