Skip to content

CEL extensions#

This page documents the variables, custom functions, and overloads that Protovalidate adds to Common Expression Language (CEL). All standard rules are defined in CEL expressions and often leverage these Protovalidate-specific CEL extensions.

They are all available in any custom or predefined rule's CEL expression unless otherwise noted.

Variables#

this#

this refers to the current value. When defining a field rule, this refers to the value of the field. When defining a message rule, this refers to the message itself. Its fields can be accessed via dot notation.

Protobuf fields are converted to CEL types. For example, a Protobuf int32 or int64 field becomes a CEL int. See the section on Protocol Buffer Data Conversion in the CEL language reference. When comparing this against literal values, make sure to use the appropriate literal, for example 1u for an unsigned integer, and 1.0 for a double. If needed, you can convert types with CEL's conversion functions, for example uint(1).

now#

now is a google.protobuf.Timestamp. It's computed once per expression: now == now always evaluates to true.

rule#

Only available within predefined rules.

rule refers to the value assigned to a predefined rule when used as a field within a Protobuf message. See complex predefined rules for an example.

rules#

Only available within predefined rules.

Within a predefined rule, rules is an instance of the underlying Protovalidate rule message being extended. For example, the rules variable made available to a CEL expression for a predefined rule extending StringRules is an instance of the StringRules message itself. You cannot access your extension field on rules, but it's available in the rule variable. See complex predefined rules for an example.

Double functions#

Protovalidate adds the following extensions functions to CEL's double type.

isInf#

double.isInf() -> bool

Tests whether the double is an infinity.

isNan#

double.isNan() -> bool

Tests whether the double is NaN. Returns false when isInf() is true.

Int functions#

Protovalidate adds the following extensions functions to CEL's int type.

isInf#

int.isInf() -> bool

Tests whether the int is an infinity.

String functions#

Protovalidate adds the following extensions functions to CEL's string type.

isEmail#

string.isEmail() -> bool

Test whether the string is a valid email address.

isHostAndPort#

string.isHostAndPort(bool) -> bool

Test whether the string is a valid host/port pair. The single bool argument is required, and if it's true, the port is also required—otherwise, the port is optional.

isHostname#

string.isHostname() -> bool

Test whether the string is a valid hostname.

isIp#

string.isIp() -> bool

Test whether the string is a valid IP address in either IPv4 or IPv6.

string.isIp(int) -> bool

Test whether the string is a valid IP address in a specific IP version. Versions other than 0, 4, or 6 always return false.

isIpPrefix#

string.isIpPrefix() -> bool

Test whether the string is a valid IP with prefix length.

string.isIpPrefix(int) -> bool

Test whether the string is a valid IP with prefix length in a specific IP version. Versions other than 0, 4, or 6 always return false.

string.isIpPrefix(bool) -> bool

Test whether the string is a valid IP with prefix length and an appropriate network address.

string.isIpPrefix(int, bool) -> bool

Test whether the string is a valid IP with prefix length in a specific IP version and an appropriate network address. IP versions other than 0, 4, or 6 always return false.

isUri#

string.isUri() -> bool

Tests whether the string is a valid absolute URI.

isUriRef#

string.isUriRef() -> bool

Tests whether the string is a valid (absolute or relative) URI.

List functions#

Protovalidate adds the following extensions functions to CEL's list type.

unique#

list.unique() -> bool

Test whether the items in the list are all unique. It can be used with lists of the following types:

  • bool
  • bytes
  • double
  • int
  • string
  • uint

Overloads#

Protovalidate overloads the following CEL functions:

contains#

bytes.contains(bytes) -> bool

Overload of the CEL standard contains to support bytes.

endsWith#

bytes.endsWith(bytes) -> bool

Overload of the CEL standard endsWith to support bytes.

startsWith#

bytes.startsWith(bytes) -> bool

Overload of the CEL standard startsWith to support bytes.

Further reading#

Learn about all CEL variables and functions within its language definition.