From 4fe1ca3507eab850ae5356f3522698fc53cc26a1 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 14 Mar 2023 09:32:01 -0400 Subject: [PATCH] Add information on MSC3873 dotted-path escape rules. --- content/appendices.md | 14 ++++++++++++++ content/client-server-api/modules/push.md | 12 ++++++------ 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/content/appendices.md b/content/appendices.md index dc3ced66..366d1796 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -942,6 +942,20 @@ uses the following rules: * The character `*` matches zero or more characters. * `?` matches exactly one character. +## Dot-separated property paths + +It is useful to express the "path" to an event property by concatenating property +names with dots, e.g. `content.body` would represent the a `body` property in the +event's `content`. + +To handle ambiguity when a property name contains a dot, any literal dot or +backslash found in a property name should be escaped with a backslash. E.g. a +property `m.relates_to` in the `content` would be expressed as +`content.m\.relates_to`. + +It is recommended that implementations do not redundantly escape characters, as +other escape sequences are reserve for future use. + ## Security Threat Model ### Denial of Service diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 1bf0343a..103c328f 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -214,8 +214,8 @@ The following conditions are defined: This is a glob pattern match on a property of the event. Parameters: -- `key`: The dot-separated path of the property of the event to match, e.g. - `content.body`. +- `key`: The [dot-separated path of the property](/appendices#dot-separated property paths) + of the event to match, e.g. `content.body`. - `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against. @@ -297,8 +297,8 @@ For an example of this, see the default rule This is an exact value match on a property of the event. Parameters: -- `key`: The dot-separated path of the property of the event to match, e.g. - `content.body`. +- `key`: The [dot-separated path of the property](/appendices#dot-separated property paths) + of the event to match, e.g. `content.body`. - `value`: The value to match against. @@ -341,8 +341,8 @@ The following `m.federate` values will NOT match: This matches if an array property of an event exactly contains a value. Parameters: -- `key`: The dot-separated path of the property of the event to match, e.g. - `content.body`. +- `key`: The [dot-separated path of the property](/appendices#dot-separated property paths) + of the event to match, e.g. `content.body`. - `value`: The value to match against.