Read the Ballerina language specification and other specifications that cover the Ballerina library, built-in language extensions, testing, documentation, and more.
As a language, which is designed to have multiple implementations, Ballerina semantics are defined by a series of specifications and not by the implementation. Currently, there is only one implementation (i.e., jBallerina that compiles Ballerina to Java bytecodes). Others will follow including a compiler, which generates native binaries using LLVM.
Ballerina has a collection of specifications starting with the Ballerina Language Specification. Other specifications (which are yet to be moved to the specification repository or, in some cases, yet to be written) will cover the Ballerina library, built-in language extensions such as security, immutability & deprecation, module and project management, testing, documentation, compiler extensions for cloud, and Ballerina Central.
Language specifications
From the start of 2019, Ballerina specifications are versioned chronologically using the convention 20XYRn, where XY is the 2-digit year (e.g., 19), R stands for "Release" and n is the release number for that year. Prior to 2019, a semver versioning scheme was used. However, that approach was abandoned when the language specification reached 0.980.
Released specifications
Below are the most stable versions of the language specification, which are in sync with the Ballerina releases.
Note: The changes since previous releases section of the specification identifies the changes that have occurred in each version of the specification.
| Version | Release Date | Description |
|---|---|---|
| 2023R1 | 2023-07-07 | First release of 2023. This is the basis for Ballerina Swan Lake Update 7. |
| 2022R4 | 2022-12-09 | Fourth release of 2022. This is the basis for Ballerina 2201.3.0 (Swan Lake Update 3). |
| 2022R3 | 2022-08-12 | Third release of 2022. This is the basis for Ballerina 2201.2.0 (Swan Lake Update 2). |
| 2022R2 | 2022-06-02 | Second release of 2022. This is the basis for Ballerina 2201.1.0 (Swan Lake Update 1). |
| 2022R1 | 2022-01-31 | First release of 2022. This is the basis for Ballerina 2201.0.0 (Swan Lake). |
| 2021R1 | 2021-06-02 | First release of 2021. This is the basis for Ballerina Swan Lake Beta1. |
| 2020R1 | 2020-03-20 | First release of 2020. This is the basis for jBallerina 1.2.0. |
| 2019R3 | 2019-09-07 | Stable release used as the basis for jBallerina 1.0.0 implementation. Mostly a cleanup from 2019R2 |
| 2019R2 | 2019-07-01 | Major revised edition of the language |
| 2019R1 | 2019-05-01 | First release with new versioning scheme with significant revisions |
Current snapshot
For a snapshot of the current language specification including all changes, see the main language specification.
Previous drafts
For previous draft language specifications of a Ballerina release, see the draft language specification.
Ballerina library specifications
| Package | Edition | Current snapshot | Description |
|---|---|---|---|
auth | Swan Lake | Snapshot | Auth package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.). |
cache | Swan Lake | Snapshot | Cache package of Ballerina language, which provides a mechanism to manage frequently accessed data in-memory by using a semi-persistent mapping from key to value. |
constraint | Swan Lake | Snapshot | Constraint package of Ballerina language, which provides APIs to validate the values that have been assigned to Ballerina types. |
crypto | Swan Lake | Snapshot | Crypto package of Ballerina language, which provides Crypto functionalities. |
email | Swan Lake | Snapshot | Email package of Ballerina language, which provides functionalities related to sending/receiving emails via SMTP, POP3, and IMAP protocols. |
file | Swan Lake | Snapshot | File package of Ballerina language, which provides APIs to perform file, file path, and directory operations. |
ftp | Swan Lake | Snapshot | FTP package of Ballerina language, which provides FTP client/listener functionalities to send and receive files by connecting to FTP/SFTP server. |
graphql | Swan Lake | Snapshot | GraphQL package of Ballerina language, which provides GraphQL server functionalities to produce GraphQL APIs. |
grpc | Swan Lake | Snapshot | gRPC package of Ballerina language, which provides APIs for gRPC client and server implementation. |
io | Swan Lake | Snapshot | I/O package of Ballerina language, which provides file related I/O operations. |
http | Swan Lake | Snapshot | HTTP package of Ballerina language, which provides HTTP client-server functionalities to produce and consume HTTP APIs. |
jwt | Swan Lake | Snapshot | JWT package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.). |
log | Swan Lake | Snapshot | Log package of Ballerina language, which provides APIs to log information when running applications. |
mime | Swan Lake | Snapshot | MIME package of Ballerina language, which provides a set of APIs to work with messages, which follow the Multipurpose Internet Mail Extensions (MIME) specification as specified in the RFC 2045 standard. |
oauth2 | Swan Lake | Snapshot | OAuth2 package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.). |
os | Swan Lake | Snapshot | OS package of Ballerina language, which provides APIs to retrieve information about the operating system and its current users. |
protobuf | Swan Lake | Snapshot | Protobuf package of Ballerina language, which provides APIs to represent a set of pre-defined protobuf types. |
random | Swan Lake | Snapshot | Random package of Ballerina language, which provides APIs to generate pseudo-random numbers. |