diff --git a/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs b/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs
index ce713a02..853f22bf 100644
--- a/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs
@@ -40,6 +40,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs b/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs
index 73885efd..33143c20 100644
--- a/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs
@@ -43,6 +43,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs b/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs
index 42cfa1ec..8030d2b3 100644
--- a/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs
@@ -40,6 +40,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs b/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs
index 1f917354..5a2c0c15 100644
--- a/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs
@@ -36,6 +36,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/account/request_registration_token_via_email.rs b/ruma-client-api/src/r0/account/request_registration_token_via_email.rs
index 9a9833bb..d336be98 100644
--- a/ruma-client-api/src/r0/account/request_registration_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_registration_token_via_email.rs
@@ -40,6 +40,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs b/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs
index 52c482b3..26e2b966 100644
--- a/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs
@@ -43,6 +43,9 @@ ruma_api! {
         pub sid: String,
 
         /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/directory.rs b/ruma-client-api/src/r0/directory.rs
index 2825436c..eac62471 100644
--- a/ruma-client-api/src/r0/directory.rs
+++ b/ruma-client-api/src/r0/directory.rs
@@ -44,6 +44,9 @@ pub struct PublicRoomsChunk {
     pub guest_can_join: bool,
 
     /// The URL for the room's avatar, if one is set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-client-api/src/r0/membership/joined_members.rs b/ruma-client-api/src/r0/membership/joined_members.rs
index d037bc1d..1582f88f 100644
--- a/ruma-client-api/src/r0/membership/joined_members.rs
+++ b/ruma-client-api/src/r0/membership/joined_members.rs
@@ -54,6 +54,9 @@ pub struct RoomMember {
     pub display_name: Option<String>,
 
     /// The mxc avatar url of the user.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-client-api/src/r0/profile/get_avatar_url.rs b/ruma-client-api/src/r0/profile/get_avatar_url.rs
index 074e5dec..fc4992b9 100644
--- a/ruma-client-api/src/r0/profile/get_avatar_url.rs
+++ b/ruma-client-api/src/r0/profile/get_avatar_url.rs
@@ -25,6 +25,9 @@ ruma_api! {
     #[derive(Default)]
     response: {
         /// The user's avatar URL, if set.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/profile/get_profile.rs b/ruma-client-api/src/r0/profile/get_profile.rs
index 57705df9..5b898f11 100644
--- a/ruma-client-api/src/r0/profile/get_profile.rs
+++ b/ruma-client-api/src/r0/profile/get_profile.rs
@@ -25,6 +25,9 @@ ruma_api! {
     #[derive(Default)]
     response: {
         /// The user's avatar URL, if set.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/profile/set_avatar_url.rs b/ruma-client-api/src/r0/profile/set_avatar_url.rs
index cff062c7..5e9ee3b9 100644
--- a/ruma-client-api/src/r0/profile/set_avatar_url.rs
+++ b/ruma-client-api/src/r0/profile/set_avatar_url.rs
@@ -21,6 +21,9 @@ ruma_api! {
         /// The new avatar URL for the user.
         ///
         /// `None` is used to unset the avatar.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
diff --git a/ruma-client-api/src/r0/search/search_events.rs b/ruma-client-api/src/r0/search/search_events.rs
index c68a80cf..f356306a 100644
--- a/ruma-client-api/src/r0/search/search_events.rs
+++ b/ruma-client-api/src/r0/search/search_events.rs
@@ -436,6 +436,9 @@ impl SearchResult {
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct UserProfile {
     /// The user's avatar URL, if set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-client-api/src/r0/user_directory/search_users.rs b/ruma-client-api/src/r0/user_directory/search_users.rs
index 919890e8..09009010 100644
--- a/ruma-client-api/src/r0/user_directory/search_users.rs
+++ b/ruma-client-api/src/r0/user_directory/search_users.rs
@@ -78,6 +78,9 @@ pub struct User {
     pub display_name: Option<String>,
 
     /// The avatar url, as an MXC, if one exists.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-common/src/directory.rs b/ruma-common/src/directory.rs
index 81757993..22b54ccb 100644
--- a/ruma-common/src/directory.rs
+++ b/ruma-common/src/directory.rs
@@ -50,6 +50,9 @@ pub struct PublicRoomsChunk {
     pub guest_can_join: bool,
 
     /// The URL for the room's avatar, if one is set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-common/src/power_levels.rs b/ruma-common/src/power_levels.rs
index 373a5b05..a835ce84 100644
--- a/ruma-common/src/power_levels.rs
+++ b/ruma-common/src/power_levels.rs
@@ -10,6 +10,9 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct NotificationPowerLevels {
     /// The level required to trigger an `@room` notification.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level")]
     pub room: Int,
diff --git a/ruma-events/src/presence.rs b/ruma-events/src/presence.rs
index 2bd16731..c201ca36 100644
--- a/ruma-events/src/presence.rs
+++ b/ruma-events/src/presence.rs
@@ -26,6 +26,9 @@ pub struct PresenceEvent {
 #[ruma_event(type = "m.presence")]
 pub struct PresenceEventContent {
     /// The current avatar URL for this user.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-events/src/room/member.rs b/ruma-events/src/room/member.rs
index f6730927..063140ee 100644
--- a/ruma-events/src/room/member.rs
+++ b/ruma-events/src/room/member.rs
@@ -41,6 +41,9 @@ pub type MemberEvent = StateEvent<MemberEventContent>;
 #[ruma_event(type = "m.room.member")]
 pub struct MemberEventContent {
     /// The avatar URL for this user, if any. This is added by the homeserver.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
diff --git a/ruma-events/src/room/power_levels.rs b/ruma-events/src/room/power_levels.rs
index 4e55061f..99ff48d5 100644
--- a/ruma-events/src/room/power_levels.rs
+++ b/ruma-events/src/room/power_levels.rs
@@ -20,6 +20,9 @@ pub type PowerLevelsEvent = StateEvent<PowerLevelsEventContent>;
 #[ruma_event(type = "m.room.power_levels")]
 pub struct PowerLevelsEventContent {
     /// The level required to ban a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
     #[ruma_event(skip_redaction)]
@@ -28,6 +31,9 @@ pub struct PowerLevelsEventContent {
     /// The level required to send specific event types.
     ///
     /// This is a mapping from event type to power level required.
+    ///
+    /// If you activate the `compat` feature, the value being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(
         feature = "compat",
         serde(deserialize_with = "ruma_serde::btreemap_int_or_string_to_int_values")
@@ -37,29 +43,44 @@ pub struct PowerLevelsEventContent {
     pub events: BTreeMap<EventType, Int>,
 
     /// The default level required to send message events.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
     #[ruma_event(skip_redaction)]
     pub events_default: Int,
 
     /// The level required to invite a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
     pub invite: Int,
 
     /// The level required to kick a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
     #[ruma_event(skip_redaction)]
     pub kick: Int,
 
     /// The level required to redact an event.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
     #[ruma_event(skip_redaction)]
     pub redact: Int,
 
     /// The default level required to send state events.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
     #[ruma_event(skip_redaction)]
@@ -68,6 +89,9 @@ pub struct PowerLevelsEventContent {
     /// The power levels for specific users.
     ///
     /// This is a mapping from `user_id` to power level for that user.
+    ///
+    /// If you activate the `compat` feature, the value being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(
         feature = "compat",
         serde(deserialize_with = "ruma_serde::btreemap_int_or_string_to_int_values")
@@ -77,6 +101,9 @@ pub struct PowerLevelsEventContent {
     pub users: BTreeMap<UserId, Int>,
 
     /// The default power level for every user in the room.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
     #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
     #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
     #[ruma_event(skip_redaction)]
diff --git a/ruma-events/src/room/third_party_invite.rs b/ruma-events/src/room/third_party_invite.rs
index eb226ca3..8c7eebbc 100644
--- a/ruma-events/src/room/third_party_invite.rs
+++ b/ruma-events/src/room/third_party_invite.rs
@@ -17,14 +17,23 @@ pub type ThirdPartyInviteEvent = StateEvent<ThirdPartyInviteEventContent>;
 #[ruma_event(type = "m.room.third_party_invite")]
 pub struct ThirdPartyInviteEventContent {
     /// A user-readable string which represents the user who has been invited.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
     #[cfg_attr(feature = "compat", serde(default))]
     pub display_name: String,
 
     /// A URL which can be fetched to validate whether the key has been revoked.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
     #[cfg_attr(feature = "compat", serde(default))]
     pub key_validity_url: String,
 
     /// A Base64-encoded Ed25519 key with which the token must be signed.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
     #[cfg_attr(feature = "compat", serde(default))]
     pub public_key: String,
 
diff --git a/ruma-events/src/room/tombstone.rs b/ruma-events/src/room/tombstone.rs
index 0496a640..a886e0d6 100644
--- a/ruma-events/src/room/tombstone.rs
+++ b/ruma-events/src/room/tombstone.rs
@@ -15,6 +15,9 @@ pub type TombstoneEvent = StateEvent<TombstoneEventContent>;
 #[ruma_event(type = "m.room.tombstone")]
 pub struct TombstoneEventContent {
     /// A server-defined message.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
     #[cfg_attr(feature = "compat", serde(default))]
     pub body: String,
 
diff --git a/ruma-federation-api/src/query/get_profile_information/v1.rs b/ruma-federation-api/src/query/get_profile_information/v1.rs
index 03f12d88..18b9b587 100644
--- a/ruma-federation-api/src/query/get_profile_information/v1.rs
+++ b/ruma-federation-api/src/query/get_profile_information/v1.rs
@@ -32,6 +32,9 @@ ruma_api! {
         pub displayname: Option<String>,
 
         /// Avatar URL for the user's avatar.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",