diff --git a/appendices/legacy.adoc b/appendices/legacy.adoc
index 58805b169..0002a63d4 100644
--- a/appendices/legacy.adoc
+++ b/appendices/legacy.adoc
@@ -98,6 +98,25 @@ provided in the pname:pNext chain of slink:VkDeviceCreateInfo instead of
 using slink:VkDeviceCreateInfo::pname:pEnabledFeatures.
 endif::VK_BASE_VERSION_1_1[]
 
+ifdef::VK_KHR_get_surface_capabilities2[]
+[[legacy-gpdsc2]]
+=== Physical Device Surface Queries: Superseded via version 2
+
+Some parts of apiext:VK_KHR_surface were superseded by
+apiext:VK_KHR_get_surface_capabilities2, which introduced new versions
+of some physical device surface query functions.
+These provide the same functionality as the VK_KHR_surface functionality
+but with greater extensibility.
+
+When querying surface capabilities,
+flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR should: be used instead of
+flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
+
+When querying surface formats,
+flink:vkGetPhysicalDeviceSurfaceFormats2KHR should: be used instead of
+flink:vkGetPhysicalDeviceSurfaceFormatsKHR.
+endif::VK_KHR_get_surface_capabilities2[]
+
 
 ifndef::VKSC_VERSION_1_0[]
 // these were never included in VKSC 1.0
diff --git a/xml/vk.xml b/xml/vk.xml
index bf86758ae..63e136711 100644
--- a/xml/vk.xml
+++ b/xml/vk.xml
@@ -23371,6 +23371,12 @@ endif::VK_KHR_internally_synchronized_queues[]
                 <command name="vkGetPhysicalDeviceSurfaceCapabilities2KHR"/>
                 <command name="vkGetPhysicalDeviceSurfaceFormats2KHR"/>
             </require>
+            <deprecate explanationlink="legacy-gpdsc2">
+                <type name="VkSurfaceCapabilitiesKHR"/>
+                <type name="VkSurfaceFormatKHR"/>
+                <command name="vkGetPhysicalDeviceSurfaceCapabilitiesKHR" supersededby="vkGetPhysicalDeviceSurfaceCapabilities2KHR"/>
+                <command name="vkGetPhysicalDeviceSurfaceFormatsKHR" supersededby="vkGetPhysicalDeviceSurfaceFormats2KHR"/>
+            </deprecate>
         </extension>
         <extension name="VK_KHR_variable_pointers" number="121" type="device" author="KHR" contact="Jesse Hall @critsec" depends="(VK_KHR_get_physical_device_properties2+VK_KHR_storage_buffer_storage_class),VK_VERSION_1_1" supported="vulkan" promotedto="VK_VERSION_1_1" ratified="vulkan">
             <require>