← Back to packages

Package cel.expr

Message Call

Message Comprehension

Message Constant

Message CreateList

Message CreateStruct

Message Entry

Message Expr

Message Extension

Message Ident

Message ParsedExpr

Message Select

Message SourceInfo

Message Version

Enum Component

Messages

message Call (Nested in cel.expr.Expr ) cel/expr/syntax.proto

A call expression, including calls to predefined functions and operators.

For example, value == 10, size(map_value).

Field Type Description
1 target cel.expr.Expr

The target of an method call-style expression. For example, x in x.f().
2 function string

Required. The name of the function or method being called.
3 args repeated cel.expr.Expr

The arguments.

message Comprehension (Nested in cel.expr.Expr ) cel/expr/syntax.proto

A comprehension expression applied to a list or map.

Comprehensions are not part of the core syntax, but enabled with macros. A macro matches a specific call signature within a parsed AST and replaces the call with an alternate AST block. Macro expansion happens at parse time.

The following macros are supported within CEL:

Aggregate type macros may be applied to all elements in a list or all keys in a map:

  • all, exists, exists_one - test a predicate expression against the inputs and return true if the predicate is satisfied for all, any, or only one value list.all(x, x < 10).
  • filter - test a predicate expression against the inputs and return the subset of elements which satisfy the predicate: payments.filter(p, p > 1000).
  • map - apply an expression to all elements in the input and return the output aggregate type: [1, 2, 3].map(i, i * i).

The has(m.x) macro tests whether the property x is present in struct m. The semantics of this macro depend on the type of m. For proto2 messages has(m.x) is defined as 'defined, but not set. For proto3, the macro tests whether the property is set to its default. For map and struct types, the macro tests whether the propertyxis defined onm`.

Comprehensions for the standard environment macros evaluation can be best visualized as the following pseudocode:

let `accu_var` = `accu_init`
for (let `iter_var` in `iter_range`) {
  if (!`loop_condition`) {
    break
  }
  `accu_var` = `loop_step`
}
return `result`

Comprehensions for the optional V2 macros which support map-to-map translation differ slightly from the standard environment macros in that they expose both the key or index in addition to the value for each list or map entry:

let `accu_var` = `accu_init`
for (let `iter_var`, `iter_var2` in `iter_range`) {
  if (!`loop_condition`) {
    break
  }
  `accu_var` = `loop_step`
}
return `result`
Field Type Description
1 iter_var string

The name of the first iteration variable. For the single iteration variable macros, when iter_range is a list, this variable is the list element and when the iter_range is a map, this variable is the map key.
2 iter_range cel.expr.Expr

The range over which the comprehension iterates.
3 accu_var string

The name of the variable used for accumulation of the result.
4 accu_init cel.expr.Expr

The initial value of the accumulator.
5 loop_condition cel.expr.Expr

An expression which can contain iter_var, iter_var2, and accu_var.

Returns false when the result has been computed and may be used as a hint to short-circuit the remainder of the comprehension.
6 loop_step cel.expr.Expr

An expression which can contain iter_var, iter_var2, and accu_var.

Computes the next value of accu_var.
7 result cel.expr.Expr

An expression which can contain accu_var.

Computes the result.
8 iter_var2 string

The name of the second iteration variable, empty if not set. This field is only set for comprehension v2 macros.

message Constant cel/expr/syntax.proto

Represents a primitive literal.

Named 'Constant' here for backwards compatibility.

This is similar as the primitives supported in the well-known type google.protobuf.Value, but richer so it can represent CEL's full range of primitives.

Lists and structs are not included as constants as these aggregate types may contain [Expr][cel.expr.Expr] elements which require evaluation and are thus not constant.

Examples of constants include: "hello", b'bytes', 1u, 4.2, -2, true, null.

Field Type Description
oneof constant_kind
1 null_value google.protobuf.NullValue

null value.
2 bool_value bool

boolean value.
3 int64_value int64

int64 value.
4 uint64_value uint64

uint64 value.
5 double_value double

double value.
6 string_value string

string value.
7 bytes_value bytes

bytes value.
8 duration_value google.protobuf.Duration

protobuf.Duration value.

Deprecated: duration is no longer considered a builtin cel type.
9 timestamp_value google.protobuf.Timestamp

protobuf.Timestamp value.

Deprecated: timestamp is no longer considered a builtin cel type.

message CreateList (Nested in cel.expr.Expr ) cel/expr/syntax.proto

A list creation expression.

Lists may either be homogenous, e.g. [1, 2, 3], or heterogeneous, e.g. dyn([1, 'hello', 2.0])

Field Type Description
1 elements repeated cel.expr.Expr

The elements part of the list.
2 optional_indices repeated int32

The indices within the elements list which are marked as optional elements.

When an optional-typed value is present, the value it contains is included in the list. If the optional-typed value is absent, the list element is omitted from the CreateList result.

message CreateStruct (Nested in cel.expr.Expr ) cel/expr/syntax.proto

A map or message creation expression.

Maps are constructed as {'key_name': 'value'}. Message construction is similar, but prefixed with a type name and composed of field ids: types.MyType{field_id: 'value'}.

Field Type Description
1 message_name string

The type name of the message to be created, empty when creating map literals.
2 entries repeated cel.expr.Expr.CreateStruct.Entry

The entries in the creation expression.

message Entry (Nested in cel.expr.Expr.CreateStruct ) cel/expr/syntax.proto

Represents an entry.

Field Type Description
1 id int64

Required. An id assigned to this node by the parser which is unique in a given expression tree. This is used to associate type information and other attributes to the node.
4 value cel.expr.Expr

