Evaluation Criteria Reference

Overview
Extraction Rules and JSONPath Syntax
Data Types
Operators
Array Match Modes
Complete Examples
Best Practices

Overview

The governance service evaluation engine evaluates extracted event fields against criteria. Each indicator defines extractionRules that map stable field names to JSONPath expressions, then each criterion references one of those extracted field names in field.

Key Components

Extraction Rules: Map names such as status or responseTimeMs to JSONPath expressions
Criteria Fields: Reference extracted field names, not JSONPath expressions
Data Types: Define how extracted values are interpreted and compared
Operators: Specify the comparison logic
Array Match Modes: Control how array values are evaluated

Extraction Rules and JSONPath Syntax

JSONPath is used only inside extractionRules. Criteria use the extracted field name as their field value. For example, extractionRules.status may be $.status, but the criterion field must be status.

Criteria field names must start with a letter or underscore and may contain only letters, numbers, and underscores.

The evaluation engine supports a subset of JSONPath syntax optimized for performance and clarity.

Basic Syntax

Syntax	Description	Example
`$`	Root object	`$` returns entire object
`.`	Child operator	`$.status`
`..`	Recursive descent	`$..status`
`[n]`	Array element at index n	`$.items[2]`
`[*]`	All array elements	`$.items[*]`
`[?()]`	Array filter expression	`$.items[?(@.price>10)]`

Supported Path Expressions

1. Simple Field Access

// Event data
{
  "status": "active",
  "score": 85
}

// JSONPath: $.status
// Returns: "active"

// JSONPath: $.score

// Returns: 85

2. Nested Field Access

// Event data
{
  "server": {
    "status": "running",
    "metrics": {
      "cpu": 45.5,
      "memory": 78.2
    }
  }
}

// JSONPath: $.server.status
// Returns: "running"

// JSONPath: $.server.metrics.cpu

// Returns: 45.5

3. Array Index Access

// Event data
{
  "vulnerabilities": [{ "severity": 3 }, { "severity": 7 }, { "severity": 9 }]
}

// JSONPath: $.vulnerabilities[0].severity
// Returns: 3

// JSONPath: $.vulnerabilities[2].severity

// Returns: 9

4. Array Wildcard Access

// Event data
{
  "services": [
    { "name": "api", "status": "healthy" },
    { "name": "db", "status": "unhealthy" },
    { "name": "cache", "status": "healthy" }
  ]
}

// JSONPath: $.services[*].status
// Returns: ["healthy", "unhealthy", "healthy"]

// JSONPath: $.services[*].name

// Returns: ["api", "db", "cache"]

5. Array Filter Access

// Event data
{
  "items": [
    { "type": "security", "score": 85 },
    { "type": "performance", "score": 92 },
    { "type": "security", "score": 78 }
  ]
}

// JSONPath: $.items[?(@.type=='security')].score

// Returns: [85, 78]

Special Cases

Root Access: Use $ or . to access the entire object
Array Wildcards: Use [*] to read all elements in an array; [] is not a wildcard form
Recursive Descent: Use $..fieldName to find matching fields at any depth
Filters: Array filters use the ?(...) form and support equality, comparison, regex, and field-existence checks on item fields
Missing Fields: Missing values are tracked in extraction details and cause the criterion to fail instead of raising an extraction error

Data Types

The evaluation engine supports six criteria data types. In every example below, field is the extracted field name that appears as a key in extractionRules.

1. String (`string`)

Text values compared as strings.

{
  "type": "string",
  "field": "status",
  "operator": "eq",
  "criteriaValue": "active"
}

2. Number (`number`)

Numeric values (integers or decimals) compared as 64-bit floating-point numbers.

{
  "type": "number",
  "field": "score",
  "operator": "gt",
  "criteriaValue": 80
}

3. Boolean (`boolean`)

True/false values. Supports various representations:

Boolean: true, false
String: "true", "false" (case-insensitive)
Number: 0 (false), non-zero (true)

