Contact Us 1-800-596-4880

Value Constructs for Types

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 represents data using values, each of which has a data type associated with it. There are many types, such as strings, arrays, Booleans, numbers, objects, dates, times, and others. Each type supports several ways of creating its values. This topic explores many of the ways you can create them. 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.

The types that DataWeave provide are bundled into modules that also contain the related functions.

Types in the dw::Core module (Core types) are available without having to import the Core module. Other modules need to be imported for their functions and types to be available.

It is important for you to know the values that are possible for each DataWeave type, how to create those values, and the common patterns used:

Array (dw::Core Type)

An array can hold elements of any supported type. Here is an example of an array:

Example: DataWeave Array
%dw 2.0
output application/json
var x = "words"
---
[ "My", "three", x ]

Conditional Elements

Arrays can define elements that appear (or not) based on a condition.

Conditional elements take the form (value) if condition, for example:

Example: if Condition
%dw 2.0
output application/json
---
[(1) if true, (2) if false]
Output
[1]

Boolean (dw::Core Type)

A Boolean is defined by the keywords true and false.

CData (dw::Core Type)

XML defines a custom type named CData, which inherits from and extends String. It is used to identify a CDATA XML block. It can be used to tell the writer to wrap the content inside CDATA or to check if the input string arrives inside a CDATA block.

Transform
%dw 2.0
output application/xml encoding="UTF-8"
---
{
  users:
  {
    user : "Mariano" as CData,
    age : 31 as CData
  }
}
Output
<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user><![CDATA[Mariano]]></user>
  <age><![CDATA[31]]></age>
</users>

Date and Time (dw::Core Types)

Dates in DataWeave follow the ISO-8601 standard and literals are defined between | characters.

The language has the following native date types:

  • Date

  • DateTime

  • LocalDateTime

  • LocalTime

  • Period

  • Time

  • TimeZone

Date

A Date represented by Year, Month, and Day, specified as |yyyy-MM-dd|. The Date type has no time component.

Example
|2003-10-01|

DateTime

A Date and Time within a TimeZone. It is the conjunction of Date + Time + TimeZone.

Example
|2003-10-01T23:57:59-03:00|

LocalDateTime

A DateTime in the current TimeZone.

Example
|2003-10-01T23:57:59|

LocalTime

A Time in the current TimeZone.

Period

