From 7340a2f6d0c86b228d2dccb821aa82b46bf93acf Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 5 Aug 2024 16:30:20 -0400 Subject: [PATCH 01/10] MSC4175: Profile field for user time zone --- proposals/4175-profile-field-time-zone.md | 91 +++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 proposals/4175-profile-field-time-zone.md diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md new file mode 100644 index 00000000000..20835ed6f40 --- /dev/null +++ b/proposals/4175-profile-field-time-zone.md @@ -0,0 +1,91 @@ +# MSC4175: Profile field for user time zone + +Knowing another user's time zone is useful for knowing whether they are likely +to respond or not. Example uses include: + +* Showing a user's time zone or time zone offset directly. +* Showing a user's local time (with hints of whether it is day or night there). + + +## Proposal + +Profiles can provide an optional `m.tz` field with values equal to names from the +[IANA time zone database](https://data.iana.org/time-zones/theory.html#naming). +Clients can set and fetch this via the [normal API endpoints](https://spec.matrix.org/unstable/client-server-api/#profiles). + +* Servers MAY validate that the value is a valid IANA time zone. If deemed invalid + they MUST return a 400 error with error code `M_INVALID_PARAM`. +* Clients MUST handle invalid or unknown values. + +If the field is not provided it SHOULD be interpreted as having no time zone information +for that user. + + +## Potential issues + +Clients may need to understand IANA time zone names to show useful information to users. +Some languages make this easy, e.g. JavaScript can handle this using +[`Date.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString). +This may cause clients to bundle the IANA time zone database (and thus also keep it +up to date). + +Clients will need to manually update the profile field when the user changes time zone. +This could be automated by clients based on location, or left as a manual change to +users. + + +## Alternatives + +The time zone offset could be included directly (in minutes/seconds or in `[+-]HH:MM` form). +This would require clients to manually update the profile field during daylight +savings. Using the IANA time zone name is robust against this. + +[RFC7095: jCard The JSON Format for vCard](https://datatracker.ietf.org/doc/html/rfc7095) +format could be used instead, but this doesn't make much sense unless the entire +profile was replaced. + +(Note there's an alternative [jCard](https://microformats.org/wiki/jCard) format +which is a non-standard derivative of [hCard](https://microformats.org/wiki/hcard).) + + +## Competitive analysis + +Slack's [`users.info` API call](https://api.slack.com/methods/users.info) includes +3 separate fields: + +* `tz`: the time zone database name (e.g. `"America/New_York"`) +* `tz_label`: a friendly name (e.g. `"Eastern Daylight Time"`) +* `tz_offset`: offset in seconds as an integer (e.g. `-14400`) + + +XMPP directly uses either: + +* [XEP-054](https://xmpp.org/extensions/xep-0054.html) uses vCard + ([RFC2426](https://datatracker.ietf.org/doc/html/rfc2426)) converted to XML via + [draft-dawson-vcard-xml-dtd-01](https://datatracker.ietf.org/doc/html/draft-dawson-vcard-xml-dtd-01) +* [XEP-0292](https://xmpp.org/extensions/xep-0292.html) uses xCard: vCard XML Representation + ([RFC6351](https://datatracker.ietf.org/doc/html/rfc6351)), see also vCard4 + ([RFC6351](https://datatracker.ietf.org/doc/html/rfc6351)) + +Rocket.Chat provides a user's [time zone offset](https://developer.rocket.chat/docs/user) +in the `utcOffset` field. + +Mattermost [returns an object](https://api.mattermost.com/#tag/users/operation/GetUser) +with the user's manual and/or automatic IANA time zone name. + +Discord, Twitter, blah don't provide a user's time zone. + +## Security considerations + +Showing a user's time zone gives some information to their location. There is currently +no way to limit what profile fields other users can see. + + +## Unstable prefix + +`us.cloke.msc4175.tz` should be used in place of `m.tz`. + + +## Dependencies + +Requires [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). From 68105db50ed789a2fdf1e681014e919db830a96e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 9 Aug 2024 15:01:37 -0400 Subject: [PATCH 02/10] Expand security section. --- proposals/4175-profile-field-time-zone.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index 20835ed6f40..c3eebdf9d5d 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -80,6 +80,9 @@ Discord, Twitter, blah don't provide a user's time zone. Showing a user's time zone gives some information to their location. There is currently no way to limit what profile fields other users can see. +clients may wish to warn users when providing a timezone and give +the option to kot incoude it in their profile. + ## Unstable prefix From 416bb7eed1640d5b47ca252910046467cf51c9d2 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 28 Aug 2024 13:36:34 -0400 Subject: [PATCH 03/10] Fix typos. Co-authored-by: Will Hunt --- proposals/4175-profile-field-time-zone.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index c3eebdf9d5d..690bb372644 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -80,8 +80,8 @@ Discord, Twitter, blah don't provide a user's time zone. Showing a user's time zone gives some information to their location. There is currently no way to limit what profile fields other users can see. -clients may wish to warn users when providing a timezone and give -the option to kot incoude it in their profile. +Clients may wish to warn users when providing a timezone and give +the option to not include it in their profile. ## Unstable prefix From 30701f0ddcce1a5c9fe331775a771fee5bb50774 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 6 Sep 2024 07:43:40 -0400 Subject: [PATCH 04/10] Updates. --- proposals/4175-profile-field-time-zone.md | 24 ++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index 690bb372644..8918af14b35 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -10,7 +10,7 @@ to respond or not. Example uses include: ## Proposal Profiles can provide an optional `m.tz` field with values equal to names from the -[IANA time zone database](https://data.iana.org/time-zones/theory.html#naming). +[IANA Time Zone Database](https://www.iana.org/time-zones). Clients can set and fetch this via the [normal API endpoints](https://spec.matrix.org/unstable/client-server-api/#profiles). * Servers MAY validate that the value is a valid IANA time zone. If deemed invalid @@ -33,6 +33,11 @@ Clients will need to manually update the profile field when the user changes tim This could be automated by clients based on location, or left as a manual change to users. +Clients may wish to periodically fetch the time one of other users as it is +liable to change somewhat frequently. Currently, profile data isn't propagated/synchronized +between servers, but that's left to a future MSC to solve. It is recommended that +clients cache the value for 12 - 24 hours. + ## Alternatives @@ -44,11 +49,16 @@ savings. Using the IANA time zone name is robust against this. format could be used instead, but this doesn't make much sense unless the entire profile was replaced. -(Note there's an alternative [jCard](https://microformats.org/wiki/jCard) format -which is a non-standard derivative of [hCard](https://microformats.org/wiki/hcard).) +[RFC9553](https://datatracker.ietf.org/doc/html/rfc9553) offers an alternative +representation for contacts (which is not backwards compatible with vCard). There +exists `timeZone` field under the `addresses` field which uses an time zone name +from the IANA Time Zone Database. + +Note there's an alternative [jCard](https://microformats.org/wiki/jCard) format +which is a non-standard derivative of [hCard](https://microformats.org/wiki/hcard). -## Competitive analysis +### Competitive analysis Slack's [`users.info` API call](https://api.slack.com/methods/users.info) includes 3 separate fields: @@ -57,8 +67,7 @@ Slack's [`users.info` API call](https://api.slack.com/methods/users.info) includ * `tz_label`: a friendly name (e.g. `"Eastern Daylight Time"`) * `tz_offset`: offset in seconds as an integer (e.g. `-14400`) - -XMPP directly uses either: +XMPP uses either: * [XEP-054](https://xmpp.org/extensions/xep-0054.html) uses vCard ([RFC2426](https://datatracker.ietf.org/doc/html/rfc2426)) converted to XML via @@ -73,7 +82,8 @@ in the `utcOffset` field. Mattermost [returns an object](https://api.mattermost.com/#tag/users/operation/GetUser) with the user's manual and/or automatic IANA time zone name. -Discord, Twitter, blah don't provide a user's time zone. +Discord, Twitter, and IRC don't provide a user's time zone. + ## Security considerations From 11792480c581d53f5c3a7eeda5fa23fc36fca83e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 14 May 2025 08:12:39 -0400 Subject: [PATCH 05/10] Update with concerns --- proposals/4175-profile-field-time-zone.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index 8918af14b35..849e8220fcd 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -17,6 +17,10 @@ Clients can set and fetch this via the [normal API endpoints](https://spec.matri they MUST return a 400 error with error code `M_INVALID_PARAM`. * Clients MUST handle invalid or unknown values. +The rationale for somewhat loose validation is that different clients/servers may have +different understanding of valid time zones, e.g. different versions of the time zone +database. + If the field is not provided it SHOULD be interpreted as having no time zone information for that user. @@ -29,6 +33,9 @@ Some languages make this easy, e.g. JavaScript can handle this using This may cause clients to bundle the IANA time zone database (and thus also keep it up to date). +Using the IANA time zone name has the downside that it does now allow arbitrary offsets, +which may be required for time zones which are not internationally recognized. + Clients will need to manually update the profile field when the user changes time zone. This could be automated by clients based on location, or left as a manual change to users. @@ -45,6 +52,15 @@ The time zone offset could be included directly (in minutes/seconds or in `[+-]H This would require clients to manually update the profile field during daylight savings. Using the IANA time zone name is robust against this. +### Delegate profile fields + +There are several standards related to storing of contact information electronically, +notably vCard and its derivatives (see below). It is unclear if Matrix profile +information is similar enough to the contact information found in vCard to warrant using +that format directly, although there is certainly some overlap. + +Some of the JSON formats for vCard which include time zone information are detailed below: + [RFC7095: jCard The JSON Format for vCard](https://datatracker.ietf.org/doc/html/rfc7095) format could be used instead, but this doesn't make much sense unless the entire profile was replaced. From 99591dcc5cf5fbf6217597ab1f5453af5ea458ac Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 14 May 2025 16:24:04 -0400 Subject: [PATCH 06/10] Add additional required info --- proposals/4175-profile-field-time-zone.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index 849e8220fcd..d8b154cd060 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -45,6 +45,9 @@ liable to change somewhat frequently. Currently, profile data isn't propagated/s between servers, but that's left to a future MSC to solve. It is recommended that clients cache the value for 12 - 24 hours. +There should not be backwards compatibilty concerns since clients should be ignoring +unknown profile fields. + ## Alternatives @@ -52,6 +55,7 @@ The time zone offset could be included directly (in minutes/seconds or in `[+-]H This would require clients to manually update the profile field during daylight savings. Using the IANA time zone name is robust against this. + ### Delegate profile fields There are several standards related to storing of contact information electronically, @@ -114,6 +118,9 @@ the option to not include it in their profile. `us.cloke.msc4175.tz` should be used in place of `m.tz`. +Clients may immediately use the stable profile field once this MSC is accepted. This is +a client-to-client protocol and no feature negotiation is necessary. + ## Dependencies From 32f4ec617cab4ef388b060fa4a221c3be7ce80ad Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 14 May 2025 16:28:22 -0400 Subject: [PATCH 07/10] Typo fix --- proposals/4175-profile-field-time-zone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index d8b154cd060..e8dd49ced20 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -45,7 +45,7 @@ liable to change somewhat frequently. Currently, profile data isn't propagated/s between servers, but that's left to a future MSC to solve. It is recommended that clients cache the value for 12 - 24 hours. -There should not be backwards compatibilty concerns since clients should be ignoring +There should not be backwards compatibility concerns since clients should be ignoring unknown profile fields. From 0bcd6867d96ddc3095e5a91b9a48de40431a544a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 24 Jun 2025 15:59:15 -0400 Subject: [PATCH 08/10] Review comments. Co-authored-by: Travis Ralston --- proposals/4175-profile-field-time-zone.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index e8dd49ced20..cd1753b0493 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -11,11 +11,11 @@ to respond or not. Example uses include: Profiles can provide an optional `m.tz` field with values equal to names from the [IANA Time Zone Database](https://www.iana.org/time-zones). -Clients can set and fetch this via the [normal API endpoints](https://spec.matrix.org/unstable/client-server-api/#profiles). +Clients can set and fetch this via the [normal API endpoints](https://spec.matrix.org/v1.14/client-server-api/#profiles). * Servers MAY validate that the value is a valid IANA time zone. If deemed invalid they MUST return a 400 error with error code `M_INVALID_PARAM`. -* Clients MUST handle invalid or unknown values. +* Clients MUST handle invalid or unknown values. One approach may be processing the value as though it was never set. The rationale for somewhat loose validation is that different clients/servers may have different understanding of valid time zones, e.g. different versions of the time zone From 401cfc87b96d1335cd5d1f083c7fd075fbd28d5a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 20 Aug 2025 07:40:02 -0400 Subject: [PATCH 09/10] Typo fix Co-authored-by: Hubert Chathi --- proposals/4175-profile-field-time-zone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index cd1753b0493..f366ee58dc2 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -40,7 +40,7 @@ Clients will need to manually update the profile field when the user changes tim This could be automated by clients based on location, or left as a manual change to users. -Clients may wish to periodically fetch the time one of other users as it is +Clients may wish to periodically fetch the time zone of other users as it is liable to change somewhat frequently. Currently, profile data isn't propagated/synchronized between servers, but that's left to a future MSC to solve. It is recommended that clients cache the value for 12 - 24 hours. From 895787859fea6e0a20b2f630b284ef1e8a739465 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 2 Sep 2025 12:33:34 -0400 Subject: [PATCH 10/10] Add examples --- proposals/4175-profile-field-time-zone.md | 25 +++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/proposals/4175-profile-field-time-zone.md b/proposals/4175-profile-field-time-zone.md index f366ee58dc2..f68fff48c01 100644 --- a/proposals/4175-profile-field-time-zone.md +++ b/proposals/4175-profile-field-time-zone.md @@ -21,9 +21,30 @@ The rationale for somewhat loose validation is that different clients/servers ma different understanding of valid time zones, e.g. different versions of the time zone database. -If the field is not provided it SHOULD be interpreted as having no time zone information +If the field is not provided, it SHOULD be interpreted as having no time zone information for that user. +An example request to set the time zone would be: + +``` +PUT /_matrix/client/v3/profile/@alice:example.org/m.tz + +{ + "m.tz": "America/New_York" +} +``` + +Similarly when retrieving a user's profile: + +``` +GET /_matrix/client/v3/profile/@alice:example.org + +{ + "displayname": "Alice", + "m.tz": "Europe/Paris" +} +``` + ## Potential issues @@ -110,7 +131,7 @@ Discord, Twitter, and IRC don't provide a user's time zone. Showing a user's time zone gives some information to their location. There is currently no way to limit what profile fields other users can see. -Clients may wish to warn users when providing a timezone and give +Clients may wish to warn users when providing a time zone and give the option to not include it in their profile.