{
  "type": "boolean",
  "field": "enabled",
  "operator": "eq",
  "criteriaValue": true
}

4. Date (`date`)

Date/time values in RFC3339 format.

{
  "type": "date",
  "field": "lastUpdated",
  "operator": "gt",
  "criteriaValue": "2024-01-01T00:00:00Z"
}

5. List of Strings (`list[string]`)

Array of string values. Supports multiple input formats:

JSON array: ["value1", "value2"]
Comma-separated: "value1,value2"

{
  "type": "list[string]",
  "field": "tags",
  "operator": "in",
  "criteriaValue": ["production", "critical"]
}

6. List of Numbers (`list[number]`)

Array of numeric values.

{
  "type": "list[number]",
  "field": "scores",
  "operator": "in",
  "criteriaValue": [80, 90, 100]
}

Operators

The evaluation engine supports ten comparison operators:

1. Equal (`eq`)

Checks if values are equal. Supports flexible type comparison.

{
  "operator": "eq",
  "criteriaValue": "active"
}

2. Not Equal (`neq`)

Checks if values are not equal.

{
  "operator": "neq",
  "criteriaValue": "inactive"
}

3. Greater Than (`gt`)

Numeric comparison - actual value must be greater than criteria value.

{
  "operator": "gt",
  "criteriaValue": 80
}

4. Less Than (`lt`)

Numeric comparison - actual value must be less than criteria value.

{
  "operator": "lt",
  "criteriaValue": 100
}

5. Greater Than or Equal (`gte`)

Numeric comparison - actual value must be greater than or equal to criteria value.

{
  "operator": "gte",
  "criteriaValue": 80
}

6. Less Than or Equal (`lte`)

Numeric comparison - actual value must be less than or equal to criteria value.

{
  "operator": "lte",
  "criteriaValue": 100
}

7. In (`in`)

Checks if actual value exists in the criteria list.

{
  "operator": "in",
  "criteriaValue": ["active", "pending", "processing"]
}

8. Not In (`notIn`)

Checks if actual value does not exist in the criteria list.

{
  "operator": "notIn",
  "criteriaValue": ["failed", "error", "timeout"]
}

9. Contains (`contains`)

String comparison - checks if actual string contains the criteria string.

{
  "operator": "contains",
  "criteriaValue": "error"
}

10. Not Contains (`notContains`)

String comparison - checks if actual string does not contain the criteria string.

{
  "operator": "notContains",
  "criteriaValue": "warning"
}

Array Match Modes

When an extraction rule returns an array, such as $.vulnerabilities[*].severity, the criterion can control how the array is evaluated.

1. ALL Match Mode (Default)

All elements in the array must satisfy the criteria.

{
  "field": "vulnerabilitySeverity",
  "operator": "lte",
  "criteriaValue": 7,
  "arrayMatchMode": "all" // Optional - this is the default
}

Example: All vulnerabilities must have severity ≤ 7

2. ANY Match Mode

At least one element in the array must satisfy the criteria.

{
  "field": "backupStatus",
  "operator": "eq",
  "criteriaValue": "available",
  "arrayMatchMode": "any"
}

Example: At least one backup must be available

Complete Examples

Example 1: Security Compliance Check

{
  "extractionRules": {
    "vulnerabilitySeverity": "$.security_scan.vulnerabilities[*].severity",
    "securityScanPassed": "$.security_scan.passed",
    "scannerVersion": "$.security_scan.scanner_version"
  },
  "criteria": [
    {
      "type": "number",
      "field": "vulnerabilitySeverity",
      "operator": "lte",
      "criteriaValue": 7,
      "arrayMatchMode": "all"
    },
    {
      "type": "boolean",
      "field": "securityScanPassed",
      "operator": "eq",
      "criteriaValue": true
    },
    {
      "type": "string",
      "field": "scannerVersion",
      "operator": "contains",
      "criteriaValue": "v2"
    }
  ]
}

Example 2: Service Health Monitoring

