MSC3873: event_match dotted keys

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

@@ -0,0 +1,111 @@
+# 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. [^1] 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:
+
+```json
+{
+  "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].
+
+  [`event_match`]: https://spec.matrix.org/v1.3/client-server-api/#conditions-1
+  [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767
+  [#648]: https://github.com/matrix-org/matrix-spec/issues/648
+  [matrix-org/matrix-js-sdk#1454]: https://github.com/matrix-org/matrix-js-sdk/issues/1454
+  [MSC3952]: https://github.com/matrix-org/matrix-spec-proposals/pull/3952
+  [MSC3958]: https://github.com/matrix-org/matrix-spec-proposals/pull/3958
+  [filters]: https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3useruseridfilter
+  [JSON pointers]: https://www.rfc-editor.org/rfc/rfc6901
+  [JSONPath]: https://goessner.net/articles/JsonPath/
+  [a previous version]: https://github.com/matrix-org/matrix-spec-proposals/blob/cd906fcb263f667a7b8e5a626cc5b55fba3b9262/proposals/3873-event-match-dotted-keys.md?rgh-link-date=2022-08-21T18%3A02%3A02Z#backwards-compatibility