Thank you for your feedback! We understand the need for clearer context when validation fails.

While we don't currently plan to implement descriptions directly within expressions (as its primary utility seems specific to the validation use case), I can suggest several workarounds that might be helpful:

1. Combine $jsonSchema with $expr

You can define rules that $jsonSchema can handle within a $jsonSchema block, utilizing its description field, and reserve $expr only for complex, cross-field logic that $jsonSchema cannot express. Combine them using a top-level $and.

Example:

"validator": {
  "$and": [
    {
      "$jsonSchema": {
        "properties": {
          "status": {
            "bsonType": "string",
            "enum": ["Active", "Inactive", "Pending"],
            "description": "Status must be one of the allowed values."
          }
          // ... other simple rules with descriptions ...
        }
      }
    },
    {
      "$expr": {
        // ... only complex rules go here ...
        "$gte": ["$endDate", "$startDate"]
      }
    }
  ]
}

2. Separate $expr Rules

Instead of one $expr with many conditions, break it into multiple $expr clauses joined by a top-level $and. If validation fails, the error message will list only the specific $expr blocks that failed.

Example

"validator": {
  "$and": [
    { "$expr": { "$gte": ["$endDate", "$startDate"] } },       // Rule 1
    { "$expr": { "$lt": ["$maxAttendees", 100] } },          // Rule 2
    { "$expr": { /* ... more separate rules ... */ } }         // Rule 3...
  ]
}

3. Techniques for Embedding Descriptions Inside $expr

While not perfectly elegant, you can embed descriptive text or documentation links directly into your separate $expr clauses in a way that doesn't affect the logic but does appear in the error output's specifiedAs field.

Here are two ways to do this:

Option A: Using $let (Define an unused variable to hold the description)

{
  "$expr": {
    "$let": {
      "vars": {
        "description": "Attendee limit is 100. See: http://your-wiki.com/docs#attendees"
      },
      "in": { "$lt": ["$maxAttendees", 100] } // <- Your actual rule logic
    }
  }
}

Option B: Using $and (Add the description string as the "truthy" element)

{
  "$expr": {
    "$and": [
      "Description: Dates are inverted. See: http://your-wiki.com/docs#dates", // <- Your description
      { "$gte": ["$endDate", "$startDate"] } // <- Your actual rule logic
    ]
  }
}

Combining approach #2 (separate $expr blocks) with approach #3 (embedding descriptions) gives you both isolation of the failing rule and descriptive text within the error message for that rule. We do not expect these approaches to have meaningful performance impact on your writes.

Hope these will be helpful.