Add the metadata.title field to all kinds

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/strange-zoos-grab.md

@@ -0,0 +1,11 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Add an optional `metadata.title` field to all entity kinds.
+
+This used to be available on only the `Template` kind, and we have decided that the metadata block should be the same for all kinds. A title can be useful especially in large and complex catalogs where users have a tough time navigating or discerning among the entities.
+
+It also carries some risk. You do not want to end up giving a title that collides with an actual name, which at best leads to confusion and at worst could be a liability. We do not perform any collision detection in the catalog. If you want to disallow this facility you may want to add a small processor that makes sure it's not set.
+
+At the time of writing this message, only the scaffolder actually makes use of this field for display purposes.

docs/features/software-catalog/descriptor-format.md

@@ -245,6 +245,22 @@ 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.
 
+### `title` [optional]
+
+A nice display name of the entity, to be presented in user interfaces instead of
+the `name` property above, when available.
+
+This field is sometimes useful when the `name` is cumbersome or ends up being
+perceived as overly technical. The title generally does not have as stringent
+format requirements on it, so it may contain special characters and be more
+explanatory. Do keep it very short though, and avoid situations where a title
+can be confused with the name of another entity, or where two entities share a
+title.
+
+Note that this is only for display purposes, and may be ignored by some parts of
+the code. [Entity references](references.md) still always make use of the `name`
+property for example, not the title.
+
 ### `description` [optional]
 
 A human readable description of the entity, to be shown in Backstage. Should be
@@ -690,12 +706,6 @@ shape, this kind has the following structure.
 
 Exactly equal to `backstage.io/v1beta2` and `Template`, respectively.
 
-### `metadata.title` [required]
-
-The nice display name for the template as a string, e.g. `React SSR Template`.
-This field is required as is used to reference the template to the user instead
-of the `metadata.name` field.
-
 ### `metadata.tags` [optional]
 
 A list of strings that can be associated with the template, e.g.

packages/catalog-model/api-report.md

@@ -230,6 +230,7 @@ export type EntityMeta = JsonObject & {
   generation?: number;
   name: string;
   namespace?: string;
+  title?: string;
   description?: string;
   labels?: Record<string, string>;
   annotations?: Record<string, string>;
@@ -722,10 +723,6 @@ export interface TemplateEntityV1beta2 extends Entity {
   // (undocumented)
   kind: 'Template';
   // (undocumented)
-  metadata: EntityMeta & {
-    title?: string;
-  };
-  // (undocumented)
   spec: {
     type: string;
     parameters?: JsonObject | JsonObject[];

packages/catalog-model/src/entity/Entity.ts

@@ -103,7 +103,13 @@ export type EntityMeta = JsonObject & {
    * The name of the entity.
    *
    * Must be unique within the catalog at any given point in time, for any
-   * given namespace + kind pair.
+   * given namespace + kind pair. This value is part of the technical
+   * identifier of the entity, and as such it will appear in URLs, database
+   * tables, entity references, and similar. It is subject to restrictions
+   * regarding what characters are allowed.
+   *
+   * If you want to use a different, more human readable string with fewer
+   * restrictions on it in user interfaces, see the `title` field below.
    */
   name: string;
 
@@ -112,6 +118,23 @@ export type EntityMeta = JsonObject & {
    */
   namespace?: string;
 
+  /**
+   * A nice display name of the entity, to be presented in user interfaces
+   * instead of the `name` property above, when available.
+   *
+   * This field is sometimes useful when the `name` is cumbersome or ends up
+   * being perceived as overly technical. The title generally does not have
+   * as stringent format requirements on it, so it may contain special
+   * characters and be more explanatory. Do keep it very short though, and
+   * avoid situations where a title can be confused with the name of another
+   * entity, or where two entities share a title.
+   *
+   * Note that this is only for display purposes, and may be ignored by some
+   * parts of the code. Entity references still always make use of the `name`
+   * property, not the title.
+   */
+  title?: string;
+
   /**
    * A short (typically relatively few words, on one line) description of the
    * entity.

packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts

@@ -15,16 +15,13 @@
  */
 
 import { JsonObject } from '@backstage/config';
-import type { Entity, EntityMeta } from '../entity/Entity';
+import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Template.v1beta2.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
 export interface TemplateEntityV1beta2 extends Entity {
   apiVersion: 'backstage.io/v1beta2';
   kind: 'Template';
-  metadata: EntityMeta & {
-    title?: string;
-  };
   spec: {
     type: string;
     parameters?: JsonObject | JsonObject[];

packages/catalog-model/src/schema/EntityMeta.schema.json

@@ -53,6 +53,12 @@
       "examples": ["default", "admin"],
       "minLength": 1
     },
+    "title": {
+      "type": "string",
+      "description": "A nice display name of the entity, to be presented in user interfaces instead of the name property, when available.",
+      "examples": ["React SSR Template"],
+      "minLength": 1
+    },
     "description": {
       "type": "string",
       "description": "A short (typically relatively few words, on one line) description of the entity."

packages/catalog-model/src/schema/kinds/Template.v1beta2.schema.json

@@ -69,17 +69,6 @@
         "kind": {
           "enum": ["Template"]
         },
-        "metadata": {
-          "type": "object",
-          "properties": {
-            "title": {
-              "type": "string",
-              "description": "The nice display name for the template.",
-              "examples": ["React SSR Template"],
-              "minLength": 1
-            }
-          }
-        },
         "spec": {
           "type": "object",
           "required": ["type", "steps"],

packages/catalog-model/src/validation/entitySchemaValidator.test.ts

@@ -30,6 +30,8 @@ describe('entitySchemaValidator', () => {
         generation: 13,
         name: 'test',
         namespace: 'ns',
+        title: 'My Component, Yay',
+        description: 'Yeah this is probably the best component so far',
         labels: {
           'backstage.io/custom': 'ValueStuff',
         },
@@ -192,6 +194,21 @@ describe('entitySchemaValidator', () => {
     expect(() => validator(entity)).toThrow(/namespace/);
   });
 
+  it('accepts missing title', () => {
+    delete entity.metadata.title;
+    expect(() => validator(entity)).not.toThrow();
+  });
+
+  it('rejects bad title type', () => {
+    entity.metadata.title = 7;
+    expect(() => validator(entity)).toThrow(/title/);
+  });
+
+  it('rejects empty title', () => {
+    entity.metadata.title = '';
+    expect(() => validator(entity)).toThrow(/title/);
+  });
+
   it('accepts missing description', () => {
     delete entity.metadata.description;
     expect(() => validator(entity)).not.toThrow();