diff --git a/.changeset/shaggy-melons-drive.md b/.changeset/shaggy-melons-drive.md new file mode 100644 index 0000000000..b5674493f4 --- /dev/null +++ b/.changeset/shaggy-melons-drive.md @@ -0,0 +1,5 @@ +--- +'@backstage/catalog-model': minor +--- + +Adding an optional type field to entity links to group and categorize links diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 86c832e3d2..81e3604ffe 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -55,6 +55,7 @@ metadata: - url: https://admin.example-org.com title: Admin Dashboard icon: dashboard + type: admin-dashboard spec: type: website lifecycle: production @@ -83,7 +84,8 @@ This is the same entity as returned in JSON from the software catalog API: { "url": "https://admin.example-org.com", "title": "Admin Dashboard", - "icon": "dashboard" + "icon": "dashboard", + "type": "admin-dashboard" } ], "tags": ["java"], @@ -353,6 +355,7 @@ Fields of a link are: | `url` | String | [Required] A `url` in a standard `uri` format (e.g. `https://example.com/some/page`) | | `title` | String | [Optional] A user friendly display name for the link. | | `icon` | String | [Optional] A key representing a visual icon to be displayed in the UI. | +| `type` | String | [Optional] An optional value to categorize links into specific groups. | _NOTE_: The `icon` field value is meant to be a semantic key that will map to a specific icon that may be provided by an icon library (e.g. `material-ui` @@ -362,6 +365,8 @@ Backstage integrator will ultimately be left to provide the appropriate icon component mappings. A generic fallback icon would be provided if a mapping cannot be resolved. +The semantics of the `type` field are undefined. The adopter is free to define their own set of types and utilize them as they wish. Some potential use cases can be to utilize the type field to validate certain links exist on entities or to create customized UI components for specific link types. + ## Common to All Kinds: Relations The `relations` root field is a read-only list of relations, between the current diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index fca23d6ab9..8427ef4112 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -159,6 +159,7 @@ export type EntityLink = { url: string; title?: string; icon?: string; + type?: string; }; // @public diff --git a/packages/catalog-model/src/entity/Entity.ts b/packages/catalog-model/src/entity/Entity.ts index 96f19b2c8a..80c9adaffb 100644 --- a/packages/catalog-model/src/entity/Entity.ts +++ b/packages/catalog-model/src/entity/Entity.ts @@ -210,4 +210,9 @@ export type EntityLink = { * An optional semantic key that represents a visual icon. */ icon?: string; + + /** + * An optional value to categorize links into specific groups + */ + type?: string; }; diff --git a/packages/catalog-model/src/schema/EntityMeta.schema.json b/packages/catalog-model/src/schema/EntityMeta.schema.json index cfdf9539c2..483e69f672 100644 --- a/packages/catalog-model/src/schema/EntityMeta.schema.json +++ b/packages/catalog-model/src/schema/EntityMeta.schema.json @@ -108,6 +108,12 @@ "description": "A key representing a visual icon to be displayed in the UI.", "examples": ["dashboard"], "minLength": 1 + }, + "type": { + "type": "string", + "description": "An optional value to categorize links into specific groups.", + "examples": ["runbook", "documentation", "logs", "dashboard"], + "minLength": 1 } } }