diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index f0151d7618..383fd698f9 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -251,6 +251,23 @@ the entity belongs to the `"default"` namespace.
 Namespaces may also be part of the catalog, and are `v1` / `Namespace` entities,
 i.e. not Backstage specific but the same as in Kubernetes.
 
+### `uid` [output]
+
+Each entity gets an automatically generated globally unique ID when it first
+enters the database. This field is not meant to be specified as input data, but
+is rater created by the database engine itself when producing the output entity.
+
+Note that `uid` values are _not_ to be seen as stable, and should _not_ be used
+as external references to an entity. The `uid` can change over time even when a
+human observer might think that it wouldn't. As one of many examples,
+unregistering and re-registering the exact same file will result in a different
+`uid` value even though everything else is the same. Therefore there is very
+little, if any, reason to read or use this field externally.
+
+If you want to refer to an entity by some form of an identifier, you should
+always use [string-form entity reference](references.md#string-references)
+instead.
+
 ### `title` [optional]
 
 A display name of the entity, to be presented in user interfaces instead of the