Ballerina Specifications
Ballerina is defined by a set of formal specifications that govern the language semantics, standard library behavior, and platform requirements. These specifications serve as the authoritative reference for language implementors, library authors, and developers who need precise behavioral definitions.
Language specification
The Ballerina Language Specification defines the syntax, type system, semantics, and execution model of the Ballerina programming language.
| Attribute | Detail |
|---|---|
| Current version | 2024R1 |
| Specification | Ballerina Language Specification |
| Status | Active, updated with each Swan Lake release |
| Format | HTML |
Specification sections
| Section | Topics Covered |
|---|---|
| Lexical Structure | Tokens, keywords, identifiers, literals, comments |
| Values, Types, and Variables | Type system, basic types, structured types, behavioral types |
| Expressions | Operators, literals, member access, function calls, query expressions |
| Statements | Variable declarations, assignments, control flow, transactions |
| Module and Program Structure | Modules, imports, visibility, program entry points |
| Concurrency | Strands, workers, isolation, transactions |
| Error Handling | Error type, check, trap, on fail |
| Type Narrowing | Type guards, type test expressions |
| Object Types | Object definitions, methods, constructors |
| Other Types | Stream, future, typedesc, handle |
Language specification versions
| Version | Swan Lake Release | Key Changes |
|---|---|---|
| 2024R1 | Swan Lake Update 9 | Regular expressions, resource method typing enhancements |
| 2023R1 | Swan Lake Update 7 | Tuple rest descriptors, isolated inference improvements |
| 2022R4 | Swan Lake Update 4 | Configurable variables refinements, query expression enhancements |
| 2022R3 | Swan Lake Update 3 | Intersection types for errors, resource methods for client objects |
| 2022R1 | Swan Lake GA | Initial Swan Lake specification |
Standard library specifications
Each standard library module has its own specification defining the module's API contract, behavior, and error semantics.
Core library specifications
| Module | Description |
|---|---|
ballerina/lang.value | Operations on all Ballerina values |
ballerina/lang.array | Array/Tuple operations (push, pop, sort, filter) |
ballerina/lang.map | Map/Record operations (get, entries, keys, values) |
ballerina/lang.string | String operations (substring, trim, split) |
ballerina/lang.int | Integer operations and limits |
ballerina/lang.float | Floating-point operations |
ballerina/lang.decimal | Decimal operations |
ballerina/lang.boolean | Boolean operations |
ballerina/lang.error | Error type operations |
ballerina/lang.xml | XML type operations |
ballerina/lang.table | Table operations |
ballerina/lang.regexp | Regular expression operations |
ballerina/lang.runtime | Runtime management operations |
ballerina/lang.transaction | Transaction management |
Network library specifications
| Module | Key Topics |
|---|---|
ballerina/http | HTTP service, client, request/response, security, interceptors |
ballerina/grpc | gRPC service, client, streaming patterns |
ballerina/graphql | GraphQL service, schema generation, subscriptions |
ballerina/websocket | WebSocket service, client, lifecycle |
ballerina/websub | WebSub subscriber, hub integration |
ballerina/tcp | TCP listener, client, byte stream handling |
ballerina/udp | UDP datagram communication |
ballerina/email | SMTP, POP3, IMAP protocols |
ballerina/ftp | FTP/SFTP client and listener |
Data library specifications
| Module | Key Topics |
|---|---|
ballerina/io | File I/O, stream I/O, console I/O |
ballerina/sql | Generic SQL client, parameterized queries, transactions |
ballerina/persist | Data persistence layer, entity modeling |
ballerina/constraint | Data validation constraints |
Platform specification
The Ballerina Platform Specification defines the build system, package management, and runtime environment.
| Attribute | Detail |
|---|---|
| Build tool | bal CLI |
| Package format | BALA (Ballerina Archive) |
| Package registry | Ballerina Central |
| Runtime | JVM-based (Java 17+) |
| Native compilation | GraalVM native image (experimental) |
Platform components
| Component | Specification Area | Description |
|---|---|---|
| Package System | Module structure, Ballerina.toml, Dependencies.toml | Package layout, dependencies, versioning |
| Build System | bal build, bal run, bal test | Compilation, execution, testing pipeline |
| Central Repository | Package publishing and resolution | Versioned package distribution |
| Type Narrowing | Flow typing and type guards | Compile-time type inference |
| Concurrency Model | Strand-based execution | Cooperative concurrency on JVM threads |
| Transaction Manager | Two-phase commit protocol | Distributed transaction coordination |
Specification versioning
Ballerina specifications follow a versioning scheme tied to Swan Lake releases.
| Scheme | Format | Example | Description |
|---|---|---|---|
| Language spec | YYYYRN | 2024R1 | Year and release number within that year |
| Distribution | YYYY.N.N | 2201.9.2 | Year, minor version, patch version |
| Module spec | Semantic versioning | 2.11.2 | Major.minor.patch per module |
Where to find specifications
| Resource | URL |
|---|---|
| Language specification (latest) | ballerina.io/spec/lang/master/ |
| Module specifications | Each module's GitHub repository under docs/spec/ |
| Swan Lake release notes | ballerina.io/downloads/swan-lake-release-notes/ |
See also
- Ballerina by Example — Runnable code examples
- Ballerina API Documentation — Module API docs
- Release Notes — Version history and migration notes