Periods have the form:

  • P[n]Y[n]M[n]DT[n]H[n]M[n]S

  • P<date>T<time>`

Where the [n] is replaced by the value for each of the date and time elements that follow the [n].

P is the duration designator placed at the start of the duration representation.

  • Y is the year designator (e.g. |P1Y|)

  • M is the month designator (e.g. |P1M|)

  • D is the day designator (e.g. |P1D|)

T is the time designator that precedes the time components of the representation.

  • H is the hour designator (e.g. |PT1H|)

  • M is the minute designator (e.g. |PT1M|)

  • S is the second designator (e.g. |PT1S|)

Transform
%dw 2.0
output application/json
---
a: |20:00:00| + |PT1M1S|
Output
{
  "a": "20:01:01"
}

Time

A time in a specific TimeZone, specified as |HH:mm:ss.SSS|.

Example
|23:59:56|

TimeZone

The Time relative to Greenwich Mean Time (GMT). A TimeZone must include a + or a -. For example, |03:00| is a time, while |+03:00| is a TimeZone.

Example
|-08:00|

Date Decomposition

To access the different parts of the date, special selectors must be used.

Transform
%dw 2.0
output application/json
var myDate = |2003-10-01T23:57:59.700-03:00|
---
{
  year: myDate.year,
  month: myDate.month,
  day: myDate.day,
  hour: myDate.hour,
  minutes: myDate.minutes,
  seconds: myDate.seconds,
  milliseconds: myDate.milliseconds,
  nanoseconds: myDate.nanoseconds,
  quarter: myDate.quarter,
  dayOfWeek: myDate.dayOfWeek,
  dayOfYear: myDate.dayOfYear,
  offsetSeconds: myDate.offsetSeconds
}
Output
{
  "year": 2003,
  "month": 10,
  "day": 1,
  "hour": 23,
  "minutes": 57,
  "seconds": 59,
  "milliseconds": 700,
  "nanoseconds": 700000000,
  "quarter": 4,
  "dayOfWeek": 3,
  "dayOfYear": 274,
  "offsetSeconds": -10800
}

Changing the Format of a Date

To format dates and times, DataWeave supports some formatting characters that are based on the Java 8 java.time.format package, such as the y, M, and d in the date format yyyy-MM-dd. The following example formats the output of the now DataWeave function to show supported letters:

DataWeave Script
%dw 2.0
output application/json
---
[
  { "dateTime" : now() },
  { "era-G" : now() as String { format: "G"} },
  { "year-u" : now() as String {format: "u"} },
  { "year-uu" : now() as String {format: "uu"} },
  { "year-y" : now() as String { format: "y"} },
  { "year-yy" : now() as String { format: "yy"} },
  { "dayOfYear-D" : now() as String { format: "D"} },
  { "monthOfYear-MMMM": now() as String { format: "MMMM"} },
  { "monthOfYear-MMM": now() as String { format: "MMM"} },
  { "monthOfYear-MM": now() as String { format: "MM"} },
  { "monthOfYear-M": now() as String { format: "M"} },
  { "monthOfYear-LL": now() as String { format: "LL"} },
  { "monthOfYear-L": now() as String { format: "L"} },
  { "dayOfMonth-d" : now() as String {format: "d"} },
  { "quarterOfYear-qqq" : now() as String {format: "qqq"} },
  { "quarterOfYear-qq" : now() as String {format: "qq"} },
  { "quarterOfYear-q" : now() as String {format: "q"} },
  { "quarterOfYear-QQQQ" : now() as String {format: "QQQQ"} },
  { "quarterOfYear-QQQ" : now() as String {format: "QQQ"} },
  { "quarterOfYear-QQ" : now() as String {format: "QQ"} },
  { "quarterOfYear-Q" : now() as String {format: "Q"} },
  // Understand "Y" and "YY" thoroughly before using it.
  { "weekBasedYear-YY" : now() as String { format: "YY"} },
  { "weekBasedYear-Y" : now() as String { format: "Y"} },
  { "weekInYear-w" : now() as String {format: "w"} },
  { "weekInMonth-W" : now() as String {format: "W"} },
  { "dayOfWeekAbbreviatedName-E" : now() as String {format: "E"} },
  { "dayOfWeekFullName-EEEE" : now() as String {format: "EEEE"} },
  { "localizedDayOfWeek-eeee" : now() as String {format: "eeee"} },
  { "localizedDayOfWeek-eee" : now() as String {format: "eee"} },
  { "localizedDayOfWeek-ee" : now() as String {format: "ee"} },
  { "localizedDayOfWeek-e" : now() as String {format: "e"} },
  { "localizedDayOfWeek-cccc" : now() as String {format: "cccc"} },
  { "localizedDayOfWeek-ccc" : now() as String {format: "ccc"} },
  { "localizedDayOfWeek-c" : now() as String {format: "c"} },
  { "weekOfMonth-F" : now() as String {format: "F"} },
  { "amORpm-a" : now() as String {format: "a"} },
  // "h" outputs 12 o'clock as 12. Other hours match "K" output.
  { "hourOfDay1to12-h" : now() as String {format: "h"} },
  // "K" outputs 12 o'clock as 0. Other hours match "h" output.
  { "hourOfDay0to11-K" : now() as String {format: "K"} },
  { "clockHourOfAmPm-k" : now() as String {format: "k"} },
  { "hourOfDay0to23-H" : now() as String {format: "H"} },
  { "minuteOfHour-m" : now() as String {format: "m"} },
  { "secondOfMinute-s" : now() as String {format: "s"} },
  { "fractionOfSecond-S" : now() as String {format: "S"} },
  { "millisecondOfDay-A" : now() as String {format: "A"} },
  { "nanosecondCountOfSecond-n" : now() as String {format: "n"} },
  { "nanosecondCountOfDay-N" : now() as String {format: "N"} },
  { "timeZoneID-VV" : now() as String {format: "VV"} },
  { "timeZoneName-zz" : now() as String {format: "zz"} },
  { "localizedZoneOffset-zzz" : now() as String {format: "zzz"} },
  { "localizedZoneOffset-O" : now() as String {format: "O"} },
  { "timeZoneOffsetZforZero-XXX" : now() as String {format: "XXX"} },
  { "timeZoneOffsetZforZero-XX" : now() as String {format: "XX"} },
  { "timeZoneOffsetZforZero-X" : now() as String {format: "X"} },
  { "timeZoneOffset-xxx" : now() as String {format: "xxx"} },
  { "timeZoneOffset-xx" : now() as String {format: "xx"} },
  { "timeZoneOffset-x" : now() as String {format: "x"} },
  { "timeZoneOffset-Z" : now() as String {format: "Z"} } }
 ]

Notice the use of the syntax to format the date or time.

Output
[
  { "dateTime": "2019-04-10T14:20:14.271-07:00" },
  { "era-G": "AD" },
  { "year-u": "2019" },
  { "year-uu": "19" },
  { "year-y": "2019" },
  { "year-yy": "19" },
  { "dayOfYear-D": "100" },
  { "monthOfYear-MMMM": "April" },
  { "monthOfYear-MMM": "Apr" },
  { "monthOfYear-MM": "04" },
  { "monthOfYear-M": "4" },
  { "monthOfYear-LL": "04" },
  { "monthOfYear-L": "4" },
  { "dayOfMonth-d": "10" },
  { "quarterOfYear-qqq": "2" },
  { "quarterOfYear-qq": "02" },
  { "quarterOfYear-q": "2" },
  { "quarterOfYear-QQQQ": "2nd quarter" },
  { "quarterOfYear-QQQ": "Q2" },
  { "quarterOfYear-QQ": "02" },
  { "quarterOfYear-Q": "2" },
  { "weekBasedYear-YY": "19" },
  { "weekBasedYear-Y": "2019" },
  { "weekInYear-w": "15" },
  { "weekInMonth-W": "2" },
  { "dayOfWeekAbbreviatedName-E": "Wed" },
  { "dayOfWeekFullName-EEEE": "Wednesday" },
  { "localizedDayOfWeek-eeee": "Wednesday" },
  { "localizedDayOfWeek-eee": "Wed" },
  { "localizedDayOfWeek-ee": "04" },
  { "localizedDayOfWeek-e": "4" },
  { "localizedDayOfWeek-cccc": "Wednesday" },
  { "localizedDayOfWeek-ccc": "Wed" },
  { "localizedDayOfWeek-c": "4" },
  { "weekOfMonth-F": "3" },
  { "amORpm-a": "PM" },
  { "hourOfDay1to12-h": "2" },
  { "hourOfDay0to11-K": "2" },
  { "clockHourOfAmPm-k": "14" },
  { "hourOfDay0to23-H": "14" },
  { "minuteOfHour-m": "20" },
  { "secondOfMinute-s": "14" },
  { "fractionOfSecond-S": "2" },
  { "millisecondOfDay-A": "51614271" },
  { "nanosecondCountOfSecond-n": "271000000" },
  { "nanosecondCountOfDay-N": "51614271000000" },
  { "timeZoneID-VV": "America/Los_Angeles" },
  { "timeZoneName-zz": "PDT" },
  { "localizedZoneOffset-zzz": "GMT-07:00" },
  { "localizedZoneOffset-O": "GMT-7" },
  { "timeZoneOffsetZforZero-XXX": "-07:00" },
  { "timeZoneOffsetZforZero-XX": "-0700" },
  { "timeZoneOffsetZforZero-X": "-07" },
  { "timeZoneOffset-xxx": "-07:00" },
  { "timeZoneOffset-xx": "-0700" },
  { "timeZoneOffset-x": "-07" },
  { "timeZoneOffset-Z": "-0700" }
]

You can combine the formatting letters to write supported date an time formats into a string, using as in the following way:

Transform
%dw 2.0
output application/json
---
formattedDate: |2003-10-01T23:57:59| as String {format: "yyyy-MM-dd"}
Output
{ "formattedDate": "2003-10-01" }

For multiple, similar conversions in your script, you might want to define a custom type as a directive in the header and set each date to that type.

Transform
%dw 2.0
output application/json
type Mydate = String { format: "yyyy/MM/dd" }
---
{
  formattedDate1: |2003-10-01T23:57:59| as Mydate,
  formattedDate2: |2015-07-06T08:53:15| as Mydate
}
Output
{
  "formattedDate1": "2003/10/01",
  "formattedDate2": "2015/07/06"
}

Note that type names are case-sensitive.

Enum (dw::Core Type)

This type is based on the Enum Java class. It must always be used with the class property, specifying the full Java class name of the class, as shown in this example.

Transform
%dw 2.0
output application/java
---
"Male" as Enum {class: "com.acme.GenderEnum"}

Iterator (dw::Core Type)

The Iterator type is based on the Iterator Java class, that iterates through arrays. Iterator contains a collection and includes methods to iterate through and filter it.

Note that like the Java class, the iterator is designed to be consumed only once. For example, if a logger consumes the value, the value is no longer readable by subsequent elements in the flow.

Null (dw::Core Type)

DataWeave defines a Null data type for null values. It is important to note that null is the value, while Null is the type. DataWeave functions do not recognize Null as a null value.

You can determine whether a DataWeave function accepts null values by looking in the DataWeave reference documentation for a function signature that accepts a Null type. For example, the flatten function has two function signatures, one of which is flatten(Null): Null. The signature indicates that flatten can accept null values. The ++ (concatenate) function, which lacks a signature for handling value so the Null type, does not accept null.

  • flatten([[1],2,[null],null]) returns [1,2,null,null]

  • "a" ++ null returns the error Unable to call `++` with (`String`, `Null`).

Number (dw::Core Type)

There is only one Number type that supports both floating point and integer numbers. There is no loss of precision in any operation, the engine always stores the data in the most performant way that does not compromise precision.

Object (dw::Core Type)

Represents any object as a collection of Key:value pairs, where a Key is composed of a Name and Attributes.

The Name type is composed of a String as the local name and the Namespace. Attributes is composed of an Array of Name:value pairs. Note that the Key is not a String, so it is not possible to compare keys. However, you can get the local name by performing an as String type coercion on any value of type Key.

Example
%dw 2.0
output application/json
---
{
  name: "Annie"
}

Single Value Objects

If an Object has only one key:value pair, the enclosing curly brackets { } are not required:

Example
%dw 2.0
output application/json
---
name: "Annie"

Conditional Elements

Objects can define conditional key-value pairs based on a conditional expression. Conditional elements have the form (key:value) if condition.

%dw 2.0
output application/xml encoding="UTF-8"
---
file: {
  name: "transform",
  (extension: "zip") if payload.fileSystem?
}

This example outputs an additional field called "extension" only when the fileSystem property is present in payload (this field may contain any value, not just true).

<?xml version="1.0" encoding="UTF-8"?>
<file>
  <name>transform</name>
  <extension>zip</extension>
</file>

If absent:

<?xml version="1.0" encoding="UTF-8"?>
<file>
  <name>transform</name>
</file>

Dynamic Keys

To specify a key through an expression, you need to wrap the expression in parentheses.

Transform
%dw 2.0
output application/json
var dynamicKey = "language"
---
{
  (dynamicKey): "Data Weave"
}
Output
{
  "language": "Data Weave"
}

Dynamic Elements

Dynamic elements allow you to add the result of an expression as key:value pairs of an object. That expression must be either an object or an array of objects.

Transform
%dw 2.0
output application/json
var x = [
  {b: "b"},
  {c: "c", d: "d"}
]
var y = {e: "e"}
---
{
  a: "a",
  (x),
  (y)
}

It is important to note that the expression between the parentheses (such as (x) where x is the variable shown in the header) should return an array of objects. All of objects in that array get merged together. They are also merged with the contained object. So the output looks like this:

Output
{
  "a": "a",
  "b": "b",
  "c": "c",
  "d": "d",
  "e": "e"
}

Conditional XML Attributes

You might want your output to only include certain XML attributes based on a condition. Conditional elements have the form (key:value) if condition

Transform
%dw 2.0
output application/xml
---
{
  name @(
    (company: "Acme") if false,
    (transform: "Anything") if true
  ): "DataWeave"
}
Output
<?xml version='1.0' encoding='US-ASCII'?>
<name transform="Anything">DataWeave</name>

Dynamic XML Attributes

You might want to include a changing set of key:value pairs in a specific location as XML attributes.

Input
{
  "company": "Mule",
  "product": "DataWeave"
}
Transform
%dw 2.0
output application/xml
---
transformation @((payload)): "Transform from anything to anything"
Output
<?xml version='1.0' encoding='US-ASCII'?>
<transformation company="Mule" product="DataWeave">Transform from anything to anything</transformation>

Regex (dw::Core Type)

Regular Expressions are defined between /. For example /\d+/ represents multiple numerical digits from 0-9. These may be used as arguments in certain operations that act upon strings, like Matches or Replace, or on operations that act upon objects and arrays, such as filters.

String (dw::Core Type)

A string can be defined by the use of double quotes or single quotes.

{
  doubleQuoted: "Hello",
  singleQuoted: 'Hello',
}

Escaping Special Characters

Use the backslash (\) to escape special characters in an input string:

  • $: You need to escape any use of of $ in a string. Otherwise, DataWeave treats the $ as an unnamed parameter for a function and returns the error Unable to resolve reference of $..

  • ": For a string that is surrounded by double quotes, you need to escape any double quote that is part of the string, for example, "a\"bcdef". Here, the second double-quote is part of the string that starts with an a and ends with f.

  • ' For a string that is surrounded by single quotes, you need to escape any single quote that is part of the string: for example, 'abcd\'e"f'. In this example, the second single quote is part of the string that starts with an a and ends with f. Notice that you do not need to escape the double quote in this case.

  • `: For a string that is surrounded by backticks (supported in DataWeave 2.0), you must escape any backtick that is part of the string: for example, `abc\`def`.

  • \: Because the backslash is the character you use to escape other special characters, you need to escape it with a separate backslash to use it in a string, for example,\\.

  • \n: For inserting a new line.

  • \t: For inserting a tab.

  • \u: For inserting a unicode character, such as \u25c4.

