What is your idea?

The Event Ruler README should explicitly document that ALL leaf values in rules must be arrays,
regardless of data type. This is a fundamental requirement enforced by the parser but is not clearly
stated in the documentation.

Current Problem:
Users frequently encounter this error without understanding why:
ERROR: Failed to load rule: "coppa" must be an object or an array

The Issue:
The README shows examples with arrays but doesn't explicitly state this as a requirement. Users
naturally try:
// ❌ Logical but incorrect - causes parser error

"br": { "regs": { "coppa": true } } } 

Instead of the required format:
// ✅ Required format

"br": { "regs": { "coppa": [true] } } } 

Proposed Documentation Enhancement:

Add a prominent section early in the README (after the basic example) that clearly states:

Important: Rule Value Format

⚠️ CRITICAL: ALL values in Event Ruler rules must be provided as arrays.

This applies to every data type:

• ✅ Correct: "field": [true] (boolean in array)
• ✅ Correct: "field": ["string"] (string in array)
• ✅ Correct: "field": [123] (number in array)
• ❌ Incorrect: "field": true (direct boolean - will cause error)
• ❌ Incorrect: "field": "string" (direct string - will cause error)

Why arrays? Arrays enable OR logic (["val1", "val2"] = "val1 OR val2") and provide a consistent
parser interface.

Objects are only used for:

1. Nested field navigation: {"detail": {"state": ["running"]}}
2. Match expressions: {"field": [{"prefix": "value"}]}

Would you be willing to make the change?

Yes, I'm willing to contribute this improvement.

I can provide:

1. README.md updates with the proposed documentation enhancement
2. Additional examples showing correct array usage for all data types
3. Updated existing examples to emphasize the array requirement
4. Links to troubleshooting for the "must be an object or an array" error

Additional context

Evidence from source code:
The requirement is enforced in RuleCompiler.java:213:

case START_OBJECT: // Navigate into nested object break; case START_ARRAY: // Process matching values break; default: barf(parser, String.format("\"%s\" must be an object or an array", stepName)); } 

Real-world impact:

• AWS services using Event Ruler encounter this regularly
• New users spend significant time debugging this undocumented requirement
• The error message is cryptic without context about the array requirement

Current documentation gap:
While the README shows good examples using arrays, it never explicitly states this as a requirement.
Users seeing examples like:

"detail": { "state": [ "initializing", "running" ] } } 

Might reasonably assume single values would work as:

"detail": { "state": "running" } } 

Proposed solution benefits:

• Reduces user confusion and support burden
• Makes the fundamental rule syntax clear upfront
• Improves developer experience for Event Ruler adoption
• Prevents the most common rule creation error

Additional improvements to consider:

• Add a troubleshooting section for common errors
• Include examples for each data type (boolean, string, number, null)
• Explain the reasoning behind the array requirement (OR logic, parser consistency)

This documentation enhancement would significantly improve the Event Ruler user experience and reduce
the learning curve for new users.

Add any other context (such as images, docs, posts) about the idea here.