diff --git a/doc/gitsigns.txt b/doc/gitsigns.txt
index 487f75def..14e87964d 100644
--- a/doc/gitsigns.txt
+++ b/doc/gitsigns.txt
@@ -873,8 +873,7 @@ trouble                                              *gitsigns-config-trouble*
 
 yadm                                                    *gitsigns-config-yadm*
    DEPRECATED
-
-   Please instead use |gitsigns-config-on_attach_pre|.
+      Please use |gitsigns-config-on_attach_pre| instead
 
       Type: `table`
       Default: >
diff --git a/lua/gitsigns/config.lua b/lua/gitsigns/config.lua
index 61d88d54f..96f2613f2 100644
--- a/lua/gitsigns/config.lua
+++ b/lua/gitsigns/config.lua
@@ -1,9 +1,21 @@
+--- @class (exact) Gitsigns.SchemaElem.Deprecated
+---
+--- Used for renaming fields.
+--- @field new_field string
+---
+--- Documentation for deprecation. Will be added to the help file and used in
+--- the notification if `hard = true`.
+--- @field message string
+---
+--- Emit a message via vim.notify
+--- @field hard boolean
+
 --- @class (exact) Gitsigns.SchemaElem
 --- @field type string|string[]
 --- @field refresh? fun(cb: fun()) Function to refresh the config value
 --- @field deep_extend? boolean
 --- @field default any
---- @field deprecated? boolean|{new_field:string,message:string,hard:boolean}
+--- @field deprecated? boolean|Gitsigns.SchemaElem.Deprecated
 --- @field default_help? string
 --- @field description string
 
@@ -752,7 +764,7 @@ M.schema = {
   yadm = {
     type = 'table',
     deprecated = {
-      new_field = 'on_attach_pre',
+      message = 'Please use |gitsigns-config-on_attach_pre| instead',
     },
     default = { enable = false },
     description = [[