Skip to content

Component Spec

type [Required]

The type of Component as a string, e.g. type: service.

Whilst the type of a Component may be any string, it is strongly recommended that you use one of the common values. Futher to this, tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites. Thus we recommend that when specifying a component one of the following is used in this field:

  • library - a software library
  • service - a backend service, typically exposing an API
  • user-interface - a local user interface
  • website - a web user interface

lifecycle [Required]

The lifecycle state of the Component as a string, e.g. lifecycle: production.

Whilst the spec.type of a Component or API may be any string, understanding is made easier by sticking to a small set of well-known and common values. Thus we recommend that when specifying an entity one of the following is used in this field:

  • experimental - an experiment or early, non-production entity, signaling that users may not prefer to consume it over other more established entities, or that there are low or no reliability guarantees
  • production - an established, owned, maintained entity
  • deprecated - an entity that is at the end of its lifecycle, and may disappear at a later point in time

owner [Required]

An entity reference to the owner of the entity, e.g. owner: user:enu43627. Users and Groups are automatically populated, and can listed in the catalog by filtering by Kind of User or Group respectively.

The owner of an entity is the group or user that bears ultimate responsibility for the entity, and has the authority and capability to develop and maintain it. They will be the point of contact if something goes wrong, or if features are to be requested. The main purpose of this field is for display purposes in Backstage, so that people looking at catalog items can get an understanding of to whom this entity belongs. It is not to be used by automated processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the entity, but there will always be one ultimate owner.

system [Optional]

An entity reference to the System that the entity belongs to, e.g. developer-portal. There is no requirement for this System to be created within the same location; Existing Systems can be listed in the catalog by filtering by Kind of System.

subcomponentOf [Optional]

An entity reference to another Component of which this Component is part of, e.g. subComponentOf: developer-portal-frontend. There is no requirement for this Component to be created within the same location; Existing Components can be listed in the catalog by filtering by Kind of Component.

providesApis [Optional]

An array of entity references to the APIs that are provided by the Component, e.g. providesApis: [developer-portal-backend-rest]. There is no requirement for these APIs to be created within the same location; Existing APIs can be listed in the catalog by filtering by Kind of API.

consumesApis [Optional]

An array of entity references to the APIs that are consumed by the Component, e.g. consumesApis: [developer-portal-backend-rest]. There is no requirement for these APIs to be created within the same location; Existing APIs can be listed in the catalog by filtering by Kind of API.

dependsOn [Optional]

An array of entity references to the Components and Resources that this entity depends on, e.g. dependsOn: [component:developer-portal-backend]. There is no requirement for these entities to be created within the same location; Existing entities can be listed in the catalog.