112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# 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
|