Entity Kinds

/**
 * A Component entity represents a software component, such as a service or application
 */
interface ComponentEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Component';
  spec: {
    /** The type of component (e.g., 'service', 'website', 'library') */
    type: string;
    /** The lifecycle stage (e.g., 'experimental', 'production', 'deprecated') */
    lifecycle: string;
    /** The owner of the component (user or group entity reference) */
    owner: string;
    /** Optional reference to a parent component this is part of */
    subcomponentOf?: string;
    /** Optional list of APIs that this component provides */
    providesApis?: string[];
    /** Optional list of APIs that this component consumes */
    consumesApis?: string[];
    /** Optional list of other entities this component depends on */
    dependsOn?: string[];
    /** Optional list of other entities that depend on this component */
    dependencyOf?: string[];
    /** Optional reference to the system this component belongs to */
    system?: string;
  };
}

/** Type alias for backwards compatibility */
type ComponentEntity = ComponentEntityV1alpha1;

/** Schema validator for Component entities */
const componentEntityV1alpha1Validator: KindValidator;

import { ComponentEntity } from "@backstage/catalog-model";

const myService: ComponentEntity = {
  apiVersion: "backstage.io/v1alpha1",
  kind: "Component",
  metadata: {
    name: "user-service",
    namespace: "default",
    title: "User Management Service",
    description: "REST API for user management operations"
  },
  spec: {
    type: "service",
    lifecycle: "production",
    owner: "team-backend",
    providesApis: ["user-api"],
    consumesApis: ["notification-api"],
    system: "user-management-system"
  }
};

/**
 * An API entity represents an interface that components can provide or consume
 */
interface ApiEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'API';
  spec: {
    /** The type of API (e.g., 'openapi', 'grpc', 'graphql') */
    type: string;
    /** The lifecycle stage of the API */
    lifecycle: string;
    /** The owner of the API (user or group entity reference) */
    owner: string;
    /** The API definition (OpenAPI spec, proto file, etc.) */
    definition: string;
    /** Optional reference to the system this API belongs to */
    system?: string;
  };
}

/** Type alias for backwards compatibility */
type ApiEntity = ApiEntityV1alpha1;

/** Schema validator for API entities */
const apiEntityV1alpha1Validator: KindValidator;

import { ApiEntity } from "@backstage/catalog-model";

const userApi: ApiEntity = {
  apiVersion: "backstage.io/v1alpha1",
  kind: "API",
  metadata: {
    name: "user-api",
    title: "User Management API",
    description: "REST API for user CRUD operations"
  },
  spec: {
    type: "openapi",
    lifecycle: "production",
    owner: "team-backend",
    definition: "$text:https://user-service.example.com/openapi.yaml",
    system: "user-management-system"
  }
};

/**
 * A System entity represents a collection of resources and components
 */
interface SystemEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'System';
  spec: {
    /** The owner of the system (user or group entity reference) */
    owner: string;
    /** Optional reference to the domain this system belongs to */
    domain?: string;
    /** Optional type classification for the system */
    type?: string;
  };
}

/** Type alias for backwards compatibility */
type SystemEntity = SystemEntityV1alpha1;

/** Schema validator for System entities */
const systemEntityV1alpha1Validator: KindValidator;

/**
 * A Domain entity represents a business domain or capability area
 */
interface DomainEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'Domain';
  spec: {
    /** The owner of the domain (user or group entity reference) */
    owner: string;
    /** Optional reference to a parent domain */
    subdomainOf?: string;
    /** Optional type classification for the domain */
    type?: string;
  };
}

/** Type alias for backwards compatibility */
type DomainEntity = DomainEntityV1alpha1;

/** Schema validator for Domain entities */
const domainEntityV1alpha1Validator: KindValidator;

/**
 * A User entity represents a person, such as an employee or contractor
 */
interface UserEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'User';
  spec: {
    /** Optional profile information */
    profile?: {
      /** Display name for the user */
      displayName?: string;
      /** Email address */
      email?: string;
      /** Profile picture URL */
      picture?: string;
    };
    /** Optional list of groups this user belongs to */
    memberOf?: string[];
  };
}

/** Type alias for backwards compatibility */
type UserEntity = UserEntityV1alpha1;

/** Schema validator for User entities */
const userEntityV1alpha1Validator: KindValidator;

/**
 * A Group entity represents a team, business unit, or other organizational entity
 */
interface GroupEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'Group';
  spec: {
    /** The type of group (e.g., 'team', 'business-unit', 'product-area') */
    type: string;
    /** Optional profile information */
    profile?: {
      /** Display name for the group */
      displayName?: string;
      /** Contact email for the group */
      email?: string;
      /** Group picture or logo URL */
      picture?: string;
    };
    /** Optional reference to parent group */
    parent?: string;
    /** List of child groups */
    children: string[];
    /** Optional list of group members (user entities) */
    members?: string[];
  };
}

/** Type alias for backwards compatibility */
type GroupEntity = GroupEntityV1alpha1;

/** Schema validator for Group entities */
const groupEntityV1alpha1Validator: KindValidator;

/**
 * A Resource entity represents an infrastructure resource
 */
interface ResourceEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'Resource';
  spec: {
    /** The type of resource (e.g., 'database', 'queue', 'storage') */
    type: string;
    /** The owner of the resource (user or group entity reference) */
    owner: string;
    /** Optional list of other entities this resource depends on */
    dependsOn?: string[];
    /** Optional reference to the system this resource belongs to */
    system?: string;
  };
}

/** Type alias for backwards compatibility */
type ResourceEntity = ResourceEntityV1alpha1;

/** Schema validator for Resource entities */
const resourceEntityV1alpha1Validator: KindValidator;

/**
 * A Location entity represents a location where catalog data can be found
 */
interface LocationEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
  kind: 'Location';
  spec: {
    /** Optional type of location (e.g., 'url', 'file') */
    type?: string;
    /** Optional single target location */
    target?: string;
    /** Optional list of target locations */
    targets?: string[];
    /** Optional presence requirement ('required' or 'optional') */
    presence?: 'required' | 'optional';
  };
}

/** Type alias for backwards compatibility */
type LocationEntity = LocationEntityV1alpha1;

/** Schema validator for Location entities */
const locationEntityV1alpha1Validator: KindValidator;

/**
 * Interface for entity kind validators
 */
interface KindValidator {
  /** Check if an entity matches this kind's schema */
  check(entity: Entity): Promise<boolean>;
}

import { 
  ComponentEntity, 
  ApiEntity, 
  SystemEntity,
  componentEntityV1alpha1Validator 
} from "@backstage/catalog-model";

// Creating a complete system with components and APIs
const system: SystemEntity = {
  apiVersion: "backstage.io/v1alpha1",
  kind: "System",
  metadata: {
    name: "user-management-system",
    title: "User Management System"
  },
  spec: {
    owner: "team-platform",
    domain: "user-services"
  }
};

// Validating entities
async function validateComponent(entity: unknown) {
  const isValid = await componentEntityV1alpha1Validator.check(entity as Entity);
  if (isValid) {
    console.log("Component entity is valid");
  } else {
    console.error("Component entity validation failed");
  }
}