---

The Complete Guide to XML Transformation in Ballerina: From Zero to Hero

Master XML transformation in Ballerina by effortlessly reading, processing, and aggregating data from an input file into a new, structured XML output. This guide leverages Ballerina's powerful query expressions and native, type-safe XML features to build a robust data processing solution from scratch, a core skill for any integration developer.

You've been there before. A client or another department hands you a massive XML file, a relic from a legacy system, and says, "We need a summary report from this." Your mind immediately jumps to clunky libraries, endless loops, and painful string parsing in languages not built for the task. The process is often error-prone, verbose, and a nightmare to maintain. What if there was a better way? A modern, cloud-native language designed to make this exact task feel intuitive and elegant?

This is where Ballerina shines. In this comprehensive guide, we'll tackle a real-world problem from the exclusive kodikra.com learning path: processing employee fuel expense records from a raw XML file. We will not only build a complete solution but also dive deep into the "why" behind Ballerina's powerful XML capabilities. You will learn to read, query, group, and transform XML data, producing a clean, aggregated output file with surprising simplicity and power.

---

What is XML Transformation in Ballerina?

XML (eXtensible Markup Language) transformation is the process of converting an XML document from one structure to another. This can involve filtering data, aggregating values, renaming elements, or completely reshaping the document's hierarchy. In many enterprise environments, this is a daily necessity for tasks like generating reports, integrating disparate systems, or preparing data for APIs.

In Ballerina, this isn't an afterthought handled by a third-party library; it's a core, first-class feature. Ballerina has a built-in type called xml. This isn't just a string representation; it's a rich, navigable data structure that understands XML concepts like elements, attributes, and text content natively. This deep integration allows developers to write code that is not only highly readable but also type-safe and performant.

The centerpiece of Ballerina's XML functionality is its integrated query expression syntax, which is heavily inspired by SQL and XQuery. This allows you to write declarative queries directly within your Ballerina code to filter, join, group, and select data from XML structures. Instead of writing complex, nested loops to parse a document, you can express your intent in a few lines of clear, concise code.

// A simple example of Ballerina's XML literal and query
import ballerina/io;

public function main() {
    // Natively define an XML structure
    xml bookData = xml `
        
            
                
                F. Scott Fitzgerald
            
            
                
                Stephen Hawking
            
        
    `;

    // Use a query expression to find the title of the fiction book
    string|error fictionTitle = from xml:Element book in bookData/book
                                where book.category == "fiction"
                                select book.title.getTextValue();

    if fictionTitle is string {
        io:println(fictionTitle); // Output: The Great Gatsby
    }
}

This native support makes Ballerina an exceptionally powerful tool for any developer working in environments where XML is prevalent, such as finance, telecommunications, and enterprise application integration (EAI).

---

Why Use Ballerina for XML Processing?

While many languages can process XML, Ballerina is uniquely architected for it. The language designers understood that data integration is a primary use case for a modern programming language, and they built features directly into the syntax and type system to address this. This design philosophy provides several compelling advantages over traditional approaches in languages like Java, Python, or Node.js.

The Power of Integrated Query Expressions

The most significant advantage is the language-integrated query syntax. In other languages, you typically need to learn a separate library's API (like lxml in Python or JAXB/DOM in Java), which often feels disconnected from the core language. Ballerina’s from...where...select clauses are part of the language itself, making the code more cohesive and easier for developers to read and write.

Type Safety and Immutability

Ballerina's xml type is immutable by default. When you perform a transformation, you are creating a new xml value rather than modifying the original one in place. This functional approach eliminates a whole class of bugs related to side effects and makes your data processing pipelines more predictable and reliable. Furthermore, the compiler can check your XML navigation paths to a degree, catching potential errors at compile time rather than runtime.

Seamless Data Binding

While this guide focuses on direct XML manipulation, Ballerina also offers powerful data binding capabilities. You can easily convert XML data into Ballerina records (structs) and back again. This allows you to work with strongly-typed objects within your business logic, gaining the benefits of compile-time checks and IDE autocompletion, while still being able to serialize the final result back to XML effortlessly.

