Evaluation Criteria Reference

Table of Contents

1. Overview
2. JSONPath Expression Syntax
3. Data Types
4. Operators
5. Array Match Modes
6. Complete Examples
7. Best Practices

Overview

The governance service evaluation engine provides a powerful and flexible system for evaluating compliance criteria against event data. It uses JSONPath expressions to extract values from JSON data and applies various operators to determine compliance status.

Key Components

• JSONPath Expressions: Extract values from JSON event data
• Data Types: Define how values are interpreted and compared
• Operators: Specify the comparison logic
• Array Match Modes: Control how array values are evaluated

JSONPath Expression Syntax

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[?(@.type=='x')]

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 the extraction details and cause the criterion to fail instead of raising an extraction error

Data Types

The evaluation engine supports six data types for criteria values:

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 JSONPath expressions return arrays (e.g., using [*]), you can control how the evaluation is performed:

1. ALL Match Mode (Default)

All elements in the array must satisfy the criteria. This is the default for most operators.

{
  "field": "$.vulnerabilities[*].severity",
  "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. This is the default for in and contains operators when arrayMatchMode is omitted.

{
  "field": "$.backups[*].status",
  "operator": "eq",
  "criteriaValue": "available",
  "arrayMatchMode": "any"
}

Example: At least one backup must be available

Complete Examples

Example 1: Security Compliance Check

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

Example 2: Service Health Monitoring

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

Example 3: Data Quality Validation

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

Example 4: Mixed Array Match Modes

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

Best Practices

1. Use Specific JSONPath Expressions

• Prefer $.server.metrics.cpu over complex filter expressions
• Use array indices when targeting specific elements

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

• Missing JSONPath values cause the affected criterion to fail
• 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 failure modes and their meanings:

Failure mode	Cause	Solution
Missing extracted value	JSONPath doesn’t match the event payload	Verify path and data structure
Type conversion failed	Extracted value cannot be compared as the configured type	Ensure data type matches criteria type
Empty or invalid JSON payload	Event payload is empty or not valid JSON	Validate the event payload before ingestion
Invalid operator	Criterion uses an unsupported operator	Use supported operators only

Debugging Tips

1. Test JSONPath expressions separately before creating criteria
2. Log extracted values to verify correct data extraction
3. Start simple with basic paths and operators
4. Validate event data structure matches expected format
5. Use appropriate match modes for array evaluations