Expression Language Syntax

Expression Language Syntax

RFC XXXX                 Expression Language Syntax               10 2024


Title: Expression Language Syntax Specification
Author: Lahiru, WSO2
Status: Informational
Date: 10 2024


Abstract

This document specifies the syntax and semantics of a simple expression language designed for data manipulation and computation within applications. The language provides mechanisms for accessing variables, payloads, performing mathematical and logical operations, invoking predefined functions, and navigating complex data structures using JSONPath-like syntax.

Table of Contents

1. Introduction
   1.1 Purpose
   1.2 Scope
2. Conventions and Terminology
3. Syntax and Semantics
   3.1 Variable Access
       3.1.1 Variables
       3.1.2 Payload Access
   3.2 Functions
       3.2.1 String Functions
       3.2.2 Numerical Functions
       3.2.3 Predefined Functions
           3.2.3.1 Registry Functions
           3.2.3.2 Secret Retrieval
           3.2.3.3 Encoding and Decoding
           3.2.3.4 Type Checking
           3.2.3.5 Date and Time Functions
           3.2.3.6 Data Type Conversions
   3.3 Operators
       3.3.1 Arithmetic Operators
       3.3.2 Comparison Operators
       3.3.3 Logical Operators
   3.4 JSONPath Support
4. Security Considerations
5. References
6. Acknowledgments

1. Introduction

1.1 Purpose

This document defines a concise expression language intended for dynamic evaluation of expressions involving variables, payloads, and data structures within applications. The language aims to be simple yet powerful, facilitating data processing, transformation, and validation tasks.

1.2 Scope

The expression language specified herein is designed to be embedded within applications that require dynamic expression evaluation. It supports variable access, function calls, arithmetic and logical operations, and JSONPath-like syntax for data navigation.

2. Conventions and Terminology

- **Variable**: An identifier referring to a value.
- **Payload**: The primary data object containing accessible and manipulable data.
- **Function**: A predefined operation applicable to values.
- **Expression**: A combination of variables, literals, operators, and function calls evaluating to a value.
- **Syntax Notation**: Functions are called using the syntax `functionName(arguments)`.

3. Syntax and Semantics

3.1 Variable Access

3.1.1 Variables

Variables are accessed using the `var` prefix followed by a dot and the variable name:

- `var.name`
- `var.totalPrice`

3.1.2 Payload Access

The `payload` object is used to access data structures. For keys containing special characters or spaces, use the bracket notation:

- `payload.students`
- `payload.orders`
- `payload["orders"][0]["name"]`

3.2 Functions

The language supports a variety of functions for string manipulation, numerical computations, data retrieval, encoding/decoding, type checking, date/time operations, and data type conversions.

3.2.1 String Functions

Applicable when the value is a string:

- `length(value)`: Returns the length of the string.
- `toUpper(value)`: Converts the string to uppercase.
- `toLower(value)`: Converts the string to lowercase.
- `substring(value, start, end)`: Extracts a substring from `start` to `end`.
- `startsWith(value, prefix)`: Checks if the string starts with `prefix`.
- `endsWith(value, suffix)`: Checks if the string ends with `suffix`.
- `contains(value, substring)`: Checks if the string contains `substring`.
- `trim(value)`: Removes leading and trailing whitespace.
- `replace(value, old, new)`: Replaces occurrences of `old` with `new`.
- `split(value, delimiter)`: Splits the string into an array using `delimiter`.

3.2.2 Numerical Functions

Applicable when the value is a number:

- `abs(value)`: Returns the absolute value.
- `floor(value)`: Returns the largest integer less than or equal to the value.
- `ceil(value)`: Returns the smallest integer greater than or equal to the value.
- `sqrt(value)`: Returns the square root.
- `log(value)`: Returns the natural logarithm (base e).
- `pow(base, exponent)`: Returns the result of raising `base` to the power of `exponent`.

3.2.3 Predefined Functions

3.2.3.1 Registry Functions

- `registry('path')`: Accesses the registry value at the specified `path`.

3.2.3.2 Secret Retrieval

- `secret('alias')`: Retrieves the secret associated with the given `alias`.

3.2.3.3 Encoding and Decoding

- `base64encode(value, 'charset')`: Encodes the value using Base64 with the specified charset.
- `base64decode(value)`: Decodes a Base64-encoded value.

- `urlEncode(value)`: Encodes a string for safe inclusion in a URL.
- `urlDecode(value)`: Decodes a URL-encoded string.

3.2.3.4 Type Checking

- `isNumber(value)`: Checks if the value is a number.
- `isString(value)`: Checks if the value is a string.
- `isArray(value)`: Checks if the value is an array.
- `isObject(value)`: Checks if the value is an object.

3.2.3.5 Date and Time Functions

- `now()`: Returns the current date and time.
- `today('format')`: Returns the current date formatted according to the specified `format`.
- `formatDate(date, 'format')`: Formats a given `date` according to the specified `format`.

3.2.3.6 Data Type Conversions

- `integer(value)`: Converts the value to an integer.
- `float(value)`: Converts the value to a floating-point number.
- `string(value)`: Converts the value to a string.
- `boolean(value)`: Converts the value to a boolean.

3.3 Operators

Operators can be used between expressions and literals for arithmetic, comparison, and logical operations.

3.3.1 Arithmetic Operators

- Addition: `+` (e.g., `var.num1 + var.num2`)
- Subtraction: `-` (e.g., `var.num1 - var.num2`)
- Multiplication: `*` (e.g., `var.num1 * var.num2`)
- Division: `/` (e.g., `var.num1 / var.num2`)

3.3.2 Comparison Operators

- Greater than: `>` (e.g., `var.num1 > var.num2`)
- Less than: `<` (e.g., `var.num1 < var.num2`)
- Greater than or equal to: `>=` (e.g., `var.num1 >= var.num2`)
- Less than or equal to: `<=` (e.g., `var.num1 <= var.num2`)
- Equal to: `==` (e.g., `var.num1 == var.num2`)
- Not equal to: `!=` (e.g., `var.num1 != var.num2`)

3.3.3 Logical Operators

- Logical NOT: `not` (e.g., `not var.boolValue`)
- Logical AND: `and` (e.g., `var.boolValue1 and var.boolValue2`)
- Logical OR: `or` (e.g., `var.boolValue1 or var.boolValue2`)

3.4 JSONPath Support

The language supports JSONPath-like syntax for navigating complex data structures.

- Accessing array elements and object properties:

  - `var.student[0].age`: Accesses the `age` property of the first `student`.
  - `payload["student"]["name"]`: Accesses the `name` property within `student`.

- Filtering elements in arrays:

  - `payload.users[?(@.age >= vars.minAge)]`: Selects users with `age` greater than or equal to `vars.minAge`.

4. Security Considerations

Implementations must ensure that access to sensitive data, such as secrets and registry values, is properly controlled and authenticated. Unauthorized access can lead to security breaches, data leakage, and compromise of system integrity. It is imperative to enforce strict access controls and validation when evaluating expressions that involve sensitive operations.

5. References

- [1] JSONPath Specification
- [2] Base64 Encoding Standard (RFC 4648)
- [3] URL Encoding Standards
- [4] ISO Date and Time Formats

6. Acknowledgments

The development of this expression language was inspired by common requirements in data processing applications. Special thanks to all contributors who provided valuable feedback and suggestions.

---

This document provides a comprehensive specification of the expression language, ensuring consistency and clarity for developers and implementers. By adhering to this specification, applications can reliably evaluate expressions for various data manipulation tasks.