String Interpolation

String interpolation allows you to embed variables or expressions directly in a string. The expression need to be enclosed ($( <expression> )), and it should always return String type or something that is coercible to String.

%dw 2.0
output application/json
var name = "Shoki"
---
{
    Greeting: "Hi, my name is $name",
    Sum: "1 + 1 = $(1 + 1)"
}
Output
{
  "Greeting": "Hi, my name is Shoki",
  "Sum": "1 + 1 = 2"
}

TryResult (dw::Runtime Type)

Evaluates the delegate and returns an object with the result or an error message. See the try example. A successful TryResult contains the result field and a success value of true. An unsuccessful TryResult contains the error field and a success value of false.

Definition
{
  success: Boolean,
  result?: T,
  error?: {
    kind: String,
    message: String,
    stack?: Array<String>,
    location?: String
  }
}

URI Types (dw::core::URL)

Functions in the URI function module can return a URI data type.

Definition:
{
  isValid: Boolean,
  host?: String,
  authority?: String,
  fragment?: String,
  path?: String,
  port?: Number,
  query?: String,
  scheme?: String,
  user?: String,
  isAbsolute?: Boolean,
  isOpaque?: Boolean
}

The URI type consists of the following fields:

  • isValid: Boolean that indicates whether the URI is valid. Invalid characters include <, >, and blank spaces.

  • host: String representing the host name (for example, my.company.com from http://my.company.com:8080/hello)

  • authority: String representing the authority, which includes the host and port (for example, my.company.com:8080 from http://my.company.com:8080/hello). Returns the port only if it is explicitly specified in the URI.

  • fragment: String representing the subordinate resource after the # in the URI (for example, footer in the URI "https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#footer").

  • path: String representing a path following the host or authority (for example, /hello in http://my.company.com:8080/hello) .

  • port: Number representing an explicit port in the URI (for example, 8080 in http://my.company.com:8080/hello). If no port is specified (for example, http://my.company.com/hello), the value of the port field is null.

  • query: String identifying a query portion of a URI (for example, field=value in 'http://my.company.com:1234/hello/?field=value').

  • scheme: String identifying the URI scheme, such as https or http, which appears before a colon (:).

  • user: String representing user information in a URI (for example, the myname in http://myname@www.mycompany.com).

  • isAbsolute: Boolean value of true if the URI contains a scheme, false if the URI does not (for example, a relative URI such as /path/to/somewhere).

  • isOpaque: Boolean value of true if the URI lacks a scheme followed by forward slashes (/). mailto:somebody@somewhere.com returns true.

The following DataWeave script uses the parseURI function to return and access values to fields from a URI type. Note that fields with null values (for example, the URI defined by uriDataTypeEx) are not returned unless you explicitly select them.

DataWeave Script
%dw 2.0
import * from dw::core::URL
var uriDataTypeEx = "https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#footer"
var queryStringsEx = 'http://my.company.com:1234/hello/?field=value'
output application/json
---
{
    'myUriDataTypeEx': parseURI(uriDataTypeEx),
    // queryStringsEx has a query string:
    'myQueryStringsEx': parseURI(queryStringsEx).query,
    // uriDataTypeEx lacks a query string:
    'myQueryStringNullEx': parseURI(uriDataTypeEx).query,
    // The URI includes the port number:
    'myAuthorityEx': parseURI('http://localhost:8080/test').authority
}
Output
{
  "myUriDataTypeEx": {
    "isValid": true,
    "raw": "https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#footer",
    "host": "en.wikipedia.org",
    "authority": "en.wikipedia.org",
    "fragment": "footer",
    "path": "/wiki/Uniform_Resource_Identifier",
    "scheme": "https",
    "isAbsolute": true,
    "isOpaque": false
  },
  "myQueryStringsEx": "field=value",
  "myQueryStringNullEx": null,
  "myAuthorityEx": "localhost:8080"
}