From 33fbe8ccaceac12c35d56ebb7ca05c5cc8c3855b Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 14 Nov 2021 20:53:00 +0000 Subject: [PATCH 1/8] MSC3488: Extending events with location data --- proposals/3488-location.md | 103 +++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 proposals/3488-location.md diff --git a/proposals/3488-location.md b/proposals/3488-location.md new file mode 100644 index 00000000000..2628992c7a0 --- /dev/null +++ b/proposals/3488-location.md @@ -0,0 +1,103 @@ +# MSC3488 - m.location: Extending events with location data + +## Problem + +We need a standard way to share location data about events in Matrix. Use +cases include sharing freeform static location info, sharing live-updating +location data of assets, associating location data with IOT telemetry, etc. + +The spec currently has the concept of an `m.location` `msgtype` on +`m.room.message` events, but this is very limiting as it only applies to +sharing location as an instant message. Instead, we'd like to leverage +extensible events (MSC1767) to associate location data with any kind of +event. + +## Proposal + +We introduce `m.location` as an extensible event type: a key which can be +placed in the `content` of any event to associate a location object with the +other data (if any) in that event. Clients which are location-aware may +let the user view events containing `m.location` on a map. + +This is intended to eventually replace the `m.location` msgtype (although this +MSC doesn't obsolete it) + +The `m.location` object must contain a `uri` field with a standard RFC5870 +`geo:` URI. It may also contain an optional `description` field, giving a +free-form label that should be used to label this location on a map. This is +not to be confused with fallback text representations of the event, which are +given by `m.text` or `m.html` as per MSC1767. The description field is also +not intended to include semantic descriptions of the location (e.g. the +details of a calendar invite), which should be stored in their respective +extensible event types when available. + +XXX: should description be localised? + +```json + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Our destination", + }, +``` + +If sharing the location of an object, one would add another subtype (e.g. a +hypothetical `m.asset` type) to give the object a type and ID. + +If sharing time-sensitive data, one would add another subtype (e.g. a +hypothetical `m.ts` type) to spell out the exact time that the data in the +event refers to (milliseconds since the UNIX epoch) + +If `m.location` is used as the event type itself, it describes a contextless +static location, suitable for "drop a pin on a map" style use cases. + +Example for sharing a static location: + +```json +{ + "type": "m.location", + "content": { + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Matthew's whereabouts", + }, + "m.ts": 1636829458432, + "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021" + } +} +``` + +## Alternatives + +We could use GeoJSON (RFC7946) to describe the location. However, it doesn't +support the concept of uncertainty, and is designed more for sharing map +annotations than location sharing. It would look something like this if we +used it: + +```json + "m.geo": { + "type": "Point", + "coordinates": [30.0, 10.0] + } +``` + +Another design choice is to represent static shared locations as a normal room +event rather than a state event. The reason we've chosen non-state events is +so that the data is subject to normal history visibility: it's very much a +transient event. Just because I temporarily mention a location to someone +doesn't mean I want it pinned in the room state forever more. On the other +hand, it means that streaming location data (where you do want to keep track +of the current location in room state) ends up being a different shape, which +could be a little surprising. + +## Security considerations + +Geographic location data is high risk from a privacy perspective. +Clients should remind users to be careful where they send location data, +and encourage them to do so in end-to-end encrypted rooms, given the +very real risk of real-world abuse from location data. + +## Unstable prefix + +`m.location` used as a event type and extensible event field name should be +referred to as `org.matrix.msc3488.location` until this MSC lands. +`m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. \ No newline at end of file From bb38c65ccc5b12ca0289d79ec22bd6abb3fe2991 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 14 Nov 2021 21:04:37 +0000 Subject: [PATCH 2/8] tabs->spaces --- proposals/3488-location.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index 2628992c7a0..8284a9ba860 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -34,10 +34,10 @@ extensible event types when available. XXX: should description be localised? ```json - "m.location": { - "uri": "geo:51.5008,0.1247;u=35", - "description": "Our destination", - }, + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Our destination", + }, ``` If sharing the location of an object, one would add another subtype (e.g. a @@ -54,15 +54,15 @@ Example for sharing a static location: ```json { - "type": "m.location", - "content": { - "m.location": { - "uri": "geo:51.5008,0.1247;u=35", - "description": "Matthew's whereabouts", - }, - "m.ts": 1636829458432, - "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021" - } + "type": "m.location", + "content": { + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Matthew's whereabouts", + }, + "m.ts": 1636829458432, + "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021" + } } ``` @@ -74,10 +74,10 @@ annotations than location sharing. It would look something like this if we used it: ```json - "m.geo": { - "type": "Point", - "coordinates": [30.0, 10.0] - } + "m.geo": { + "type": "Point", + "coordinates": [30.0, 10.0] + } ``` Another design choice is to represent static shared locations as a normal room From 97da17704451a636a9ff5f690ca4271028c16282 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 14 Nov 2021 21:06:21 +0000 Subject: [PATCH 3/8] bullets --- proposals/3488-location.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index 8284a9ba860..cfb623a42b8 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -98,6 +98,6 @@ very real risk of real-world abuse from location data. ## Unstable prefix -`m.location` used as a event type and extensible event field name should be + * `m.location` used as a event type and extensible event field name should be referred to as `org.matrix.msc3488.location` until this MSC lands. -`m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. \ No newline at end of file + * `m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. \ No newline at end of file From a3b8facbb3d61e38e5a520dbb1567fa0fcc553bc Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 21 Nov 2021 16:30:01 +0100 Subject: [PATCH 4/8] spell out backwards compat --- proposals/3488-location.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index cfb623a42b8..f89d4c8cfd0 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -66,6 +66,40 @@ Example for sharing a static location: } ``` +## Migration from the `m.location` msgtype + +Historically in Matrix, static locations have been shared via the `m.location` +msgtype in `m.room.message`. Until that API is deprecated from the spec, +clients should share static locations in a backwards-compatible way by mixing +in the `m.location` extensible event type from this MSC into the old-style +`m.room.message`. During this migratory phase, this necessarily duplicates +the relevant data. + +```json +{ + "type": "m.room.message", + "content": { + "body": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021", + "msgtype": "m.location", + "geo_uri": "geo:51.5008,0.1247;u=35", + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Matthew's whereabouts", + }, + "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021", + "m.ts": 1636829458432, + } +} +``` + +This means that clients which do not yet implement MSC3488 will be able to +correctly handle the location share. In future, an MSC will be written to +officially deprecate the `m.location` msgtype from the spec, at which point +clients should start sending `m.location` event types instead. Clients should +grandfather in the old `m.location` msgtype format for posterity in order to +display old events; this is unavoidable (similar to HTML being doomed to display +blink tags until the end of days). + ## Alternatives We could use GeoJSON (RFC7946) to describe the location. However, it doesn't @@ -96,6 +130,8 @@ Clients should remind users to be careful where they send location data, and encourage them to do so in end-to-end encrypted rooms, given the very real risk of real-world abuse from location data. +All points from https://www.w3.org/TR/geolocation/#security apply. + ## Unstable prefix * `m.location` used as a event type and extensible event field name should be From dc61c188f1f01d66885fb9e1a801e1d6f3cdb369 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 21 Nov 2021 20:58:29 +0100 Subject: [PATCH 5/8] prioritise msc3488 over geo_uri if both present --- proposals/3488-location.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index f89d4c8cfd0..9a3e01f322e 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -72,8 +72,9 @@ Historically in Matrix, static locations have been shared via the `m.location` msgtype in `m.room.message`. Until that API is deprecated from the spec, clients should share static locations in a backwards-compatible way by mixing in the `m.location` extensible event type from this MSC into the old-style -`m.room.message`. During this migratory phase, this necessarily duplicates -the relevant data. +`m.room.message`. During this migratory phase, this necessarily duplicates the +relevant data. If both fields are present, clients that speak MSC3488 should +favour the contents of the MSC3488 fields over the legacy `geo_uri` field. ```json { From 5c8e2bad52696929403aac8651865febc9e5abae Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Wed, 12 Jan 2022 12:57:59 +0200 Subject: [PATCH 6/8] Static location sharing tweaks (#3623) Add `m.asset` tracked asset subtype and zoom levels. --- proposals/3488-location.md | 51 +++++++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index 9a3e01f322e..ab30816b4bd 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -22,8 +22,9 @@ let the user view events containing `m.location` on a map. This is intended to eventually replace the `m.location` msgtype (although this MSC doesn't obsolete it) -The `m.location` object must contain a `uri` field with a standard RFC5870 -`geo:` URI. It may also contain an optional `description` field, giving a +The `m.location` object must contain a `uri` field with a standard RFC5870 `geo:` URI. + +It may also contain an optional `description` field, giving a free-form label that should be used to label this location on a map. This is not to be confused with fallback text representations of the event, which are given by `m.text` or `m.html` as per MSC1767. The description field is also @@ -33,15 +34,40 @@ extensible event types when available. XXX: should description be localised? -```json +`m.location` can also contain an optional `zoom_level` field to specify the +displayed area size on client mapping libraries. +Possible values range from 0 to 20 based on the definitions from +[OpenStreetMap here](https://wiki.openstreetmap.org/wiki/Zoom_levels) and it +would be the client's reponsibility to map them to values a particular library +uses, if different. The client is also free to completely ignore it and decide +the zoom level through other means. + +```json5 "m.location": { "uri": "geo:51.5008,0.1247;u=35", "description": "Our destination", + "zoom_level": 15, }, ``` -If sharing the location of an object, one would add another subtype (e.g. a -hypothetical `m.asset` type) to give the object a type and ID. +In order to differentiate between user tracking and other objects we also +introduce a new subtype called `m.asset` to give the object a type and ID. + +`m.asset` defines a generic asset that can be used for location tracking +but also in other places like inventories, geofencing, checkins/checkouts etc. +It should contain a mandatory namespaced `type` key defining what particular +asset is being referred to. +For the purposes of user location tracking `m.self` should be used in order to +avoid duplicating the mxid. + +If `m.asset` is missing from the location's content the client should render it +as `m.self` as that will be the most common use case. +Otherwise, if it's not missing but the type is invalid or unkown the client +should attempt to render it as a generic location. +Clients should be able to distinguish between `m.self` and explicit assets for +this feature to be correctly implemented as interpreting everything as `m.self` +is unwanted. + If sharing time-sensitive data, one would add another subtype (e.g. a hypothetical `m.ts` type) to spell out the exact time that the data in the @@ -52,7 +78,7 @@ static location, suitable for "drop a pin on a map" style use cases. Example for sharing a static location: -```json +```json5 { "type": "m.location", "content": { @@ -60,6 +86,9 @@ Example for sharing a static location: "uri": "geo:51.5008,0.1247;u=35", "description": "Matthew's whereabouts", }, + "m.asset": { + "type": "m.self" // the type of asset being tracked + }, "m.ts": 1636829458432, "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021" } @@ -76,7 +105,7 @@ in the `m.location` extensible event type from this MSC into the old-style relevant data. If both fields are present, clients that speak MSC3488 should favour the contents of the MSC3488 fields over the legacy `geo_uri` field. -```json +```json5 { "type": "m.room.message", "content": { @@ -87,6 +116,9 @@ favour the contents of the MSC3488 fields over the legacy `geo_uri` field. "uri": "geo:51.5008,0.1247;u=35", "description": "Matthew's whereabouts", }, + "m.asset": { + "type": "m.self" // the type of asset being tracked + }, "m.text": "Matthew was at geo:51.5008,0.1247;u=35 as of Sat Nov 13 18:50:58 2021", "m.ts": 1636829458432, } @@ -108,7 +140,7 @@ support the concept of uncertainty, and is designed more for sharing map annotations than location sharing. It would look something like this if we used it: -```json +```json5 "m.geo": { "type": "Point", "coordinates": [30.0, 10.0] @@ -137,4 +169,5 @@ All points from https://www.w3.org/TR/geolocation/#security apply. * `m.location` used as a event type and extensible event field name should be referred to as `org.matrix.msc3488.location` until this MSC lands. - * `m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. \ No newline at end of file + * `m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. + * `m.asset` should be referred to as `org.matrix.msc3488.asset` until this MSC lands. From 870809250090956275219150e7236521088cbc36 Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Thu, 20 Jan 2022 14:47:44 +0200 Subject: [PATCH 7/8] Static location sharing - .well-known config (#3663) Add section about tile server configuration through .well-known. --- proposals/3488-location.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index ab30816b4bd..ef274f00938 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -38,7 +38,7 @@ XXX: should description be localised? displayed area size on client mapping libraries. Possible values range from 0 to 20 based on the definitions from [OpenStreetMap here](https://wiki.openstreetmap.org/wiki/Zoom_levels) and it -would be the client's reponsibility to map them to values a particular library +would be the client's responsibility to map them to values a particular library uses, if different. The client is also free to completely ignore it and decide the zoom level through other means. @@ -62,7 +62,7 @@ avoid duplicating the mxid. If `m.asset` is missing from the location's content the client should render it as `m.self` as that will be the most common use case. -Otherwise, if it's not missing but the type is invalid or unkown the client +Otherwise, if it's not missing but the type is invalid or unknown the client should attempt to render it as a generic location. Clients should be able to distinguish between `m.self` and explicit assets for this feature to be correctly implemented as interpreting everything as `m.self` @@ -165,9 +165,17 @@ very real risk of real-world abuse from location data. All points from https://www.w3.org/TR/geolocation/#security apply. +## Well-known configuration + +Homeservers should be allowed to define a custom tile server to use. For that +we introduce a new key in `.well-known` called `m.tile_server` which should +contain an URL to the desired map style `json`. +Clients should read values from there and reconfigure accordingly. + ## Unstable prefix * `m.location` used as a event type and extensible event field name should be referred to as `org.matrix.msc3488.location` until this MSC lands. * `m.ts` should be referred to as `org.matrix.msc3488.ts` until this MSC lands. * `m.asset` should be referred to as `org.matrix.msc3488.asset` until this MSC lands. + * `m.tile_server` should be referred to as `org.matrix.msc3488.tile_server` until this MSC lands. From 810c64db856828fcdb8e5e885965ce394444804b Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Fri, 21 Jan 2022 19:50:07 +0200 Subject: [PATCH 8/8] Static location sharing - .well-known config tweaks (#3665) * Fix indentation. * Clarify tile server .well-known configuration. --- proposals/3488-location.md | 40 +++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/proposals/3488-location.md b/proposals/3488-location.md index ef274f00938..8f240bae983 100644 --- a/proposals/3488-location.md +++ b/proposals/3488-location.md @@ -43,11 +43,11 @@ uses, if different. The client is also free to completely ignore it and decide the zoom level through other means. ```json5 - "m.location": { - "uri": "geo:51.5008,0.1247;u=35", - "description": "Our destination", - "zoom_level": 15, - }, +"m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Our destination", + "zoom_level": 15, +} ``` In order to differentiate between user tracking and other objects we also @@ -141,10 +141,10 @@ annotations than location sharing. It would look something like this if we used it: ```json5 - "m.geo": { - "type": "Point", - "coordinates": [30.0, 10.0] - } +"m.geo": { + "type": "Point", + "coordinates": [30.0, 10.0] +} ``` Another design choice is to represent static shared locations as a normal room @@ -169,8 +169,26 @@ All points from https://www.w3.org/TR/geolocation/#security apply. Homeservers should be allowed to define a custom tile server to use. For that we introduce a new key in `.well-known` called `m.tile_server` which should -contain an URL to the desired map style `json`. -Clients should read values from there and reconfigure accordingly. +contain a `map_style_url` pointing to the desired map style `json`. + +Clients should read the `.well-known` and reconfigure accordingly, with values +coming from it taking precedence over base configuration. + +```json5 +{ + "m.tile_server": { + "map_style_url": "https://www.example.com/style.json" + }, + + + "m.homeserver": { + "base_url": "https://matrix-client.matrix.org" + }, + "m.identity_server": { + "base_url": "https://vector.im" + } +} +``` ## Unstable prefix