Specification: Ballerina Constraint Library

Owners: @TharmiganK @shafreenAnfar @chamil321
Reviewers: @shafreenAnfar @chamil321
Created: 2022/08/09
Updated: 2022/08/09
Edition: Swan Lake

Introduction

This is the specification for the Constraint standard library of Ballerina language, which provides APIs to validate the values that have been assigned to Ballerina types.

The Constraint library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

1. Overview
2. Constraint annotations
   • 2.1. Constraint annotation on number types
   • 2.2. Constraint annotation on string type
   • 2.3. Constraint annotation on array types
3. validate function

1. Overview

Validating user input is a common requirement in most applications. This can prevent user entry errors before the app attempts to process the data. In Ballerina, such validations can be carried out by the Constraint library.

This specification elaborates on the functionalities provided by the Constraint library and how the library validates the constraints in Ballerina types.

2. Constraint annotations

The Constraint library provides different annotations for different basic types e.g. @constraint:String for strings, @constraint:Array for arrays etc. Each of these is defined as a separate associated record type.

These annotations are attached to type or record field attachment points.

The following table illustrates all the supported annotations with respect to the Ballerina types.

Ballerina Type	Annotation
int	@constraint:Int
float	@constraint:float
int|float|decimal	@constraint:Number
string	@constraint:String
any[]	@constraint:Array

2.1. Constraint annotation on number types

The Constraint library offers the following three constraint annotations on number types such as int, float and decimal.

All the supported constraints on number types are illustrated in the following table.

Constraint name	Semantics (v is value being constrained, c is constraint value)
minValue	v >= c
maxValue	v <= c
minValueExclusive	v > c
maxValueExclusive	v < c

When defining constraints on number types, either minValue or minValueExclusive can be present. Similarly, either maxValue or maxValueExclusive can be present.

Example :

2.2. Constraints annotation on string type

The following is the associated record type definition for @constraint:String annotation.

All the supported constraints on string type are illustrated in the following table.

Constraint name	Semantics (v is value being constrained, c is constraint value)
length	v.length() == c
minLength	v.length() >= c
maxLength	v.length() <= c

When defining constraints on string type, if the length constraint is present then minLength or maxLength are not allowed.

Example :

2.3. Constraint annotation on array types

The Constraint library offers the @constraint:Array annotation on Ballerina anydata[] types. The following is the associated record type definition.

All the supported constraints on array types are illustrated in the following table.

Constraint name	Semantics (v is value being constrained, c is constraint value)
length	v.length() == c
minLength	v.length() >= c
maxLength	v.length() <= c

When defining constraints on array types, if the length constraint is present then minLength or maxLength are not allowed.

Example :

3. validate function

The Constraint library has a public function : validate which should be explicitly called by the developer to validate the constraints. If the validation is successful then this function returns the type descriptor of the value which is validated, else a constraint:Error is returned.

The following is the definition of the validate function.

Example :