import { Entity } from '@backstage/catalog-model'; import { SerializedError } from '@backstage/errors'; import { JsonObject, JsonValue } from '@backstage/types'; /** * An opaque type that represents a set of catalog model layers. * * @alpha */ interface CatalogModelLayer { readonly $$type: '@backstage/CatalogModelLayer'; /** * The unique ID of the model layer. * * @remarks * @example `catalog.backstage.io/kind-api` * * This identifier is used for purposes of deduplication and tracking. It is * expected to be stable and descriptive. Prefer prefixing the ID with a * matching domain name. The backstage.io domain name is reserved for use by * the Backstage project itself. */ readonly layerId: string; } /** * A compiled catalog model. * * @alpha */ interface CatalogModel { /** * Lists all kinds in the model. */ listKinds(): CatalogModelKindSummary[]; /** * Lists all relations in the model. */ listRelations(): CatalogModelRelationSummary[]; /** * Returns summaries of the shared metadata fields in the model, including * all declared annotations, labels, and tags. */ getMetadata(): { annotations: CatalogModelAnnotationSummary[]; labels: CatalogModelLabelSummary[]; tags: CatalogModelTagSummary[]; }; /** * Look up a kind in the model. * * @returns The kind if found, or `undefined` if no matching kind exists. * @throws TypeError if the kind exists in the model, but not for this apiVersion or type. */ getKind(options: { kind: string; apiVersion: string; spec?: { type?: string; }; }): CatalogModelKind | undefined; /** * Look up all relations that originate from a given kind. * * @param kind - The kind name, e.g. "Component". * @returns The relations originating from the kind, or `undefined` if the * kind is not known. */ getRelations(options: { kind: string; }): CatalogModelRelation[] | undefined; } /** * A compiled catalog model kind. * * @alpha */ interface CatalogModelKind { /** * A human-readable description of the kind. */ description: string; /** * The API version(s) of the kind that this schema applies to, e.g. * "backstage.io/v1alpha1". */ apiVersions: string[]; /** * The names used for this kind. */ names: { /** * The name of the kind with proper casing, e.g. "Component". */ kind: string; /** * The singular form of the kind name, e.g. "component". */ singular: string; /** * The plural form of the kind name, e.g. "components". */ plural: string; }; /** * The relation fields declared for this kind, with full dot-separated paths * into the entity (e.g. "spec.owner"). */ relationFields: Array<{ /** * The full dot-separated path to the field in the entity, e.g. "spec.owner". */ path: string; /** * The relation type that this field generates, e.g. "ownedBy". */ relation: string; /** * The default kind for parsing shorthand entity refs. */ defaultKind?: string; /** * The default namespace for parsing shorthand entity refs. */ defaultNamespace?: 'inherit' | 'default'; /** * The kinds that are allowed as targets for this relation field. */ allowedKinds?: string[]; }>; /** * The JSON schema of the kind. * * @remarks * * This can be used for validation of entities. Note that it is up to the * caller to ensure that the kind and apiVersion match what you are validating * against. */ jsonSchema: JsonObject; } /** * A summary of a catalog model kind, without version-specific details such as * schemas and relation fields. * * @alpha */ interface CatalogModelKindSummary { /** * A human-readable description of the kind. */ description: string; /** * The names used for this kind. */ names: { /** * The name of the kind with proper casing, e.g. "Component". */ kind: string; /** * The singular form of the kind name, e.g. "component". */ singular: string; /** * The plural form of the kind name, e.g. "components". */ plural: string; }; /** * The available versions and spec types for this kind. * * @remarks * * Each entry represents a unique apiVersion/specType combination that can be * passed to {@link CatalogModel.getKind} to retrieve the full kind details. */ versions: Array<{ /** * The API version, e.g. "backstage.io/v1alpha1". */ apiVersion: string; /** * The spec type, if any, e.g. "service". Undefined means the default * (untyped) version. */ specType?: string; }>; } /** * A compiled catalog model relation. * * @alpha */ interface CatalogModelRelation { /** * The kinds that this relation can originate from. */ fromKind: string[]; /** * The kinds that this relation can point to. */ toKind: string[]; /** * A human-readable description of the relation. */ description: string; /** * The forward direction of this relation. */ forward: { type: string; title: string; }; /** * The reverse direction of this relation. */ reverse: { type: string; title: string; }; } /** * A summary of a catalog model annotation. * * @alpha */ interface CatalogModelAnnotationSummary { /** * The annotation key, e.g. "backstage.io/managed-by-location". */ name: string; /** * A short human-readable title for the annotation. */ title?: string; /** * A human-readable description of the annotation. */ description: string; } /** * A summary of a catalog model label. * * @alpha */ interface CatalogModelLabelSummary { /** * The label key, e.g. "backstage.io/orphan". */ name: string; /** * A short human-readable title for the label. */ title?: string; /** * A human-readable description of the label. */ description: string; } /** * A summary of a catalog model tag. * * @alpha */ interface CatalogModelTagSummary { /** * The tag value, e.g. "java". */ name: string; /** * A short human-readable title for the tag. */ title?: string; /** * A human-readable description of the tag. */ description: string; } /** * A summary of a catalog model relation. * * @alpha */ interface CatalogModelRelationSummary { /** * The kinds that this relation can originate from. */ fromKind: string[]; /** * The kinds that this relation can point to. */ toKind: string[]; /** * A human-readable description of the relation. */ description: string; /** * The forward direction of this relation. */ forward: { type: string; title: string; }; /** * The reverse direction of this relation. */ reverse: { type: string; title: string; }; } /** * Compiles a set of catalog model layers into a single unified * catalog model. * * @alpha * @param inputs - The layers to compile. * @returns The compiled catalog model. */ declare function compileCatalogModel(inputs: Iterable): CatalogModel; /** * The definition of a catalog model annotation. * * @alpha */ interface CatalogModelAnnotationDefinition { /** * The name of the annotation, e.g. "backstage.io/techdocs-ref". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the annotation. */ description: string; /** * The JSON schema that values of this annotation must conform to. * * @remarks * * If not provided, the annotation is assumed to be a simple string with no * particular schema. */ schema?: { jsonSchema: JsonObject; }; } /** * The definition of a catalog model kind, roughly resembling a JSON Schema. * * @alpha */ interface CatalogModelKindDefinition { /** * The apiVersion group of the kind, e.g. "backstage.io". */ group: string; /** * The names used for this kind. */ names: { /** * The name of the kind with proper casing, e.g. "Component". */ kind: string; /** * The singular form of the kind name, e.g. "component". */ singular: string; /** * The plural form of the kind name, e.g. "components". */ plural: string; }; /** * A short description of the kind. * * @remarks * * For kinds that have wide applicability over for example several different * spec types, this description should be a generic one and the types * themselves can be more precise. */ description: string; /** * Declare one or more versions of the kind's actual schema shape. */ versions?: CatalogModelKindVersionDefinition[]; } /** * The definition of one or more specific versions of a catalog model kind. * * @alpha */ interface CatalogModelKindVersionDefinition { /** * The specific version name or names, e.g. "v1alpha1" or * ["v1alpha1", "v1beta1"]. The kind group and the version name form the * full apiVersion, e.g. "backstage.io/v1alpha1". */ name: string | string[]; /** * The spec type or types that this version applies to. * * @remarks * * This can be used to make kinds whose spec effectively are discriminated * unions. If you don't specify this, the schema will apply to a spec that * has no type given at all, or to those where the type is not among the set * of any other known declared spec types. * * TODO: Should this be more like `matcher: { [path: string]: string }`, or * even a full JSON Schema that can be used in an "if"? */ specType?: string | string[]; /** * A short description of this particular version (and type, where applicable). */ description?: string; /** * The fields that shall be used to generate relations, if any. * * TODO: Should this be not an array, to be more easily mergeable? Or should * we just have a custom merge strategy for them */ relationFields?: CatalogModelKindRelationFieldDefinition[]; schema: { jsonSchema: JsonObject; }; } /** * @alpha */ interface CatalogModelKindRelationFieldDefinition { /** * What field that shall be used to generate relations. * * @remarks * * The field value is expected to be a string or string array at runtime. */ selector: { path: string; }; /** * The relation type that this field generates, e.g. "ownedBy". */ relation: string; /** * If the given shorthand ref did not have a kind, use this kind as the * default. If no default kind is specified, the ref must contain a kind. */ defaultKind?: string; /** * If the given shorthand ref did not have a namespace, either inherit the * namespace of the entity itself, or choose the default namespace. If no * default namespace is specified, the namespace of the entity itself is used. */ defaultNamespace?: 'default' | 'inherit'; /** * Only allow relations to be specified to the given kinds. This list must * include the default kind, if any. If no allowed kinds are specified, all * kinds are. */ allowedKinds?: string[]; } /** * The definition of a catalog model label. * * @alpha */ interface CatalogModelLabelDefinition { /** * The name of the label, e.g. "backstage.io/source-location". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the label. */ description: string; /** * The JSON schema that values of this label must conform to. * * @remarks * * If not provided, the label is assumed to be a simple string with no * particular schema. */ schema?: { jsonSchema: JsonObject; }; } /** * The definition of a catalog model relation. * * @alpha */ interface CatalogModelRelationPairDefinition { /** * The kind(s) that this relation originates from, e.g. "Component" or * ["Component", "Resource"]. */ fromKind: string | string[]; /** * The kind(s) that this relation points to, e.g. "Group" or * ["Group", "User"]. */ toKind: string | string[]; /** * A human-readable description of the relation. */ description: string; /** * The names for the forward direction (from the current entity toward * the one being referenced). */ forward: { /** * The technical type of the relation, e.g. "ownedBy" */ type: string; /** * A human-readable title for the relation type, e.g. "owned by". */ title: string; }; /** * The names for the reverse direction (from the one being referenced * toward the current entity). */ reverse: { /** * The technical type of the relation, e.g. "ownerOf" */ type: string; /** * A human-readable title for the relation type, e.g. "owner of". */ title: string; }; } /** * The definition of an annotation removal from the catalog model. * * @alpha */ interface CatalogModelRemoveAnnotationDefinition { /** * The name of the annotation to remove, e.g. "backstage.io/techdocs-ref". */ name: string; } /** * The definition of a kind removal from the catalog model. * * @alpha */ interface CatalogModelRemoveKindDefinition { /** * The kind to remove, e.g. "Component". */ kind: string; } /** * The definition of a label removal from the catalog model. * * @alpha */ interface CatalogModelRemoveLabelDefinition { /** * The name of the label to remove, e.g. "backstage.io/source-location". */ name: string; } /** * The definition of a tag removal from the catalog model. * * @alpha */ interface CatalogModelRemoveTagDefinition { /** * The name of the tag to remove, e.g. "java". */ name: string; } /** * The definition of a catalog model tag. * * @alpha */ interface CatalogModelTagDefinition { /** * The name of the tag, e.g. "java". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the tag. */ description: string; } /** * The definition of updates to a catalog model annotation. * * @alpha */ interface CatalogModelUpdateAnnotationDefinition { /** * The name of the annotation, e.g. "backstage.io/techdocs-ref". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the annotation. */ description?: string; /** * The JSON schema that values of this annotation must conform to. * * @remarks * * If not provided, the annotation is assumed to be a simple string with no * particular schema. */ schema?: { jsonSchema: JsonObject; }; } /** * The definition of updates to a catalog model kind. * * @alpha */ interface CatalogModelUpdateKindDefinition { /** * The names used for this kind. */ names: { /** * The name of the kind with proper casing, e.g. "Component". */ kind: string; /** * The singular form of the kind name, e.g. "component". Specify this if you * want to override the default value. */ singular?: string; /** * The plural form of the kind name, e.g. "components". Specify this if you * want to override the default value. */ plural?: string; }; /** * A short description of the kind. Specify this if you want to override the * default value. */ description?: string; /** * Update one or more versions of the kind's actual schema shape. */ versions?: CatalogModelUpdateKindVersionDefinition[]; } /** * The definition of updates to a specific version of a catalog model kind. * * @alpha */ interface CatalogModelUpdateKindVersionDefinition { /** * The specific version name or names to update, e.g. "v1alpha1" or * ["v1alpha1", "v1beta1"]. */ name: string | string[]; /** * The spec type or types that this version update applies to. */ specType?: string | string[]; /** * A short description of this particular version (and type, where * applicable). Specify this if you want to override the default value. */ description?: string; /** * The fields that shall be used to generate relations, if any. Specify this * if you want to override the default value. */ relationFields?: CatalogModelKindRelationFieldDefinition[]; /** * The JSON schema to deep merge with the existing schema for this version. */ schema?: { jsonSchema: JsonObject; }; } /** * The definition of updates to a catalog model label. * * @alpha */ interface CatalogModelUpdateLabelDefinition { /** * The name of the label, e.g. "backstage.io/source-location". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the label. */ description?: string; /** * The JSON schema that values of this label must conform to. * * @remarks * * If not provided, the label is assumed to be a simple string with no * particular schema. */ schema?: { jsonSchema: JsonObject; }; } /** * The definition of a catalog model relation. * * @alpha */ interface CatalogModelUpdateRelationPairDefinition { /** * The kind(s) that this relation originates from, e.g. "Component" or * ["Component", "Resource"]. */ fromKind: string | string[]; /** * The kind(s) that this relation points to, e.g. "Group" or * ["Group", "User"]. */ toKind: string | string[]; /** * A human-readable description of the relation. Specify this if you want * to override the default value. */ description?: string; /** * The names for the forward direction (from the current entity toward the one * being referenced). */ forward: { /** * The technical type of the relation, e.g. "ownedBy" */ type: string; /** * A human-readable title for the relation type, e.g. "owned by". * Specify this if you want to override the default value. */ title?: string; }; /** * The names for the reverse direction (from the one being referenced toward * the current entity). */ reverse: { /** * The technical type of the relation, e.g. "ownerOf". Specify this if you * want to override the default value. */ type?: string; /** * A human-readable title for the relation type, e.g. "owner of". * Specify this if you want to override the default value. */ title?: string; }; } /** * The definition of updates to a catalog model tag. * * @alpha */ interface CatalogModelUpdateTagDefinition { /** * The name of the tag, e.g. "java". */ name: string; /** * A human-readable title that can be used for display purposes instead of * the technical name. */ title?: string; /** * A human-readable description of the tag. */ description?: string; } /** * A builder for catalog model layers. * * @alpha * * Plugins can use this builder to declare various contributions to the overall * catalog model, and registering the outcome with the catalog which then forms * a complete picture out of them. */ interface CatalogModelLayerBuilder { /** * Adds a new kind to the model. */ addKind(kind: CatalogModelKindDefinition): void; /** * Updates an existing kind in the model. */ updateKind(kind: CatalogModelUpdateKindDefinition): void; /** * Removes a kind entirely from the model. */ removeKind(kind: CatalogModelRemoveKindDefinition): void; /** * Adds a new relation pair to the model. */ addRelationPair(relation: CatalogModelRelationPairDefinition): void; /** * Updates an existing relation pair in the model. */ updateRelationPair(relation: CatalogModelUpdateRelationPairDefinition): void; /** * Adds a new annotation to the model. */ addAnnotation(annotation: CatalogModelAnnotationDefinition): void; /** * Updates an existing annotation in the model. */ updateAnnotation(annotation: CatalogModelUpdateAnnotationDefinition): void; /** * Removes an annotation from the model. */ removeAnnotation(annotation: CatalogModelRemoveAnnotationDefinition): void; /** * Adds a new label to the model. */ addLabel(label: CatalogModelLabelDefinition): void; /** * Updates an existing label in the model. */ updateLabel(label: CatalogModelUpdateLabelDefinition): void; /** * Removes a label from the model. */ removeLabel(label: CatalogModelRemoveLabelDefinition): void; /** * Adds a new tag to the model. */ addTag(tag: CatalogModelTagDefinition): void; /** * Updates an existing tag in the model. */ updateTag(tag: CatalogModelUpdateTagDefinition): void; /** * Removes a tag from the model. */ removeTag(tag: CatalogModelRemoveTagDefinition): void; /** * Imports all operations from another catalog model layer into this one. */ import(layer: CatalogModelLayer): void; } /** * Creates a builder for a catalog model layer. * * @alpha * @remarks * * Plugins can use the resulting builder to declare various contributions to the * overall catalog model, and registering it with the catalog which then forms a * complete picture out of them. */ declare function createCatalogModelLayerBuilder(options: { layerId: string; }): CatalogModelLayerBuilder & { build(): CatalogModelLayer; }; /** * Creates a catalog model layer using a builder pattern. * * @alpha * @remarks * * Plugins can create such catalog model layers to declare various * contributions to the overall catalog model, and registering them with the * catalog which then forms a complete picture out of them. */ declare function createCatalogModelLayer(options: { /** * The unique ID of the model layer. * * @remarks * @example `example.com/MyCustomKind` * * This identifier is used for purposes of deduplication and tracking. It is * expected to be stable and descriptive. Prefer prefixing the ID with a * matching domain name. The backstage.io domain name is reserved for use by * the Backstage project itself. */ layerId: string; builder: (model: CatalogModelLayerBuilder) => void; }): CatalogModelLayer; /** * When declaring the JSON schema model for a kind, this is the type that you * should abide by. * * @alpha * @remarks * * It forbids some patterns that would make the schema hard or impossible to * inspect / merge properly. */ interface CatalogModelKindRootSchema extends JsonObject { type: 'object'; allOf?: never; anyOf?: never; oneOf?: never; if?: never; then?: never; else?: never; not?: never; $ref?: never; properties?: undefined | { kind?: never; apiVersion?: never; metadata?: never; $ref?: never; [key: string]: undefined | { allOf?: never; anyOf?: never; oneOf?: never; if?: never; then?: never; else?: never; not?: never; $ref?: never; [key: string]: JsonValue | undefined; }; }; [key: string]: JsonValue | undefined; } /** * Options for {@link CatalogModelSource#read}. * * @alpha */ interface CatalogModelSourceReadOptions { signal?: AbortSignal; } /** * The generator returned by {@link CatalogModelSource#read}. * * @alpha */ type AsyncCatalogModelSourceGenerator = AsyncGenerator<{ data: Array<{ layer: CatalogModelLayer; }>; }, void, void>; /** * A source of catalog model layers. * * @remarks * * It is recommended to implement the `read` method as an async generator. * * @example * * ```ts * class MyCatalogModelSource implements CatalogModelSource { * async *read() { * yield { * data: [{ layer: defaultCatalogEntityModel }] * }; * } * } * ``` * * @alpha */ interface CatalogModelSource { /** * Returns a stream of layers as expressed by this particular source. */ read(options?: CatalogModelSourceReadOptions): AsyncCatalogModelSourceGenerator; } /** * A helper for creating common catalog model sources. * * @alpha */ declare class CatalogModelSources { /** * Provides the default catalog model. */ static default(): CatalogModelSource; /** * Provides a static catalog model on top of the default one (which is * included automatically). User-provided layers take precedence over the * default model when layer IDs overlap. */ static static(layers: CatalogModelLayer[]): CatalogModelSource; private constructor(); } /** * The current status of the entity, as claimed by various sources. * * @alpha */ type EntityStatus = { /** * Specific status item on a well known format. */ items?: EntityStatusItem[]; }; /** * A specific status item on a well known format. * @alpha */ type EntityStatusItem = { /** * The type of status as a unique key per source. */ type: string; /** * The level / severity of the status item. If the level is "error", the * processing of the entity may be entirely blocked. In this case the status * entry may apply to a different, newer version of the data than what is * being returned in the catalog response. */ level: EntityStatusLevel; /** * A brief message describing the status, intended for human consumption. */ message: string; /** * An optional serialized error object related to the status. */ error?: SerializedError; }; /** * Each entity status item has a level, describing its severity. * @alpha */ type EntityStatusLevel = 'info' | 'warning' | 'error'; /** * A version of the `Entity` type that contains unstable alpha fields. * * @remarks * * Available via the `@backstage/catalog-model/alpha` import. * * @alpha */ interface AlphaEntity extends Entity { /** * The current status of the entity, as claimed by various sources. * * The keys are implementation defined and the values can be any JSON object * with semantics that match that implementation. */ status?: EntityStatus; } /** * The default catalog entity model, containing all built-in Backstage entity * kinds, relations, and annotations. * * @alpha */ declare const defaultCatalogEntityModel: CatalogModelLayer; export { CatalogModelSources, compileCatalogModel, createCatalogModelLayer, createCatalogModelLayerBuilder, defaultCatalogEntityModel }; export type { AlphaEntity, AsyncCatalogModelSourceGenerator, CatalogModel, CatalogModelAnnotationDefinition, CatalogModelAnnotationSummary, CatalogModelKind, CatalogModelKindDefinition, CatalogModelKindRelationFieldDefinition, CatalogModelKindRootSchema, CatalogModelKindSummary, CatalogModelKindVersionDefinition, CatalogModelLabelDefinition, CatalogModelLabelSummary, CatalogModelLayer, CatalogModelLayerBuilder, CatalogModelRelation, CatalogModelRelationPairDefinition, CatalogModelRelationSummary, CatalogModelRemoveAnnotationDefinition, CatalogModelRemoveKindDefinition, CatalogModelRemoveLabelDefinition, CatalogModelRemoveTagDefinition, CatalogModelSource, CatalogModelSourceReadOptions, CatalogModelTagDefinition, CatalogModelTagSummary, CatalogModelUpdateAnnotationDefinition, CatalogModelUpdateKindDefinition, CatalogModelUpdateKindVersionDefinition, CatalogModelUpdateLabelDefinition, CatalogModelUpdateRelationPairDefinition, CatalogModelUpdateTagDefinition, EntityStatus, EntityStatusItem, EntityStatusLevel };