diff --git a/.changeset/2628.md b/.changeset/2628.md
new file mode 100644
index 0000000000..76ad2488fb
--- /dev/null
+++ b/.changeset/2628.md
@@ -0,0 +1,21 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+This feature works the same as $secret does in config - it allows programmatic substitution of values into a document.
+
+This is particularly useful e.g. for API type entities where you do not want to repeat your entire API spec document inside the catalog-info.yaml file. For those cases, you can instead do something like
+
+```
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: my-federated-service
+spec:
+  type: graphql
+  definition:
+    $text: ./schema.graphql
+```
+
+The textual content of that file will be injected as the value of definition, during each refresh loop. Both relative and absolute paths are supported, as well as any HTTP/HTTPS URL pointing to a service that returns the relevant data.
+
+The initial version supports injection of text file data, and structured data from JSON and YAML files. You can add any handler of your own in addition to these.