Pros and Cons of Ballerina for XML Transformation

To provide a balanced view, let's analyze the strengths and potential challenges of using Ballerina for this task.

Feature / Aspect	Pros (Advantages)	Cons (Potential Risks)
Query Syntax	Language-integrated query expressions (similar to SQL/LINQ) make code highly declarative and readable. Reduces boilerplate code significantly.	Developers unfamiliar with declarative query syntax might face a slight learning curve compared to imperative loops.
Type System	First-class xml type provides type safety. The compiler can catch errors in navigation paths and expressions. Immutable by default, preventing side effects.	For extremely dynamic or malformed XML, the strict type system might require more explicit error handling and type casting.
Tooling & Ecosystem	Excellent VS Code plugin with syntax highlighting and autocompletion for XML literals and queries. Standard library is rich with I/O and utility functions.	The ecosystem is younger and smaller than that of Java or Python, so there are fewer third-party libraries for very niche XML-related tasks.
Performance	Compiled to Java bytecode, offering strong performance for data processing tasks. The underlying implementation is optimized for XML manipulation.	For extremely large XML files (multiple gigabytes), a streaming parser approach (which Ballerina also supports) might be necessary to manage memory consumption.

---

How to Implement the Fuel Transformation: A Step-by-Step Guide

Now, let's get our hands dirty and solve the core problem from the kodikra.com module. The task is to read an XML file containing multiple fuel records, group them by employee, sum their fuel liters and costs, and write a new, summarized XML file.

The Overall Logic Flow

Before diving into the code, let's visualize the high-level process. We will read a source file, apply our Ballerina logic, and produce a target file. The core transformation happens entirely within our program.

    ● Start
    │
    ▼
  ┌─────────────────┐
  │  Input XML File │
  │ (fuel_logs.xml) │
  └────────┬────────┘
           │
           │ Reads
           ▼
  ╔═════════════════════════╗
  ║   Ballerina Program     ║
  ║  (transformation.bal)   ║
  ╠═════════════════════════╣
  ║ 1. Parse XML into       ║
  ║    `xml` type           ║
  ║ 2. Group by employeeId  ║
  ║ 3. Sum `liters` & `cost`║
  ║ 4. Construct new XML    ║
  ╚═════════════════════════╝
           │
           │ Writes
           ▼
  ┌───────────────────┐
  │  Output XML File  │
  │ (summary_report.xml) │
  └─────────┬─────────┘
            │
            ▼
        ● End

Step 1: Setting Up Your Ballerina Project

First, ensure you have Ballerina installed. Then, create a new project. Open your terminal and run the following commands:

# Create a new Ballerina project named 'xml_transformer'
$ bal new xml_transformer

# Navigate into the newly created project directory
$ cd xml_transformer

This will create a standard Ballerina project structure. Inside this directory, create two files: fuel_logs.xml (our input) and modify the existing main.bal to house our logic.

fuel_logs.xml (Input Data):

<?xml version="1.0" encoding="UTF-8"?>
<fuelRecords>
    <fuel>
        <employeeId>E101</employeeId>
        <liters>40.5</liters>
        <cost>81.00</cost>
    </fuel>
    <fuel>
        <employeeId>E102</employeeId>
        <liters>35.0</liters>
        <cost>71.75</cost>
    </fuel>
    <fuel>
        <employeeId>E101</employeeId>
        <liters>38.2</liters>
        <cost>78.31</cost>
    </fuel>
    <fuel>
        <employeeId>E103</employeeId>
        <liters>50.0</liters>
        <cost>102.50</cost>
    </fuel>
    <fuel>
        <employeeId>E102</employeeId>
        <liters>42.8</liters>
        <cost>87.74</cost>
    </fuel>
</fuelRecords>

Step 2: The Complete Ballerina Solution

Now, let's write the Ballerina code in main.bal. This single file contains all the logic required for the transformation.

