document the metadata.uid field

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2022-12-22 14:07:22 +01:00
parent 330fad5046
commit 71ec7585a8
1 changed files with 17 additions and 0 deletions
@@ -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