From 71ec7585a81bd19ddb288cd341339087b9836e8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Thu, 22 Dec 2022 14:07:22 +0100 Subject: [PATCH] document the metadata.uid field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .../software-catalog/descriptor-format.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) 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