main.bal (The Transformation Logic):

import ballerina/io;
import ballerina/lang.'float;
import ballerina/lang.'xml;

// Define constant file paths for better maintainability.
const string INPUT_XML_PATH = "fuel_logs.xml";
const string OUTPUT_XML_PATH = "summary_report.xml";

// The main function serves as the entry point for the program.
// It returns an error? type, allowing it to propagate any I/O or parsing errors.
public function main() returns error? {

    // 1. READ INPUT XML
    // Read the XML file from disk. `io:fileReadXml` returns `xml|error`.
    // The `check` keyword is used for concise error handling. If an error
    // occurs, it will be returned immediately from the main function.
    xml fuelRecords = check io:fileReadXml(INPUT_XML_PATH);

    // 2. TRANSFORM DATA USING A QUERY EXPRESSION
    // This is the core of the transformation logic.
    // The query expression processes the `fuelRecords` XML.
    xml employeeSummary = from xml:Element fuelRecord in fuelRecords/fuel
        // Group the fuel records by the text value of the  child element.
        // This creates groups of records, one for each unique employee.
        group by string employeeId = fuelRecord.employeeId.getTextValue()
        // For each group, we define two variables using 'let'.
        // `totalLiters`: Sums the 'liters' for all records in the group.
        // `totalCost`: Sums the 'cost' for all records in the group.
        // We use `xml:getFloatValue()` for safe conversion from XML text to a float.
        let decimal totalLiters = 'float:sum(...from var item in fuelRecord select xml:getFloatValue(item.liters))
        let decimal totalCost = 'float:sum(...from var item in fuelRecord select xml:getFloatValue(item.cost))
        // The 'select' clause constructs the new XML structure for each employee.
        // It creates an  element containing the aggregated data.
        select xml `
            <employee>
                <id>${employeeId}</id>
                <totalLiters>${totalLiters.toString()}</totalLiters>
                <totalCost>${totalCost.toString()}</totalCost>
            </employee>
        `;

    // 3. WRAP THE RESULTS IN A ROOT ELEMENT
    // The query returns a sequence of  elements. We need to wrap them
    // in a single root element, , to form a valid XML document.
    xml finalReport = xml `<fuelSummary>${employeeSummary}</fuelSummary>`;

    // 4. WRITE OUTPUT XML
    // Write the final, transformed XML to the output file.
    // Again, `check` is used for handling potential I/O errors.
    check io:fileWriteXml(OUTPUT_XML_PATH, finalReport);

    // Print a success message to the console.
    io:println("Successfully transformed XML and saved to ", OUTPUT_XML_PATH);
}

Step 3: Running the Program

With both files in place, execute the program from your terminal:

# Run the Ballerina program
$ bal run

If successful, you will see the output: Successfully transformed XML and saved to summary_report.xml. A new file, summary_report.xml, will be created in your project directory with the following content:

summary_report.xml (Output Data):

<?xml version="1.0" encoding="UTF-8"?>
<fuelSummary>
    <employee>
        <id>E101</id>
        <totalLiters>78.7</totalLiters>
        <totalCost>159.31</totalCost>
    </employee>
    <employee>
        <id>E102</id>
        <totalLiters>77.8</totalLiters>
        <totalCost>159.49</totalCost>
    </employee>
    <employee>
        <id>E103</id>
        <totalLiters>50.0</totalLiters>
        <totalCost>102.5</totalCost>
    </employee>
</fuelSummary>

Detailed Code Walkthrough

Let's dissect the core query expression, as this is where the magic happens. Understanding this logic is key to mastering data manipulation in Ballerina.

    ● Start Query on `fuelRecords`
    │
    ├─> from xml:Element fuelRecord in fuelRecords/fuel
    │   (Iterates over each `` element)
    │
    ▼
  ┌───────────────────────────────────────────────┐
  │ group by string employeeId = ...getTextValue()│
  └──────────────────────┬────────────────────────┘
                         │ (Creates groups: E101, E102, E103)
                         │
     ╭───────────────────┴───────────────────╮
     │                   │                   │
     ▼                   ▼                   ▼