{
  "extractionRules": {
    "serviceStatus": "$.services[*].status",
    "serviceResponseTimeMs": "$.services[*].response_time_ms",
    "alertSeverity": "$.monitoring.alerts[*].severity"
  },
  "criteria": [
    {
      "type": "string",
      "field": "serviceStatus",
      "operator": "eq",
      "criteriaValue": "healthy",
      "arrayMatchMode": "all"
    },
    {
      "type": "number",
      "field": "serviceResponseTimeMs",
      "operator": "lt",
      "criteriaValue": 1000,
      "arrayMatchMode": "all"
    },
    {
      "type": "string",
      "field": "alertSeverity",
      "operator": "notIn",
      "criteriaValue": ["critical", "high"],
      "arrayMatchMode": "all"
    }
  ]
}

Example 3: Data Quality Validation

{
  "extractionRules": {
    "completenessPercent": "$.data_quality.completeness_percent",
    "validationErrorField": "$.data_quality.validation_errors[*].field",
    "schemaValid": "$.data_quality.schema_valid"
  },
  "criteria": [
    {
      "type": "number",
      "field": "completenessPercent",
      "operator": "gte",
      "criteriaValue": 95
    },
    {
      "type": "list[string]",
      "field": "validationErrorField",
      "operator": "notIn",
      "criteriaValue": ["customer_id", "transaction_id", "timestamp"],
      "arrayMatchMode": "all"
    },
    {
      "type": "boolean",
      "field": "schemaValid",
      "operator": "eq",
      "criteriaValue": true
    }
  ]
}

Example 4: Mixed Array Match Modes

{
  "extractionRules": {
    "regionStatus": "$.regions[*].status",
    "regionErrorRate": "$.regions[*].error_rate"
  },
  "criteria": [
    {
      "type": "string",
      "field": "regionStatus",
      "operator": "eq",
      "criteriaValue": "operational",
      "arrayMatchMode": "any" // At least one region operational
    },
    {
      "type": "number",
      "field": "regionErrorRate",
      "operator": "lt",
      "criteriaValue": 5,
      "arrayMatchMode": "all" // All regions must have low error rate
    }
  ]
}

Best Practices

1. Use Stable Extracted Field Names

Use simple field names such as status, cpuUsage, or encryptionEnabled
Keep JSONPath expressions in extractionRules, not in criteria field values
Prefer specific JSONPath expressions such as $.server.metrics.cpu over complex filters

2. Choose Appropriate Data Types

Use number for all numeric comparisons
Use list[string] for in/notIn operations with multiple values
Use boolean for true/false checks

3. Select the Right Operator

Use eq/neq for exact matches
Use contains/notContains for substring searches
Use in/notIn for membership tests

4. Consider Array Match Modes

Use all (default) for strict compliance
Use any for redundancy or availability checks

5. Handle Missing Data

Extraction rules fail if the JSONPath expression does not match the event payload
Consider using default values in your event data
Test with various data structures

6. Performance Considerations

Simple paths are faster than wildcard expressions
Limit the depth of nested field access
Use specific array indices when possible

Type Conversion Rules

The evaluation engine performs automatic type conversion when possible:

String to Number

"123" → 123
"45.67" → 45.67

String to Boolean

"true" → true
"false" → false
Case-insensitive

Number to Boolean

0 → false
Non-zero → true

Arrays

Single values can match array criteria
"value" can match ["value", "other"] with in operator

Error Handling

Common errors and their meanings:

Error	Cause	Solution
`Field: "X" is not defined in extraction rules`	Criteria field does not match an extraction key	Add the key to `extractionRules` or fix `field`
`cannot convert X to number`	Type conversion failed	Ensure data type matches criteria type
`array index out of bounds`	Array index exceeds length	Check array size or use wildcard
`invalid operator: X`	Unknown operator	Use supported operators only

Debugging Tips

Test JSONPath expressions separately before creating extraction rules
Log extracted values to verify correct data extraction
Confirm each criteria field matches an extractionRules key
Start simple with basic paths and operators
Validate event data structure matches expected format
Use appropriate match modes for array evaluations