From d79072b5de4cfe5a3029886d5a00326df392df23 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Mon, 13 Apr 2026 23:10:16 +0200
Subject: [PATCH] Update phantom T getter doc comments and expand changeset
 scope

Updated doc comments on ExtensionPoint.T and ServiceRef.T to reflect
that reading the value returns null rather than throwing. Expanded the
changeset to cover all three behavioral changes in the PR.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 .changeset/harmonize-phantom-t-getter.md                 | 2 +-
 packages/backend-plugin-api/src/services/system/types.ts | 2 +-
 packages/backend-plugin-api/src/wiring/types.ts          | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.changeset/harmonize-phantom-t-getter.md b/.changeset/harmonize-phantom-t-getter.md
index 970d4f18b2..99995cd8e2 100644
--- a/.changeset/harmonize-phantom-t-getter.md
+++ b/.changeset/harmonize-phantom-t-getter.md
@@ -2,4 +2,4 @@
 '@backstage/backend-plugin-api': patch
 ---
 
-Harmonized the phantom `.T` getter on `ExtensionPoint` to consistently return `null` instead of throwing.
+Harmonized the phantom `.T` getter behavior on `ExtensionPoint` and `ServiceRef` to consistently return `null` instead of throwing, and added `toJSON()` parity for `ExtensionPoint`.
diff --git a/packages/backend-plugin-api/src/services/system/types.ts b/packages/backend-plugin-api/src/services/system/types.ts
index 925156d3ae..a97d577ec4 100644
--- a/packages/backend-plugin-api/src/services/system/types.ts
+++ b/packages/backend-plugin-api/src/services/system/types.ts
@@ -50,7 +50,7 @@ export type ServiceRef<
 
   /**
    * Utility for getting the type of the service, using `typeof serviceRef.T`.
-   * Attempting to actually read this value will result in an exception.
+   * Reading this value will always return `null`. It is only intended for use with `typeof serviceRef.T`.
    */
   T: TService;
 
diff --git a/packages/backend-plugin-api/src/wiring/types.ts b/packages/backend-plugin-api/src/wiring/types.ts
index 9397cf597b..8d75c8923f 100644
--- a/packages/backend-plugin-api/src/wiring/types.ts
+++ b/packages/backend-plugin-api/src/wiring/types.ts
@@ -27,7 +27,7 @@ export type ExtensionPoint<T> = {
 
   /**
    * Utility for getting the type of the extension point, using `typeof extensionPoint.T`.
-   * Attempting to actually read this value will result in an exception.
+   * Reading this value will always return `null`. It is only intended for use with `typeof extensionPoint.T`.
    */
   T: T;