DataWeave Resources
DataWeave Resources is the Setup page where you view and manage the DataWeave scripts deployed to your Salesforce org.
Definition
DataWeave Resources is the Setup page where you view and manage the DataWeave scripts deployed to your Salesforce org. Each DataWeave Resource is a .dwl file (DataWeave 2.x source) that you author in your IDE, package as metadata, and deploy alongside the Apex code that calls it. Once deployed, the script appears under Setup, DataWeave Resources with its name, namespace, and the DataWeave version it targets.
DataWeave is MuleSoft's transformation language, embedded in the Salesforce platform since Winter '23. Apex code calls a script through the Dataweave.Script class, passing inputs and receiving the transformed output without writing parsing logic by hand. It is the supported way to convert between JSON, XML, CSV, and Salesforce objects when the shape of the data is complex enough that hand-rolled Apex would be brittle or unreadable.
How DataWeave Resources work in a Salesforce org
From .dwl file to deployable resource
A DataWeave Resource starts as a .dwl file in your project's force-app/main/default/dw directory. The file declares its input types, output type, and the transformation logic in DataWeave 2.x syntax. You deploy it through the standard Salesforce DX flow (sf project deploy start) and it becomes a record in the DataWeaveResource metadata type. Once deployed, the Setup page lists it; deleting from Setup is reversible only by redeploying the source.
Calling a DataWeave Resource from Apex
In Apex, you reference the script by name with Dataweave.Script.createScript('MyScript') and execute it with Dataweave.Result result = myScript.execute(new Map<String, Object>{'payload' => inputData}). The result exposes getValue() for the typed output. Errors come back as Dataweave.ScriptException with the line and column of the failing transformation, which makes debugging much easier than chasing JSON parse failures.
What DataWeave is good at versus Apex string parsing
DataWeave shines when you need to flip a deeply nested JSON payload into a different shape, merge two arrays by key, or convert between formats. Hand-rolled Apex JSON.deserialize().get() chains break the moment the input shape shifts; a DataWeave script reads almost like a schema specification of what comes out. For simple parsing (one or two fields out of a flat object), Apex's built-in JSON class is still less ceremony.
DataWeave 2.x syntax basics
A DataWeave script has three sections separated by ---. The directive section declares input variables, output format, and imports. The constant section (optional) defines reusable expressions. The body produces the output. Map, filter, reduce, and pluck functions cover most transformation needs, and the function-composition style means you express transformations declaratively rather than procedurally.
Platform limits and what to watch for
DataWeave-in-Apex runs inside the same governor-limit envelope as the calling Apex transaction. CPU time and heap consume from the same buckets, so a heavy DataWeave script on a large payload can starve the rest of the transaction. There is no separate DataWeave limit, but the Apex CPU limit (10 seconds for synchronous, 60 seconds for async) is the practical ceiling. Test with realistic payload sizes before relying on it in production.
Versioning and side-by-side scripts
DataWeave Resources are versioned by the targetdwversion attribute in the metadata. You can have multiple scripts targeting different DataWeave versions in the same org, useful when you want to upgrade gradually. The metadata also supports namespacing for managed packages: a DataWeave Resource named MyScript in namespace mynsp is referenced from Apex as Dataweave.Script.createScript('mynsp__MyScript').
MuleSoft and the broader DataWeave ecosystem
Outside Salesforce, DataWeave is the transformation language inside MuleSoft Anypoint applications, where it has lived since the original Mule 3.x. The Salesforce embedding is a deliberate alignment of platforms: scripts you write for MuleSoft are mostly portable to DataWeave Resources in Apex, modulo platform-specific functions. Teams running MuleSoft and Salesforce side-by-side can share knowledge and sometimes scripts between the two.
How to deploy and call a DataWeave Resource
DataWeave Resources are not authored in the Salesforce UI. You write the .dwl file in your IDE, deploy it as metadata, and then call it from Apex. The Setup page is for inspection only.
- Create the .dwl file
In your SFDX project, add force-app/main/default/dw/MyScript.dwl. Include the metadata XML stub MyScript.dwl-meta.xml that declares the API version. The DataWeave Extension for VS Code provides syntax highlighting and validation.
- Write the transformation
Define inputs in the directive section (%input payload application/json), declare the output format (%output application/json), and write the transformation body. Start with a small known input and the desired output, then evolve the script to bridge them.
- Deploy through Salesforce DX
Run sf project deploy start --source-dir force-app/main/default/dw. The deploy creates or updates the DataWeaveResource metadata. Confirm at Setup, then DataWeave Resources, that the new entry appears with the expected version.
- Call the script from Apex
Build the input map (Map<String, Object> inputs = new Map<String, Object>{'payload' => myPayload}). Create the script (Dataweave.Script s = Dataweave.Script.createScript('MyScript')). Execute it (Dataweave.Result r = s.execute(inputs)). Read the output (Object value = r.getValue()).
- Handle errors
Wrap the execute call in try/catch for Dataweave.ScriptException. The exception's message includes the line number in the .dwl source, which makes debugging much easier than chasing JSON parse failures.
- Add unit tests
Test the Apex wrapper with representative input payloads. Use System.assert to confirm the script produces the expected output. The DataWeave CLI also lets you test the script locally before deploy.
The current supported version. Targets DataWeave 2.x syntax. All new resources should declare this version.
Synchronous calls run within the calling transaction. No separate governor limits, but the script's CPU and heap consume from the Apex limits.
DataWeave Resources support package namespacing. Reference scripts from managed packages as namespace__ScriptName.
Conventional location is force-app/main/default/dw/. The metadata API accepts other paths if force-meta declares them, but tooling expects the conventional layout.
- DataWeave Resources are not editable from the Setup UI. The list page shows what is deployed but offers no edit button. All changes are source-controlled and redeployed.
- Heavy DataWeave scripts on large payloads burn Apex CPU. There is no separate governor envelope. Test with production-sized inputs before relying on it in a real-time path.
- Errors in DataWeave throw Dataweave.ScriptException, not standard System.JSONException. Catch the right type or the calling code will surface unexpected error shapes.
- DataWeave is generally available since Winter '23. Older orgs may need to enable it under Setup, then DataWeave Resources, then Enable DataWeave.
Trust & references
Straight from the source - Salesforce's reference material on DataWeave Resources.
- DataWeave in ApexSalesforce Help
- Dataweave Namespace ReferenceSalesforce Developers
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Governor Limit in the context of DataWeave Resources?
Q2. Where would a developer typically work with DataWeave Resources?
Q3. What skill set is typically needed to work with DataWeave Resources?
Discussion
Loading discussion…