┌───────────┐      ┌───────────┐      ┌───────────┐
│ Group E101│      │ Group E102│      │ Group E103│
└─────┬─────┘      └─────┬─────┘      └─────┬─────┘
      │                  │                   │
      ├─> let totalLiters = sum(...)         │
      │   let totalCost = sum(...)           │
      │                                      │
      ├───────────────────> let totalLiters = sum(...)
      │                   │   let totalCost = sum(...)
      │                   │
      ├──────────────────────────────────────> let totalLiters = sum(...)
      │                                          let totalCost = sum(...)
      │
      ▼
  ┌──────────────────────────────────────────┐
  │ select xml `<employee>...</employee>`   │
  └───────────────────┬──────────────────────┘
                      │ (Constructs new XML for each group)
                      │
                      ▼
                  ● End Query (Returns a sequence of `` elements)

• from xml:Element fuelRecord in fuelRecords/fuel: This is the iteration clause. It loops through each child element named fuel within the top-level fuelRecords XML. Each fuel element is assigned to the variable fuelRecord.
• group by string employeeId = fuelRecord.employeeId.getTextValue(): This is the aggregation clause. It tells the query to group all the fuelRecord items based on the text content of their employeeId child element. The result of this grouping is a set of streams, one for each unique employee ID ("E101", "E102", etc.). The unique ID itself is stored in the employeeId variable.
• let decimal totalLiters = ... and let decimal totalCost = ...: These are intermediate variable declarations that operate on each group created by the group by clause.
  • 'float:sum(...): We use the built-in sum function from the ballerina/lang.'float module.
  • ...from var item in fuelRecord select xml:getFloatValue(item.liters): This is a nested query expression that creates a stream of numbers. For each item in the current group (which is a collection of fuelRecord elements), it extracts the liters value, safely converts it to a float using xml:getFloatValue, and adds it to the stream. The sum function then calculates the total.
• select xml `...`: This is the projection clause. For each group, it constructs a new xml literal. The variables defined in the group by (employeeId) and let (totalLiters, totalCost) clauses are available here. We use string interpolation (${...}) to embed their values directly into the new XML structure.

Finally, the result of the entire query is a sequence of the <employee> elements created by the select clause. We wrap this sequence in a single root element, <fuelSummary>, to ensure the final output is a well-formed XML document.

---

Alternative Approaches and Future-Proofing

While the direct query approach is powerful and concise, it's not the only way to handle XML in Ballerina. Understanding alternatives helps you choose the right tool for the job.

Data Binding with Records

For more complex business logic, you might prefer to work with strongly-typed Ballerina records instead of raw xml types. This approach, known as data binding, involves converting the XML data into native Ballerina data structures first.

You would define records that mirror your XML structure:

// Define a record to hold individual fuel data
type FuelRecord record {|
    string employeeId;
    decimal liters;
    decimal cost;
|};

// Define a record for the aggregated output
type EmployeeSummary record {|
    string id;
    decimal totalLiters;
    decimal totalCost;
|};

You could then convert the input XML into an array of FuelRecord, perform the aggregation using standard list operations (like .reduce() or loops) on these records, and finally, convert the resulting EmployeeSummary records back into XML.

When to use this approach? * When you have complex validation or business rules to apply to the data. * When you need to pass the data through multiple functions and want the safety of a strong type system. * When the logic is more imperative than declarative.

The trade-off is verbosity. Data binding requires more setup code (defining records, handling the conversion), whereas the direct query approach is often more succinct for pure transformation tasks.

Future Trends: Ballerina and Data Formats

As we look ahead, Ballerina's core strength remains its flexibility in handling diverse data formats. While XML is crucial for enterprise integration, JSON is the lingua franca of modern web APIs. Ballerina provides an equally powerful, first-class json type and a similar query expression syntax for working with JSON data.

