matrix-spec-proposals/proposals/3873-event-match-dotted-keys.md

MSC3873: event_match dotted keys

The current specification of event_match describes the parameter key as

key: The dot-separated path of the property of the event to match, e.g. content.body.

It does not, however, clarify how to handle collisions such as in

{
  "m": { "foo": "bar" },
  "m.foo": "baz"
}

where it is unclear which field the dot-separated path m.foo should match (#648).

Previously collisions were not often a practical problem, but as dotted-field names have become more common in Matrix, e.g. m.relates_to or MSC1767-style extensible events, this ambiguity is no longer satisfactory.

The ambiguity in the specification leads to incompatible implementations as evidenced by matrix-org/matrix-js-sdk#1454. The current proposal resolves the ambiguity by leveraging the existing solution for the same problem used by the event_fields of filters:

List of event fields to include. If this list is absent then all fields are included. The entries may include ‘.’ characters to indicate sub-fields. So [‘content.body’] will include the ‘body’ field of the ‘content’ object. A literal ‘.’ character in a field name may be escaped using a ‘\’.

This ambiguity is blocking other MSCs which all attempt to create rules on fields with dots in them, such as:

• MSC3952 Intentional Mentions
• MSC3958 Suppress notifications from message edits

And likely any push rule for keywords using extensible events.

Proposal

The dot (.) character in the key parameter is changed to be exclusively reserved for field separators. Any literal dot in field names are to be escaped using a backslash (\.) and any literal backslashes are also escaped with a backslash (\\). A backslash before any other character has no special meaning and is left as-is, but it is recommended that implementations do not redundantly escape characters, as they may be used for escape sequences in the future.

Revisiting the example from above

{
  "m": { "foo": "bar" },
  "m.foo": "baz"
}

this means that "key": "m.foo" unambiguously matches the nested foo field. The top-level m.foo field in turn can be matched through "key": "m\.foo".

As mentioned above, this exact solution is already employed by filters. Reusing it here, therefore, increases the specification’s coherence.

Potential issues

This MSC provides no mechanism for backwards compatibility. ¹ This should not impact the vast majority of users since none of the default push rules (nor common custom push rules, e.g. for keywords) are dependent on dotted field names.

Implementations could attempt to disambiguate the key by checking all possible ambiguous version this is fragile: what do you do if both ambiguous fields exist? This gets worse as additional nested objects exist:

{
  "m": { 
    "foo": { "bar":  "abc" },
    "foo.bar": "def"
  },
  "m.foo": { "bar": "ghi" },
  "m.foo.bar": "jkl"
}

This may break custom push rules that users have configured, but it is asserted that those are broken anyway, as mentioned above (see matrix-org/matrix-js-sdk#1454).

Alternatives

Alternatives to the current proposal are to use JSON pointers or JSONPath. While being more versatile than the simplistic escaping proposed here, these are unnecessary and break backwards compatibility for all existing event_match conditions.

Security considerations

None.

---

1. See a previous version. ↩︎