Foreword

I started writing this guide because I wanted a single, well-structured resource that covers the Ballerina language from first principles. The official documentation covers the language well, but it is spread across many pages and tools. This guide aims to present the language as a coherent whole — something you can read from beginning to end, or dip into when you need to look something up.

Scope

This guide focuses on language features and core programming concepts. It does not cover:

• Integration concepts or platform-specific patterns
• The Ballerina standard library beyond what is needed for examples
• Ballerina tooling, build system, or deployment

A separate guide covering integration concepts and the Ballerina platform is planned for the future.

Version

This guide targets Ballerina Swan Lake 2024R1 or later. Some features described here may not be available in earlier versions. Code examples are tested against Ballerina Swan Lake 2201.13.0+ (JBallerina).

— Hasitha Aravinda, April 2026