Skip to main content


Home > @backstage/catalog-model

Types and validators that help describe the model of a Backstage Catalog


CommonValidatorFunctionsContains various helper validation and normalization functions that can be composed to form a Validator.
DefaultNamespaceEntityPolicySets a default namespace if none was set.
FieldFormatEntityPolicyEnsures that the format of individual fields of the entity envelope is valid.
GroupDefaultParentEntityPolicyDefaultParentPolicy is an EntityPolicy that updates group entities with a parent of last resort. This ensures that, while we preserve any existing group hierarchies, we can guarantee that there is a single global root of the group hierarchy.
KubernetesValidatorFunctionsContains validation functions that match the Kubernetes spec, usable to build a catalog that is compatible with those rule sets.
NoForeignRootFieldsEntityPolicyEnsures that there are no foreign root fields in the entity.
SchemaValidEntityPolicyEnsures that the entity spec is valid according to a schema.


entityEnvelopeSchemaValidator(schema)Creates a validation function that takes some arbitrary data, and either returns that data cast to an EntityEnvelope (or the given subtype) if it matches that schema, or throws a describing the errors.
entityKindSchemaValidator(schema)Creates a validation function that takes some arbitrary data, and either returns that data cast to a T if it matches that schema, or false if the schema apiVersion/kind didn't apply to that data, or throws a describing actual errors.
entitySchemaValidator(schema)Creates a validation function that takes some arbitrary data, and either returns that data cast to an Entity (or the given subtype) if it matches that schema, or throws a describing the errors.
getCompoundEntityRef(entity)Extracts the kind, namespace and name that form the compound entity ref triplet of the given entity.
getEntitySourceLocation(entity)Returns the source code location of the Entity, to the extent that one exists.
makeValidator(overrides)Creates a Validators object from overrides, with default values taken from KubernetesValidatorFunctions
parseEntityRef(ref, context)Parses an entity reference, either on string or compound form, and returns a structure with a name, and optional kind and namespace.
parseLocationRef(ref)Parses a string form location reference.
stringifyEntityRef(ref)Takes an entity or entity name/reference, and returns the string form of an entity ref.
stringifyLocationRef(ref)Turns a location ref into its string form.


ApiEntityV1alpha1Backstage API kind Entity. APIs describe the interfaces for Components to communicate.
ComponentEntityV1alpha1Backstage catalog Component kind Entity. Represents a single, individual piece of software.
DomainEntityV1alpha1Backstage Domain kind Entity. Domains group Systems together.
GroupEntityV1alpha1Backstage catalog Group kind Entity.
LocationEntityV1alpha1Backstage catalog Location kind Entity.
ResourceEntityV1alpha1Backstage catalog Resource kind Entity. Represents infrastructure required to operate Components.
SystemEntityV1alpha1Backstage catalog System kind Entity. Systems group Components, Resources and APIs together.
UserEntityV1alpha1Backstage catalog User kind Entity.


ANNOTATION_EDIT_URLAnnotation for linking to entity edit page from catalog pages.
ANNOTATION_KUBERNETES_API_SERVER_CAAnnotation for specifying the Certificate Authority of an API server for a Kubernetes cluster
ANNOTATION_KUBERNETES_API_SERVERAnnotation for specifying the API server of a Kubernetes cluster
ANNOTATION_KUBERNETES_AUTH_PROVIDERAnnotation for specifying the auth provider for a Kubernetes cluster
ANNOTATION_LOCATIONEntity annotation containing the location from which the entity is sourced.
ANNOTATION_ORIGIN_LOCATIONEntity annotation containing the originally sourced location which ultimately led to this entity being ingested.
ANNOTATION_SOURCE_LOCATIONEntity annotation pointing to the source (e.g. source code repository root or similar) for this entity.
ANNOTATION_VIEW_URLAnnotation for linking to entity page from catalog pages.
apiEntityV1alpha1ValidatorKindValidator for ApiEntityV1alpha1.
componentEntityV1alpha1ValidatorKindValidator for ComponentEntityV1alpha1.
DEFAULT_NAMESPACEThe namespace that entities without an explicit namespace fall into.
domainEntityV1alpha1ValidatorKindValidator for DomainEntityV1alpha1.
EntityPoliciesProvides helpers for enforcing a set of EntityPolicy in an and/or expression.
groupEntityV1alpha1ValidatorKindValidator for GroupEntityV1alpha1.
locationEntityV1alpha1ValidatorKindValidator for LocationEntityV1alpha1.
RELATION_API_CONSUMED_BYA relation of an API being consumed, typically by a component. Reversed direction of RELATION_CONSUMES_API.
RELATION_API_PROVIDED_BYA relation from an API to its provider entity (typically a component). Reversed direction of RELATION_PROVIDES_API.
RELATION_CHILD_OFA relation from a child to a parent entity, used for example to describe the organizational structure between groups. Reversed direction of RELATION_PARENT_OF.
RELATION_CONSUMES_APIA relation with an API entity, typically from a component. Reversed direction of RELATION_API_CONSUMED_BY.
RELATION_DEPENDENCY_OFA relation denoting a reverse dependency by another entity. Reversed direction of RELATION_DEPENDS_ON.
RELATION_DEPENDS_ONA relation denoting a dependency on another entity. Reversed direction of RELATION_DEPENDENCY_OF.
RELATION_HAS_MEMBERA relation from a group to its member, typcally a user in a group. Reversed direction of RELATION_MEMBER_OF.
RELATION_HAS_PARTA relation from a containing entity to a contained entity. Reversed direction of RELATION_PART_OF.
RELATION_MEMBER_OFA membership relation, typically for users in a group. Reversed direction of RELATION_HAS_MEMBER.
RELATION_OWNED_BYAn ownership relation where the owner is usually an organizational entity (user or group), and the other entity can be anything. Reversed direction of RELATION_OWNER_OF.
RELATION_OWNER_OFA relationship from an owner to the owned entity. Reversed direction of RELATION_OWNED_BY.
RELATION_PARENT_OFA parent/child relation to build up a tree, used for example to describe the organizational structure between groups. Reversed direction of RELATION_CHILD_OF.
RELATION_PART_OFA part/whole relation, typically for components in a system and systems in a domain. Reversed direction of RELATION_HAS_PART.
RELATION_PROVIDES_APIA relation from an API provider entity (typically a component) to the API. Reversed direction of RELATION_API_PROVIDED_BY.
resourceEntityV1alpha1ValidatorKindValidator for ResourceEntityV1alpha1.
systemEntityV1alpha1ValidatorKindValidator for SystemEntityV1alpha1.
userEntityV1alpha1ValidatorKindValidator for UserEntityV1alpha1.

Type Aliases

Type AliasDescription
CompoundEntityRefAll parts of a complete entity ref, forming a full kind-namespace-name triplet.
EntityThe parts of the format that's common to all versions/kinds of entity.
EntityEnvelopeThe envelope skeleton parts of an entity - whatever is necessary to be able to give it a ref and pass to further validation / policy checking.
EntityLinkA link to external information that is related to the entity.
EntityMetaMetadata fields common to all versions/kinds of entity.
EntityPolicyA policy for validation or mutation to be applied to entities as they are entering the system.
EntityRelationA relation of a specific type to another entity in the catalog.
KindValidatorValidates entities of a certain kind.
ValidatorsType alias for implementing validators of various entity objects.