diff --git a/.upgradenotes/MDL-84531-2025061213382940.yml b/.upgradenotes/MDL-84531-2025061213382940.yml
new file mode 100644
index 00000000000..3c299236fb2
--- /dev/null
+++ b/.upgradenotes/MDL-84531-2025061213382940.yml
@@ -0,0 +1,7 @@
+issueNumber: MDL-84531
+notes:
+  core:
+    - message: >-
+        The `\core\attribute\deprecated` attribute constructor `$replacement`
+        parameter now defaults to null, and can be omitted
+      type: changed
diff --git a/lib/classes/attribute/deprecated.php b/lib/classes/attribute/deprecated.php
index c68317bdf39..1128c6b5ef2 100644
--- a/lib/classes/attribute/deprecated.php
+++ b/lib/classes/attribute/deprecated.php
@@ -16,6 +16,8 @@
 
 namespace core\attribute;
 
+use core\exception\coding_exception;
+
 /**
  * Attribute to describe a deprecated item.
  *
@@ -25,10 +27,12 @@ namespace core\attribute;
  */
 #[\Attribute]
 class deprecated {
+
     /**
      * A deprecated item.
      *
-     * This attribute can be applied to any function, class, method, constant, property, enum, etc.
+     * This attribute can be applied to any function, class, method, constant, property, enum, etc. Note that at least one of
+     * $replacement, $since or $reason parameters must be non-null
      *
      * Note: The mere presence of the attribute does not do anything. It must be checked by some part of the code.
      *
@@ -40,7 +44,7 @@ class deprecated {
      * @param bool $emit Whether to emit a deprecation warning
      */
     public function __construct(
-        public readonly ?string $replacement,
+        public readonly ?string $replacement = null,
         public readonly ?string $since = null,
         public readonly ?string $reason = null,
         public readonly ?string $mdl = null,
@@ -48,8 +52,8 @@ class deprecated {
         public readonly bool $emit = true,
     ) {
         if ($replacement === null && $reason === null && $mdl === null) {
-            throw new \coding_exception(
-                'A deprecated item which is not deprecated must provide a reason, or an issue number.',
+            throw new coding_exception(
+                'A deprecated item must provide either a replacement, reason, or an issue number.',
             );
         }
     }
diff --git a/lib/tests/deprecation_test.php b/lib/tests/deprecation_test.php
index 5d68f7269a0..6e4268b6a48 100644
--- a/lib/tests/deprecation_test.php
+++ b/lib/tests/deprecation_test.php
@@ -187,11 +187,10 @@ final class deprecation_test extends \advanced_testcase {
         ];
     }
 
-    public function test_deprecated_without_replacement(): void {
+    public function test_deprecated_missing_constuctor_parameters(): void {
         $this->expectException(\coding_exception::class);
-        new deprecated(
-            replacement: null,
-        );
+        $this->expectExceptionMessage('A deprecated item must provide either a replacement, reason, or an issue number.');
+        new deprecated();
     }
 
     /**