Required. The value assigned to the key.

If the optional_entry field is true, the expression must resolve to an optional-typed value. If the optional value is present, the key will be set; however, if the optional value is absent, the key will be unset.
5 optional_entry bool

Whether the key-value pair is optional.
oneof key_kind
2 field_key string

The field key for a message creator statement.
3 map_key cel.expr.Expr

The key expression for a map creation statement.

message Expr cel/expr/syntax.proto

An abstract representation of a common expression.

Expressions are abstractly represented as a collection of identifiers, select statements, function calls, literals, and comprehensions. All operators with the exception of the '.' operator are modelled as function calls. This makes it easy to represent new operators into the existing AST.

All references within expressions must resolve to a [Decl][cel.expr.Decl] provided at type-check for an expression to be valid. A reference may either be a bare identifier name or a qualified identifier google.api.name. References may either refer to a value or a function declaration.

For example, the expression google.api.name.startsWith('expr') references the declaration google.api.name within a [Expr.Select][cel.expr.Expr.Select] expression, and the function declaration startsWith.

Field Type Description
2 id int64

Required. An id assigned to this node by the parser which is unique in a given expression tree. This is used to associate type information and other attributes to a node in the parse tree.
oneof expr_kind
3 const_expr cel.expr.Constant

A constant expression.
4 ident_expr cel.expr.Expr.Ident

An identifier expression.
5 select_expr cel.expr.Expr.Select

A field selection expression, e.g. request.auth.
6 call_expr cel.expr.Expr.Call

A call expression, including calls to predefined functions and operators.
7 list_expr cel.expr.Expr.CreateList

A list creation expression.
8 struct_expr cel.expr.Expr.CreateStruct

A map or message creation expression.
9 comprehension_expr cel.expr.Expr.Comprehension

A comprehension expression.

message Extension (Nested in cel.expr.SourceInfo ) cel/expr/syntax.proto

An extension that was requested for the source expression.

Field Type Description
1 id string

Identifier for the extension. Example: constant_folding
2 affected_components repeated cel.expr.SourceInfo.Extension.Component

If set, the listed components must understand the extension for the expression to evaluate correctly.

This field has set semantics, repeated values should be deduplicated.
3 version cel.expr.SourceInfo.Extension.Version

Version info. May be skipped if it isn't meaningful for the extension. (for example constant_folding might always be v0.0).

message Ident (Nested in cel.expr.Expr ) cel/expr/syntax.proto

An identifier expression. e.g. request.

Field Type Description
1 name string

Required. Holds a single, unqualified identifier, possibly preceded by a '.'.

Qualified names are represented by the [Expr.Select][cel.expr.Expr.Select] expression.

message ParsedExpr cel/expr/syntax.proto

An expression together with source information as returned by the parser.

Field Type Description
2 expr cel.expr.Expr

The parsed expression.
3 source_info cel.expr.SourceInfo

The source info derived from input that generated the parsed expr.

message Select (Nested in cel.expr.Expr ) cel/expr/syntax.proto

A field selection expression. e.g. request.auth.

Field Type Description
1 operand cel.expr.Expr

Required. The target of the selection expression.

For example, in the select expression request.auth, the request portion of the expression is the operand.
2 field string

Required. The name of the field to select.

For example, in the select expression request.auth, the auth portion of the expression would be the field.
3 test_only bool

Whether the select is to be interpreted as a field presence test.

This results from the macro has(request.auth).

message SourceInfo cel/expr/syntax.proto

Source information collected at parse time.

Field Type Description
1 syntax_version string

The syntax version of the source, e.g. cel1.
2 location string

The location name. All position information attached to an expression is relative to this location.

The location could be a file, UI element, or similar. For example, acme/app/AnvilPolicy.cel.
3 line_offsets repeated int32

Monotonically increasing list of code point offsets where newlines \n appear.

The line number of a given position is the index i where for a given id the line_offsets[i] < id_positions[id] < line_offsets[i+1]. The column may be derived from id_positions[id] - line_offsets[i].
4 positions map<int64, int32>

A map from the parse node id (e.g. Expr.id) to the code point offset within the source.
5 macro_calls map<int64, Expr>

A map from the parse node id where a macro replacement was made to the call Expr that resulted in a macro expansion.

For example, has(value.field) is a function call that is replaced by a test_only field selection in the AST. Likewise, the call list.exists(e, e > 10) translates to a comprehension expression. The key in the map corresponds to the expression id of the expanded macro, and the value is the call Expr that was replaced.
6 extensions repeated cel.expr.SourceInfo.Extension

A list of tags for extensions that were used while parsing or type checking the source expression. For example, optimizations that require special runtime support may be specified.

These are used to check feature support between components in separate implementations. This can be used to either skip redundant work or report an error if the extension is unsupported.

message Version (Nested in cel.expr.SourceInfo.Extension ) cel/expr/syntax.proto

Version

Field Type Description
1 major int64

Major version changes indicate different required support level from the required components.
2 minor int64

Minor version changes must not change the observed behavior from existing implementations, but may be provided informationally.

Enums

enum Component cel/expr/syntax.proto

CEL component specifier.

Name Number Description
COMPONENT_UNSPECIFIED 0

Unspecified, default.
COMPONENT_PARSER 1

Parser. Converts a CEL string to an AST.
COMPONENT_TYPE_CHECKER 2

Type checker. Checks that references in an AST are defined and types agree.
COMPONENT_RUNTIME 3

Runtime. Evaluates a parsed and optionally checked CEL AST against a context.