cel.md

Common Expression Language (CEL)

The Common Expression Language (CEL) is utilized by protovalidate for the formulation of validation rules, serving both as the basis for the standard constraints as well as custom constraints.

CEL features a user-friendly syntax, reminiscent of the expressions found in C, C++, Java, JavaScript, and Go.

Usage in protovalidate

The CEL expressions within protovalidate can expect to have access to the following features of the CEL language:

• CEL's standard functions, as detailed in the list of standard definitions
• CEL's standard macros
• CEL's extended string function library
• protovalidate's custom functions and overloads

protovalidate seeks to be as portable as possible. As such, providing further functionality beyond what's captured here is not recommended and not support by the library or implementations.

Custom variables, functions, and overloads

Certain pre-existing functionality inherited from protoc-gen-validate cannot be represented in CEL, requiring the usage of custom CEL functions. Below is a list of new global variables, functions and overrides to the standard functions included in protovalidate. These are free to use within custom constraints.

Symbol	Type	Description
Variables
this	dyn	The current value, referring to either a message or field's value
now	google.protobuf.Timestamp	The current timestamp, computed once per expression (i.e., now == now)
Functions
isEmail	string.isEmail() -> bool	Test whether the string is a valid email address
isHostname	string.isHostname() -> bool	Test whether the string is a valid hostname
isIp	string.isIp() -> bool string.isIp(4) -> bool string.isIp(6) -> bool	Test whether the string is a valid IP address, optionally limited to a specific version (v4 or v6)
isUriRef	string.isUriRef() -> bool	Tests whether the string is a valid (absolute or relative) URI
isUri	string.isUri() -> bool	Tests whether the string is a valid absolute URI
unique	list(bool).unique() -> bool list(int).unique() -> bool list(uint).unique() -> bool list(double).unique() -> bool list(string).unique() -> bool list(bytes).unique() -> bool	Test whether the items in the list are all unique.
Overloads
contains	bytes.contains(bytes) -> bool	Overload of the CEL standard contains to support bytes
endsWith	bytes.endsWith(bytes) -> bool	Overload of the CEL standard endWith to support bytes
startsWith	bytes.startsWith(bytes) -> bool	Overload of the CEL standard startsWith to support bytes