Introduction

Ballerina is a compiled, statically typed, concurrent-first programming language designed for plain data and networked applications. It is built for the kinds of programs developers write every day — services that receive, transform, and forward structured data across a network.

This guide covers the language from first principles: its structural type system, worker-based concurrency, and data-oriented design. It is intended for developers who want to understand how Ballerina works, not just how to use it.

How to Read This Guide

Start with Getting Started to install Ballerina and run your first program. Then work through the Language Guide chapters in order — each chapter builds on the previous one.

The Reference section (work in progress) provides detailed coverage of every language construct, organized by category. Use it as a lookup companion while reading the chapters.

What Makes Ballerina Different

• Plain data type system — The type system is designed around network-safe data. Types are structural and semantically subtyped, making it straightforward to model and evolve data structures without boilerplate or rigid nominal hierarchies.
• Network primitives — First-class support for networked programming, with built-in types and libraries for HTTP, WebSockets, gRPC, and more.
• Workers — Lightweight, first-class concurrent execution units that communicate through typed message-passing channels.
• Error handling — Errors are values, not exceptions. Error handling is explicit and composable, with no hidden control flow.
• Immutability — readonly and isolated enforce deep immutability and safe data sharing.

Playground

Throughout this guide, interactive examples are provided using the online playground. The playground runs entirely in your browser — no installation required.

It uses a lightweight, interpreter-based reference implementation of Ballerina Swan Lake 2024R1, written in Rust and compiled to WebAssembly by the author of this guide. Because it is an interpreter rather than a full compiler, and a separate implementation from the official JBallerina, some behaviour may differ from a local Ballerina installation. It may also not support every language feature covered in the guide.

The playground supports the following libraries:

• ballerina/lang.*
• ballerina/io (limited API set)
• ballerina/test (limited API set)

Try the Debugger

The example below is designed to exercise the full debug toolbar:

• ▶ Run — run to completion
• 🐛 Debug → ⤵ Step Over — step over each statement without entering functions
• ⤵ Step Over then ↴ Step Into on the greet(name) or sum(arr) call lines — enters the function body; Variables and Call Stack panels update accordingly
• ↑ Step Out — exits the current function and returns to the caller
• ▶ Continue with a breakpoint (click the gutter circle on any line first) — runs until that line

import ballerina/io;

public function main() {
    string name = "Ballerina";
    string msg = greet(name);
    io:println(msg);

    int[] numbers = [3, 1, 4, 1, 5, 9, 2, 6];
    int total = sum(numbers);
    io:println("Sum = " + total.toString());

    int hi = max(total, 100);
    io:println("Max = " + hi.toString());
}

function greet(string who) returns string {
    string prefix = "Hello, ";
    return prefix + who + "!";
}

function sum(int[] arr) returns int {
    int acc = 0;
    foreach int n in arr {
        acc = acc + n;
    }
    return acc;
}

function max(int a, int b) returns int {
    if a > b {
        return a;
    }
    return b;
}