# 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

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 :