Ballerina specifications

Read the Ballerina language specification and other specifications that cover the standard 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 standard 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

The below are the most stable versions of the lanuguage 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.

VersionRelease DateDescription
2022R42022-12-09Fourth release of 2022. This is the basis for Ballerina 2201.3.0 (Swan Lake Update 3).
2022R32022-08-12Third release of 2022. This is the basis for Ballerina 2201.2.0 (Swan Lake Update 2).
2022R22022-06-02Second release of 2022. This is the basis for Ballerina 2201.1.0 (Swan Lake Update 1).
2022R12022-01-31First release of 2022. This is the basis for Ballerina 2201.0.0 (Swan Lake).
2021R12021-06-02First release of 2021. This is the basis for Ballerina Swan Lake Beta1.
2020R12020-03-20First release of 2020. This is the basis for jBallerina 1.2.0.
2019R32019-09-07Stable release used as the basis for jBallerina 1.0.0 implementation. Mostly a cleanup from 2019R2
2019R22019-07-01Major revised edition of the language
2019R12019-05-01First 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.

Standard library specifications

PackageEditionCurrent snapshotDescription
authSwan LakeSnapshotAuth package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.).
cacheSwan LakeSnapshotCache 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.
constraintSwan LakeSnapshotConstraint package of Ballerina language, which provides APIs to validate the values that have been assigned to Ballerina types.
cryptoSwan LakeSnapshotCrypto package of Ballerina language, which provides Crypto functionalities.
emailSwan LakeSnapshotEmail package of Ballerina language, which provides functionalities related to sending/receiving emails via SMTP, POP3, and IMAP protocols.
fileSwan LakeSnapshotFile package of Ballerina language, which provides APIs to perform file, file path, and directory operations.
ftpSwan LakeSnapshotFTP package of Ballerina language, which provides FTP client/listener functionalities to send and receive files by connecting to FTP/SFTP server.
graphqlSwan LakeSnapshotGraphQL package of Ballerina language, which provides GraphQL server functionalities to produce GraphQL APIs.
grpcSwan LakeSnapshotgRPC package of Ballerina language, which provides APIs for gRPC client and server implementation.
ioSwan LakeSnapshotI/O package of Ballerina language, which provides file related I/O operations.
httpSwan LakeSnapshotHTTP package of Ballerina language, which provides HTTP client-server functionalities to produce and consume HTTP APIs.
jwtSwan LakeSnapshotJWT package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.).
logSwan LakeSnapshotLog package of Ballerina language, which provides APIs to log information when running applications.
mimeSwan LakeSnapshotMIME 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.
oauth2Swan LakeSnapshotOAuth2 package of Ballerina language, which is used for authorization of listeners and clients (HTTP, gRPC, GraphQL, WebSocket, WebSub, etc.).
osSwan LakeSnapshotOS package of Ballerina language, which provides APIs to retrieve information about the operating system and its current users.
protobufSwan LakeSnapshotProtobuf package of Ballerina language, which provides APIs to represent a set of pre-defined protobuf types.
randomSwan LakeSnapshotRandom package of Ballerina language, which provides APIs to generate pseudo-random numbers.
regexSwan LakeSnapshotRegex package of Ballerina language, which provides functionalities such as matching, replacing and splitting strings based on regular expressions.
serdesSwan LakeSnapshotSerdes package of Ballerina language, which provides functinalities for serializing and deserializing subtypes of Ballerina anydata type.
sqlSwan LakeSnapshotSQL package of Ballerina language, which provides the generic interface and functionality to interact with a SQL database.
taskSwan LakeSnapshotTask package of Ballerina language, which provides APIs to schedule a Ballerina job either once or periodically and manage the execution of those jobs.
tcpSwan LakeSnapshotTCP package of Ballerina language, which provides TCP client-server functionalities.
timeSwan LakeSnapshotTime package of Ballerina language, which provides time generation and conversion APIs.
tomlSwan LakeSnapshotTOML package of Ballerina language, which provides APIs to convert a TOML configuration file to map<json>, and vice-versa.
udpSwan LakeSnapshotUDP package of Ballerina language, which provides UDP client-server functionalities.
uuidSwan LakeSnapshotUUID package of Ballerina language, which provides APIs to generate UUIDs based on the RFC 4122.
websocketSwan LakeSnapshotWebSocket package of Ballerina language, which provides WebSocket client-server functionalities.
websubSwan LakeSnapshotWebSub package of Ballerina language, which provides WebSub compliant subscriber related functionalities.
webusuhubSwan LakeSnapshotWebSubHub package of Ballerina language, which provides WebSub compliant hub and publisher related functionalities.
xmldataSwan LakeSnapshotXmldata package of Ballerina language, which provides APIs to perform conversions between XML and JSON/Ballerina records.
yamlSwan LakeSnapshotYAML package of Ballerina language, which provides APIs to convert a YAML configuration file to JSON, and vice-versa.

Platform specifications

SpecificationLatest released versionCurrent snapshot
Code to Cloud2022R1Snapshot
Configurable2022R1Snapshot
Language Extensions - Deprecation2022R1Snapshot
Package2022R1Snapshot
Test Framework2022R1Snapshot

Proposals for improvements/enhancements

For the proposals for improving Ballerina, see the work in progress proposals.