Future versions of Ballerina are expected to further enhance these data manipulation capabilities, potentially with improved schema validation tools, more powerful data mapping features, and even tighter integration with formats like Avro and Protocol Buffers. Learning Ballerina's approach to data transformation today prepares you for a future where developers must seamlessly work across multiple data formats. For a deeper dive into Ballerina's capabilities, explore our complete Ballerina language guide.

---

Frequently Asked Questions (FAQ)

1. Is Ballerina better than Java or Python for XML processing?

"Better" is subjective, but Ballerina is arguably more specialized for it. While Java (with JAXB/DOM/SAX) and Python (with lxml/ElementTree) are highly capable, their XML features are provided by libraries. In Ballerina, XML is a native type, and query expressions are part of the language syntax. This leads to more concise, readable, and often safer code for data integration tasks.

2. How does Ballerina handle XML namespaces?

Ballerina has full support for XML namespaces. You can define namespace prefixes using the xmlns attribute in an XML literal. When querying, you can use these prefixes to access elements and attributes within a specific namespace, ensuring your queries are precise and unambiguous.

xml data = xml `<ns:root xmlns:ns="http://example.com"><ns:item>Value</ns:item></ns:root>`;
string|error itemValue = data/ns:item.getTextValue();

3. Can I validate an XML file against a schema (XSD) in Ballerina?

Currently, the Ballerina standard library does not include a built-in function for direct XSD validation. However, this is a common enterprise requirement, and you can achieve it by using Java interoperability to call a Java-based validation library like Apache Xerces. The Ballerina team is continuously expanding the standard library, and native schema validation is a potential feature for future releases.

4. What is the difference between `getTextValue()` and casting to `string`?

When you have an XML element like <id>E101</id>, accessing .id gives you the XML element itself. To get its content, you need to extract the text. .getTextValue() is a utility function from the lang.'xml module that safely extracts the concatenated text content of an element and its children. Casting with <string> is a more direct conversion that can sometimes behave differently with mixed content. For simple text elements, getTextValue() is often the clearest and safest choice.

5. How does error handling work with XML queries?

Ballerina's query expressions are integrated with its error handling system. If a navigation path doesn't exist (e.g., you query for data/nonexistent), the result is typically an empty sequence, not an error. However, functions used within the query, like xml:getFloatValue(), will return an error if the text cannot be converted. You can handle these errors using the check keyword or traditional if-else type checks, making your data processing robust.

6. What if my input XML file is very large?

The io:fileReadXml function reads the entire file into memory, which is suitable for most files but can be an issue for gigabyte-sized documents. For such cases, Ballerina supports event-based stream parsing. This involves reading the XML piece-by-piece (e.g., on each start element, end element event) and processing it incrementally, which keeps memory usage low. This is a more advanced technique but is the standard solution for handling massive datasets.

---

Conclusion and Next Steps

You have successfully built a complete, real-world XML transformation program in Ballerina. By leveraging its native xml type and powerful query expressions, we accomplished a complex aggregation task with code that is remarkably clean, readable, and efficient. This exercise, drawn from the exclusive kodikra.com curriculum, demonstrates that Ballerina is not just another general-purpose language but a finely-tuned instrument for modern data integration.

The principles you've learned here—reading data, applying declarative transformations, and writing structured output—are fundamental skills for any backend or integration developer. As you continue your journey, challenge yourself to apply these techniques to other data formats like JSON and explore more advanced features like data binding and streaming parsers. This foundational knowledge makes you well-equipped to tackle the data-centric challenges of today's software landscape.

Ready to take the next step? Continue your learning journey by exploring the next module in the Ballerina Learning Path or by diving deeper into the language's core concepts in our comprehensive Ballerina guide.

Disclaimer: The code in this article is written for Ballerina Swan Lake Update 8 (2201.8.0) and later. Syntax and standard library functions may differ in other versions. Always consult the official documentation for the version you are using.

---

Published by Kodikra — Your trusted Ballerina learning resource.