Event Gateway expressions language

In Kong Event Gateway, you can use expressions in a policy’s condition field to determine whether the policy should execute. Some policies also accept expressions in other fields, to compute a dynamic value such as a list of fields to encrypt.

Event Gateway expressions are written in Common Expression Language (CEL), wrapped in double curly braces. For example, this condition selects all topics that end with the suffix my_suffix:

{"condition": "{{context.topic.name.endsWith(\"my_suffix\")}}"}

Conditions must be between 1 and 1000 characters long.

Legacy syntax: Expressions without the double curly brace wrapper are parsed as Event Gateway’s older JavaScript-subset syntax, which is still supported but will be deprecated in a future update. See Legacy JavaScript-style syntax.

A predicate is the basic unit of an expression and compares a field against a value:

context.topic.name == "my_topic"

This predicate has the following structure:

The context. prefix is optional. topic.name == "my_topic" and context.topic.name == "my_topic" are equivalent.

Multiple predicates can be combined using logical operators:

Depending on where an expression is authored, the fields available in the context vary. The source of truth for these is the x-expression vendor extension in the API specification, which marks a field as expecting a boolean expression (like condition) or a string expression (like principal_mapping).

principal_mapping expressions only have access to context.certificate. They can’t reference context.auth, context.topic, or record, since no connection or record exists yet at certificate mapping time.

Regular expression matching follows RE2 syntax. Event Gateway doesn’t support a default() or other fallback function for CEL expressions. An expression that accesses a field that isn’t present, or a record.value.schema.*/record.key.schema.* field gated to a higher min_runtime_version, is rejected at configuration time rather than allowed to fail at runtime. Check for optional fields with has() and version-gate your policies with min_runtime_version instead.

Don’t apply a policy if a record has an x-restricted=true header and the user isn’t an admin:

context.topic.name == "filterdemo" && record.headers["x-restricted"] == "true" && context.auth.principal.name != "admin"

Apply a policy only for user1 and user2:

context.auth.principal.name == "user1" || context.auth.principal.name == "user2"

Apply a policy only for topics that start with my-prefix:

context.topic.name.startsWith("my-prefix")

Apply a policy if a header is present, regardless of value:

"x-optional-header" in record.headers

Apply a policy if the topic is filterdemo and the record content has a field foo equal to bar, or a field sub.other equal to 3:

context.topic.name == "filterdemo" && record.value.content["foo"] == "bar" || record.value.content["sub.other"] == 3

Compute a dynamic list of fields to encrypt, based on the principal’s identity:

context.auth.principal.name == "external-partner" ? ["personal.ssn", "personal.name"] : []

Apply a policy only when the record’s schema is tagged as PII in the Confluent schema registry v1.3+:

'PII' in record.value.schema.metadata.tags

Apply a policy only to schemas owned by the payments-team, based on a schema registry property v1.3+:

'owner' in record.value.schema.metadata.properties && record.value.schema.metadata.properties['owner'] == 'payments-team'

Event Gateway originally shipped with an expression language based on a subset of JavaScript, and has now moved to CEL. CEL is a widely adopted standard with a stricter, better-specified grammar than a JavaScript subset, and gives Event Gateway room to support additional CEL-native capabilities over time.

Both syntaxes are accepted today. The notation you use decides which one parses your condition (and other expression fields):

• Wrapped in double curly braces: Parsed as CEL.
• Not wrapped: Parsed as the legacy JavaScript-style syntax.

CEL uses this same double curly brace wrapper for every field type: a boolean field like condition, a string field like principal_mapping, and a list field like encrypt_fields[].paths are all wrapped the same way. The legacy syntax treats the fields differently: condition is unwrapped, but other string fields use ${...} template literals instead.

Existing expressions written in the legacy syntax continue to work unchanged, but the legacy syntax will be deprecated in a future update. We recommend migrating existing expressions to CEL syntax, and creating all new expressions in CEL.

Syntax comparison

The fields available to an expression are the same in both syntaxes. Only the notation for accessing and comparing them differs.

Some fields that accept secret and environment references, such as encrypt_fields[].encryption_key, are also sensitive fields.

• A sensitive field that’s set to a literal value is encrypted at rest and never returned in API responses.
• A sensitive field that’s set to an expression is stored and returned as the expression itself, not encrypted, since the actual secret isn’t known until the expression resolves at runtime.

Example migrations

Legacy JavaScript-style syntax

The following reference covers the JavaScript-subset syntax used when an expression isn’t wrapped in double curly braces. The available fields are the same as for CEL; only the operators and functions are different.

Supported operators and expressions

Event Gateway supports the following operators and expressions in the legacy syntax:

Legacy string functions

• includes: Performs a case-sensitive search to determine whether a given string may be found within this string, as defined in the JavaScript standard.
• startsWith: Determines whether the string begins with the characters of a specified string, equivalent to the JavaScript standard function.
• endsWith: Determines whether the string ends with the characters of a specified string, equivalent to the JavaScript standard function.
• substring: Returns the part of this string from the start index up to and excluding the end index.
• match: Retrieves the result of matching this string against an RE2 regular expression string.
• length: Returns the number of characters in the string.